Skip to content

Decide and document crate versioning policy + release runbook #10

@iainmcgin

Description

@iainmcgin

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions