DATA-1102: add description/contributing to README and clean up Makefile (#263)

Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>

Author: mcous

Makefile

@@ -1,18 +1,22 @@
-TOOL_BIN = bin/gotools/$(shell uname -s)-$(shell uname -m)
+PROTO_FILES := $(shell find proto/ -type f -name '*.proto')
 
-PATH_WITH_TOOLS="`pwd`/$(TOOL_BIN):`pwd`/node_modules/.bin:${PATH}"
+export GOBIN := $(shell pwd)/bin/gotools/$(shell uname -s)-$(shell uname -m)
+export PATH := $(GOBIN):$(shell npm root)/.bin:$(PATH)
 
-PROTO_FILES=$(shell find proto/ -type f -name '*.proto')
+.PHONY: all
+all: clean dist/buf
 
+.PHONY: setup
 setup:
 	bash etc/setup.sh
 
-clean-all:
+.PHONY: clean
+clean:
 	git clean -fxd
 
 dist/tool-install: Makefile
 	npm ci --audit=false
-	GOBIN=`pwd`/$(TOOL_BIN) go install google.golang.org/protobuf/cmd/protoc-gen-go \
+	go install google.golang.org/protobuf/cmd/protoc-gen-go \
 		github.com/bufbuild/buf/cmd/protoc-gen-buf-breaking \
 		github.com/bufbuild/buf/cmd/protoc-gen-buf-lint \
 		github.com/pseudomuto/protoc-gen-doc/cmd/protoc-gen-doc \
@@ -26,23 +30,26 @@ dist/tool-install: Makefile
 	mkdir -p dist
 	touch dist/tool-install
 
+.PHONY: dist/buf
 dist/buf: dist/buf-go dist/buf-web
 
 dist/buf-go: dist/tool-install $(PROTO_FILES)
-	PATH=$(PATH_WITH_TOOLS) buf lint
-	PATH=$(PATH_WITH_TOOLS) buf format -w
-	PATH=$(PATH_WITH_TOOLS) buf generate --template ./proto/viam/buf.gen.yaml
-	PATH=$(PATH_WITH_TOOLS) buf generate --template ./proto/viam/buf.gen.tagger.yaml
+	buf lint
+	buf format -w
+	buf generate --template ./proto/viam/buf.gen.yaml
+	buf generate --template ./proto/viam/buf.gen.tagger.yaml
 	touch dist/buf-go
 
 dist/buf-web: dist/tool-install $(PROTO_FILES)
-	PATH=$(PATH_WITH_TOOLS) buf lint
-	PATH=$(PATH_WITH_TOOLS) buf format -w
-	PATH=$(PATH_WITH_TOOLS) buf generate --template ./proto/viam/buf.gen.web.yaml
-	PATH=$(PATH_WITH_TOOLS) buf generate --timeout 5m --template ./proto/viam/buf.gen.web.yaml buf.build/googleapis/googleapis
+	buf lint
+	buf format -w
+	buf generate --template ./proto/viam/buf.gen.web.yaml
+	buf generate --timeout 5m --template ./proto/viam/buf.gen.web.yaml buf.build/googleapis/googleapis
+	touch dist/buf-web
 
+.PHONY: lint
 lint: dist/tool-install
-	PATH=$(PATH_WITH_TOOLS) buf lint
-	PATH=$(PATH_WITH_TOOLS) buf format -w
-	export pkgs=`go list -f '{{.Dir}}' ./... | grep -v gen | grep -v proto` && echo "$$pkgs" | xargs go vet -vettool=$(TOOL_BIN)/combined
-	export GOGC=50 pkgs=`go list -f '{{.Dir}}' ./... | grep -v gen | grep -v proto` && echo "$$pkgs" | xargs $(TOOL_BIN)/golangci-lint run $(LINT_BUILD_TAGS) -v --fix --config=./etc/.golangci.yaml
+	buf lint
+	buf format -w
+	export pkgs=`go list -f '{{.Dir}}' ./... | grep -v gen | grep -v proto` && echo "$$pkgs" | xargs go vet -vettool=`which combined`
+	export GOGC=50 pkgs=`go list -f '{{.Dir}}' ./... | grep -v gen | grep -v proto` && echo "$$pkgs" | xargs golangci-lint run $(LINT_BUILD_TAGS) -v --fix --config=./etc/.golangci.yaml

README.md

@@ -1,6 +1,23 @@
 # API
 
+Protobuf definitions for Viam's public-facing API.
+
+## Contributing
+
+### Development
+
+- `make setup` - Setup your development environment
+- `make all` - Clean and build the Go and web generated libraries
+- `make dist/buf` - Build the Go and web generated libraries without cleaning
+- `make clean` - Clean tool cache
+
+### Submitting PRs for Protobuf Changes
+
+- Only submit PRs with changes to `.proto` files, CI will handle generating other files
+- Do not make breaking changes to APIs if it can be avoided
+
 ## License
+
 Copyright 2022 Viam Inc.
 
 Apache 2.0 - See [LICENSE](https://github.com/viamrobotics/api/blob/main/LICENSE) file