connectrpc / connectrpc/connect-rust

Decide and document crate versioning policy + release runbook

Open
#10 5 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

documentation
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.