Skip to content

Commit

Permalink
docs: update protobuf required versions
Browse files Browse the repository at this point in the history
We document explicit versions in the dev guide, so we have a point of
reference about tooling required to perform the codegen from protobuf
definitions. We also pin the corresponding versions in CI, but that info
is harder for a human to read at a glance.
  • Loading branch information
conorsch committed Oct 17, 2023
1 parent b11ae45 commit 5640eea
Show file tree
Hide file tree
Showing 2 changed files with 11 additions and 5 deletions.
4 changes: 2 additions & 2 deletions .github/workflows/buf-pull-request.yml
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ jobs:
toolchain: stable
override: false

- uses: bufbuild/buf-setup-action@v1
- uses: bufbuild/buf-setup-action@v1.27.1
with:
buf_api_token: ${{ secrets.BUF_TOKEN }}
github_token: ${{ secrets.GITHUB_TOKEN }}
Expand All @@ -68,7 +68,7 @@ jobs:
curl -sSfL -O https://github.com/protocolbuffers/protobuf/releases/download/v${PROTOC_VERSION}/protoc-${PROTOC_VERSION}-linux-x86_64.zip
unzip protoc-${PROTOC_VERSION}-linux-x86_64.zip -d $HOME/.local
env:
PROTOC_VERSION: "23.3"
PROTOC_VERSION: "24.4"

# We exclude the proto_descriptor file from diff inspection, since
# different versions of `protoc` can generate non-substantive changes,
Expand Down
12 changes: 9 additions & 3 deletions docs/guide/src/dev/protobuf.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,20 +17,26 @@ The Rust code files are generated with our own tooling, located at `tools/proto-

The `protoc` tool is required to generate our protobuf specs via `tools/proto-compiler`.
We mandate the use of a specific major version of the `protoc` tool, to make outputs
predictable. Currently, the supported version is `23.x`. Obtain the most recent
predictable. Currently, the supported version is `24.x`. Obtain the most recent
pre-compiled binary from the [`protoc` website] for that major version.
After installing, run `protoc --version` and confirm you're running
at least `23.3` (or newer). Don't install `protoc` from package managers
at least `24.4` (or newer). Don't install `protoc` from package managers
such as `apt`, as those versions are often outdated, and will not work
with Penumbra.

To install the protoc tool from the zip file, extract it to a directory on your PATH:

```shell
unzip protoc-24.4-linux-x86_64.zip -d ~/.local/
```

## Installing buf

The `buf` tool is required to update lockfiles used for version management in
the [Buf Schema Registry](https://buf.build.penumbra-zone/penumbra). Visit
the [buf download page](https://buf.build/docs/installation/) to obtain a version.
After installing, run `buf --version` and confirm you're running at least
`1.17.0` (or newer).
`1.27.0` (or newer).

## Building protos

Expand Down

0 comments on commit 5640eea

Please sign in to comment.