diff --git a/docs/README.md b/docs/README.md index f0915bbb..9ee9327e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -383,6 +383,8 @@ not have any breaking changes on a given major version, with some exceptions: See [development.md](development.md) for concerns related to Prototool development. +See [maintenance.md](maintenance.md) for maintenance-related tasks. + ## FAQ See [faq.md](faq.md) for answers to frequently asked questions. diff --git a/docs/development.md b/docs/development.md index e0d05c15..272a71d4 100644 --- a/docs/development.md +++ b/docs/development.md @@ -34,12 +34,4 @@ To use the locally-installed tools on your command line: ## Maintainers -See [release.md](release.md) for the release process. - -See https://github.com/uber/prototool/pull/417 for an example of how to update the default version -of `protoc`. Note that `etc/config/example/prototool.yaml` is automatically updated once you -update `DefaultProtocVersion` in `internal/vars/vars.go` and you run `make generate`. - -See https://github.com/uber/prototool/pull/418 for an example of updating versions of dependencies. - -See https://github.com/uber/prototool/pull/437 for an example of updating versions for Docker. +See [maintenance.md](maintenance.md) for maintenance-related tasks. diff --git a/docs/docker.md b/docs/docker.md index a57bc601..d35de646 100644 --- a/docs/docker.md +++ b/docs/docker.md @@ -3,10 +3,9 @@ [Back to README.md](README.md) We provide a Docker image with `prototool`, `protoc`, and common Protobuf plugins pre-installed. -Most plugins are compressed with [UPX](https://github.com/upx/upx). As of this writing, the resulting -image is around 79MB. This provides a consistent environment to generate your Protobuf stubs. - -This is in early development. +Most plugins are compressed with [UPX](https://github.com/upx/upx). As of this writing, the +resulting image is around 58MB. This provides a consistent environment to generate your Protobuf +stubs. ## Docker Hub @@ -14,7 +13,8 @@ This image is hosted at [hub.docker.com/r/uber/prototool](https://hub.docker.com ## Usage -Bind your input directory as a volume to `/work`, and call your command, for example `prototool generate`: +Bind your input directory as a volume to `/work`, and call your command, for example +`prototool generate`: ``` docker run -v "$(pwd):/work" uber/prototool:latest prototool generate @@ -24,8 +24,11 @@ You can build on top of this image as well if you have custom requirements. ## Included -The following libraries are included. This is not meant to be exhaustive - these represent our view of the most -commonly-used, stable, maintained libraries. +The following libraries are included. This is not meant to be exhaustive - these represent our view +of the most commonly-used, stable, maintained libraries. If you think another library should be +included, propose it in a GitHub issue and we will evaluate it, however in general we do not want +to add additional plugins - our recommendation is to instead build your own image based on +`uber/prototool` that adds plugins you require. | Name | Version | Binaries | | --- | --- | --- | @@ -39,30 +42,20 @@ commonly-used, stable, maintained libraries. | [twirp] | 5.7.0 | protoc-gen-twirp
protoc-gen-twirp_python | | [yarpc] | 1.37.2 | protoc-gen-yarpc-go | -The Well-Known Types are copied to `/usr/include`. The packages `bash`, `curl`, and `git` are also installed. - -If you think another library should be included, propose it in a GitHub issue and we will evaluate it. +The Well-Known Types are copied to `/usr/include`. The packages `bash`, `curl`, and `git` are also +installed. ## Versioning -Images are pushed for every commit to the dev branch as the tags `uber/prototool:dev, uber:prototool:latest`, and -every minor release starting with `v1.4.0` will have a tag e.g. `uber/prototool:1.4.0`. Note that as opposed -to the rest of Prototool, there is no breaking change guarantee between minor releases - we do not account -for breaking changes in libraries we provide within this image, and will update them regularly on `dev`. -We recommend pinning to one of the minor release Docker image tags once they are available. +Images are pushed for every commit to the dev branch as the tags `uber/prototool:dev`, +`uber:prototool:latest`, and every minor release starting with `v1.4.0` has a tag e.g. +`uber/prototool:1.4.0`. Note that as opposed to the rest of Prototool, there is no breaking change +guarantee between minor releases - we do not account for breaking changes in libraries we provide +within this image, and will update them regularly on `dev`. We recommend pinning to one of the +minor release Docker image tags. ## Development -To update the Docker image, edit the [Dockerfile](../Dockerfile). - -Note that for version changes, the versions are copied in four places: once for each layer in the -Dockerfile (sharing these is harder than you think), once in [etc/docker/testing/bin/test.sh](../etc/docker/testing/bin/test.sh), -and once in this documentation. - -See https://github.com/uber/prototool/pull/437 for an example of updating versions. - -Updates of `protobuf` and `grpc` must match the current versions for `alpine:edge` for now. See [here](https://pkgs.alpinelinux.org/packages?name=protobuf&branch=edge&repo=main&arch=x86_64) and [here](https://pkgs.alpinelinux.org/packages?name=grpc&branch=edge&repo=testing&arch=x86_64) for the current versions. - Local development commands: ``` @@ -76,6 +69,10 @@ make dockerall The test files are in [etc/docker/testing](../etc/docker/testing). +## Maintenance + +See [maintenance.md](maintenance.md) for maintenance-related information. + [protoc]: https://github.com/protocolbuffers/protobuf [grpc]: https://github.com/grpc/grpc [golang/protobuf]: https://github.com/golang/protobuf diff --git a/docs/maintenance.md b/docs/maintenance.md new file mode 100644 index 00000000..85bded76 --- /dev/null +++ b/docs/maintenance.md @@ -0,0 +1,45 @@ +# Maintenance + +[Back to README.md](README.md) + +## Releasing a new version + +See [release.md](release.md) for the release process. + +## Updating the default version of protoc + +Check https://github.com/protocolbuffers/protobuf/releases regularly for new releases. A release +that can be used for Prototool must include `protoc-VERSION-linux-x86_64.zip` and +`protoc-VERSION-osx-x86_64.zip`, which small releases sometimes do not. + +The following files need to be updated: + +- All files in `docs` that contain the current `protoc` version. As of this writing, this is + `docs/README.md`, `docs/faq.md`, and `docs/protoc.md`. +- `internal/vars/vars.go` +- `example/proto/prototool.yaml` + +Once these files are updated, run `make generate`. Do not manually update +`etc/config/example/prototool.yaml` as this will be automatically updated with `make generate`. + +See https://github.com/uber/prototool/pull/417 for an example. + +## Updating dependencies + +See https://github.com/uber/prototool/pull/418 for an example of updating versions of dependencies. + +## Updating Docker image dependencies + +To update the Docker image, edit the [Dockerfile](../Dockerfile). + +Note that for version changes, the versions are copied in four places: once for each layer in the +Dockerfile (sharing these is harder than you think), once in +[etc/docker/testing/bin/test.sh](../etc/docker/testing/bin/test.sh), and once in +[docker.md](docker.md). + +Updates of `protobuf` and `grpc` must match the current versions for `alpine:edge` for now. See +[here](https://pkgs.alpinelinux.org/packages?name=protobuf&branch=edge&repo=main&arch=x86_64) and +[here](https://pkgs.alpinelinux.org/packages?name=grpc&branch=edge&repo=testing&arch=x86_64) for +the current versions. + +See https://github.com/uber/prototool/pull/437 for an example. diff --git a/etc/bin/brewgen.sh b/etc/bin/brewgen.sh index e694b4e2..df74c94b 100644 --- a/etc/bin/brewgen.sh +++ b/etc/bin/brewgen.sh @@ -1,5 +1,9 @@ #!/bin/sh +#################################################################################### +##### ** THIS SCRIPT SHOULD ONLY BE CALLED BY THE CORRESPONDING MAKE TARGET ** ##### +#################################################################################### + set -eu DIR="$(cd "$(dirname "${0}")/../.." && pwd)" diff --git a/etc/bin/grpcgen.sh b/etc/bin/grpcgen.sh index abfe54d9..7ad8f990 100644 --- a/etc/bin/grpcgen.sh +++ b/etc/bin/grpcgen.sh @@ -1,5 +1,9 @@ #!/bin/bash +#################################################################################### +##### ** THIS SCRIPT SHOULD ONLY BE CALLED BY THE CORRESPONDING MAKE TARGET ** ##### +#################################################################################### + set -euo pipefail DIR="$(cd "$(dirname "${0}")/../.." && pwd)" @@ -10,7 +14,7 @@ cd "${DIR}" check_which() { if ! command -v "${1}" >/dev/null 2>/dev/null; then echo "${1} is not installed" >&2 - exit1 + exit 1 fi } diff --git a/etc/bin/releasegen.sh b/etc/bin/releasegen.sh index f698004a..35399760 100644 --- a/etc/bin/releasegen.sh +++ b/etc/bin/releasegen.sh @@ -1,5 +1,9 @@ #!/bin/bash +#################################################################################### +##### ** THIS SCRIPT SHOULD ONLY BE CALLED BY THE CORRESPONDING MAKE TARGET ** ##### +#################################################################################### + set -euo pipefail DIR="$(cd "$(dirname "${0}")/../.." && pwd)" diff --git a/internal/reflect/proto/prototool.yaml b/internal/reflect/proto/prototool.yaml index e4add002..f44c6110 100644 --- a/internal/reflect/proto/prototool.yaml +++ b/internal/reflect/proto/prototool.yaml @@ -1,5 +1,3 @@ -protoc: - version: 3.7.1 lint: group: uber2 generate: