connectrpc / connectrpc/connect-rust
Decide and document crate versioning policy + release runbook
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 509
- Forks
- 66
- Avg merge
- 2d 8h
- Merged PRs (30d)
- 10
Description
v0.2.1 shipped with connectrpc at 0.2.1 while connectrpc-codegen
and connectrpc-build stayed at 0.2.0 (nothing changed in them). Then
the v0.2.1 tag triggered a binary release - but those binaries come
from connectrpc-codegen, which didn't change, so they're functionally
identical to v0.2.0's.
Neither of these is wrong, but there's no written policy and the
interaction is a little awkward. This issue is for deciding and writing
it down before the next release.
The versioning question
Lockstep (bump all crates together): simpler user mental model
("use 0.2.1 everywhere"), trivially answers "which codegen works with
which runtime." prost does this. Every release is one version.
Independent (only bump what changed): semver-accurate, no zero-diff
publishes cluttering the crates.io index. tonic does this for patches,
lockstep for minor/major.
Relevant constraint: codegen emits calls to connectrpc APIs, so
there's a real coupling - a codegen bump that emits a new helper call
needs a matching runtime bump. Lockstep makes this trivially
discoverable; independent means documenting "codegen X requires
runtime >= Y" somewhere.
Relevant observation: if we want a GitHub release for every
version (discoverability, changelog visibility), and the release
workflow builds protoc-gen-connect-rust binaries from whatever's on
the tag, then a runtime-only patch under independent versioning
produces a release with redundant binaries. Lockstep sidesteps this:
every tag corresponds to a real codegen build.
The runbook question
Separately, there's no written doc for "how to cut a release" - the
sequence is publish workflow dispatch -> tag push, and the publish
workflow is idempotent so order doesn't strictly matter, but none of
that is written down outside the workflow comments themselves.
Deliverable
Probably a RELEASING.md covering both: the policy, and the steps.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reading the publish workflow comments and the documented sequence of workflow dispatch followed by a tag push. Create RELEASING.md covering the chosen crate versioning policy, codegen/runtime compatibility, and release steps, including how redundant binaries are handled.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- github-actions, rust
- Domain
- documentation, release
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100