Skip to content

Latest commit

 

History

History
240 lines (170 loc) · 15.9 KB

RELEASING.md

File metadata and controls

240 lines (170 loc) · 15.9 KB

Releasing vitaminc

This project uses release-plz to automate versioning, changelog generation, and publishing to crates.io.

How it works

1. You push code to main

Merge your feature/fix PRs to main as usual. Use conventional commits (feat:, fix:, etc.) — these feed into the auto-generated changelog.

Mark a breaking change with ! (feat(aead)!: ...) or a BREAKING CHANGE: footer. That marker is what puts the commit in the changelog's Breaking section and what tells release-plz the release needs a bigger version bump, so it has to be on the commit — it cannot be added later.

2. release-plz creates a release PR

On every push to main, the release-plz GitHub Action runs and creates (or updates) a release PR. This PR contains:

  • Version bumps in Cargo.toml (all 20 crates are bumped together)
  • Updated CHANGELOG.md files with entries generated by git-cliff from commit messages
  • A follow-up commit that re-syncs the lockfiles of the two test workspaces, packages/aead-napi/tests/addon and bindings/go/vcencrypt/guest, which pin the workspace crates by version and which release-plz does not update itself. .github/scripts/sync_nested_lockfiles.py does it as a text edit, so the workflow never runs cargo on the release branch while it holds a token that can push. The workflow creates that commit through GitHub's API (.github/scripts/commit_on_branch.py), so GitHub signs it as the release-plz app; main requires signed commits, and a commit pushed with git from the workflow would be unsigned
  • The same follow-up commit synchronizes managed README installation versions with the bumped manifests, using .github/scripts/sync_readme_versions.py. It covers the root README and every workspace member's README, including newly added crates
  • It also synchronizes marked MSRV values in READMEs and Rust doc comments with rust-version, using .github/scripts/sync_msrv.py

3. You check the version it picked

release-plz derives the next version from the commits since the last release, but it does not reason about where the project is heading. Two cases need a human:

  • A prerelease never graduates on its own. While the current version is a prerelease, release-plz just increments the prerelease counter — 0.2.0-pre.1 becomes 0.2.0-pre.2, and would become 0.2.0-pre.3 after that. Deciding the prerelease train has arrived and cutting 0.2.0 is a judgement call somebody has to make.
  • Breaking changes in 0.x want a minor bump (0.2.x → 0.3.0). Worth confirming the PR agrees, especially if the breaking commits weren't marked !.

To override the version, edit it on the release PR branch — not on main, where it would just change release-plz's starting point for the next calculation:

git fetch origin
git switch release-plz-<timestamp>

# The version lives in three places: the workspace manifest, the version
# requirements on internal path dependencies, and Cargo.lock. Edit only the
# manifests (perl, because `sed -i` is not portable between GNU and BSD),
# then let Cargo re-sync its own lockfile — editing Cargo.lock directly
# would also rewrite registry dependencies that share the version string.
grep -rl '<old-version>' --include='*.toml' . | xargs perl -pi -e 's/<old-version>/<new-version>/g'
cargo update --workspace --offline   # re-syncs Cargo.lock and confirms everything still resolves
python3 .github/scripts/sync_nested_lockfiles.py .   # and the two test workspaces' lockfiles
python3 .github/scripts/sync_readme_versions.py .    # and README installation versions
python3 .github/scripts/sync_msrv.py .               # and documented Rust requirements
git commit -am "chore: release <new-version> instead of <old-version>"
git push

Then retitle the PR to match. (release-plz set-version does the same job, but takes an explicit <package>@<version> for each of the 20 crates.)

The override is not durable. The next push to main makes release-plz regenerate the release branch from scratch, reverting both the version and any changelog rewriting. Merge the release PR before landing more work, or re-apply the override afterwards.

4. You rewrite the changelog

The generated entries are a per-commit transcript, not a changelog. Rewrite them before merging:

  • Breaking changes lead, prefixed **Breaking:**. git-cliff collects every !-marked commit into a Breaking section, but it uses the raw commit subject — replace that with what breaks for the caller and what they have to do about it.
  • A wire-format change states its compatibility consequence explicitly. Whether ciphertexts written by the previous version still decrypt is the one thing a reader has to act on. Put it in the entry; don't leave it to be inferred from a list of changed internals.
  • Say what is deliberately not guaranteed. If a structural property looks authenticated but isn't, the changelog is where someone learns that, not the source.
  • Write from the caller's side — what changed and why it matters, not how it was implemented.
  • Group related commits into a single entry. Five commits that landed one feature are one line.
  • Drop internal churn. cliff.toml already skips test, ci, build, style, chore and refactor commits. Anything left that only matters to contributors goes too — and note the flip side: a user-visible refactor is skipped by that filter, so it needs an entry written by hand.
  • Keep each crate's changelog about that crate. Every crate shares a version, so a commit touching one crate can surface in several changelogs. Delete what isn't about the crate whose file you're editing.
  • One line per change.

Claude or another AI tool can draft this pass, but the compatibility claims need checking against the code — they're the part people act on.

5. Merge the release PR

Once the changelog is ready, merge the release PR. This triggers the release job which:

  • Publishes all crates to crates.io
  • Creates git tags for each crate
  • Creates GitHub releases

The job runs on every push to main, but publishes only when the commit is a merged release PR (release_always = false), so nothing is published from ordinary merges.

A crate's first release

The release job publishes through crates.io trusted publishing, and crates.io lets a crate be set up for that only once it exists, so the job cannot publish a crate that has never been released. A personal token cannot finish the release either: every crate already on trusted publishing accepts new versions only from it, and refuses a token with 403 Forbidden. So a release that includes a new crate takes these steps:

  1. Merge the release PR as usual. The job publishes crates in dependency order and fails at the first new one (Trusted Publishing tokens do not support creating new crates); the crates before it are released.

  2. From the merge commit, publish only the new crates with a crates.io token of your own, in dependency order. Every dependency a new crate has must already be on crates.io at the release version; cargo publish --dry-run --locked -p <crate>, which needs no token, says whether it is. If a new crate depends on an existing crate the job has not reached yet, re-run the job after step 3 for the crates it can now publish, then come back for the rest. Make the token narrow: the publish-new scope, the crate pattern vitaminc*, and an expiry of the next day. Hand it over through the environment rather than cargo login, which would keep it in ~/.cargo/credentials.toml:

    git switch --detach <merge-commit>
    read -rs CARGO_REGISTRY_TOKEN && export CARGO_REGISTRY_TOKEN
    cargo publish --locked -p <new-crate>   # once per new crate, dependencies first
    unset CARGO_REGISTRY_TOKEN

    Do not run release-plz release with it: release-plz goes on to the existing crates, and crates.io refuses them.

  3. On crates.io, set up trusted publishing for each new crate (repository cipherstash/vitaminc, workflow release-plz.yml, environment release). Then re-run the failed Release job (gh run rerun <run-id> --failed). It skips what is already published, publishes the rest through trusted publishing, and creates their tags and GitHub releases.

  4. Tag and release each crate published in step 2. The job skips a crate that is already published and creates no tag for it, so those crates have neither. Tag the commit the other -v<version> tags name (git rev-list -n1 <another crate's tag>), and use the crate's changelog section as the notes:

    git tag -a <crate>-v<version> <commit> -m "chore: Release package <crate> version <version>"
    git push origin refs/tags/<crate>-v<version>
    gh release create <crate>-v<version> --verify-tag --title <crate>-v<version> --notes-file <notes.md> --latest=false

Configuration

README installation versions

The synchronizer reads package versions from workspace member manifests, including version.workspace = true. It requires Python 3.11 or newer and runs without Cargo or third-party Python packages. CI checks for drift with:

python3 .github/scripts/sync_readme_versions.py . --check

To update versions locally, omit --check. For a new installation example, wrap the dependency declarations in these invisible Markdown markers:

<!-- workspace-deps:start -->
```toml
[dependencies]
vitaminc = "<current manifest version>"
```
<!-- workspace-deps:end -->

Use single-line TOML assignments: simple version strings or inline tables such as { version = "...", features = ["..."] }. Renamed dependencies with a package field and inline-code declarations in prose are supported. Only workspace crate version strings change; feature flags, comments, formatting, and third-party dependency versions are preserved. CI rejects unmarked versioned workspace dependency assignments. For an intentionally historical dependency example, use <!-- workspace-deps:keep --> followed by <!-- workspace-deps:end --> instead. Ordinary historical prose and changelogs are outside this synchronization.

README discovery follows explicit package.readme paths (including workspace inheritance), otherwise README.md beside each member's manifest. Crates with readme = false or no README need no configuration. This updates existing installation examples; it does not create documentation for crates without them.

Release configuration files

File Purpose
release-plz.toml release-plz config — version groups, feature flags
cliff.toml git-cliff config — commit grouping, the Breaking section, version headings
.github/workflows/release-plz.yml GitHub Actions workflow

All crates release together

All publishable workspace crates are in a single version_group. This means every release bumps all crates to the same version, regardless of which crates had changes. This keeps version alignment simple.

Secrets

Publishing uses crates.io trusted publishing (the Release job's id-token: write permission), so the repository holds no crates.io token. The workflow authenticates to GitHub as an app, through the RELEASE_PLZ_APP_ID variable and the RELEASE_PLZ_APP_PRIVATE_KEY secret, so its pushes trigger CI.

Both jobs run in the release environment, whose deployment branch rule allows only main. RELEASE_PLZ_APP_PRIVATE_KEY is a secret of that environment, not of the repository, and every crate's trusted publisher on crates.io names the environment release. A workflow runs from whichever branch triggered it, so without these, anyone who can push a branch could run this workflow from it, read the app key, and publish any crate. Keep all three when changing the workflow: a job that needs the key or publishes must declare environment: release, and a new crate's trusted publisher must name it.

Semver checking

release-plz runs cargo-semver-checks before releasing. If you accidentally introduce a breaking change without a matching version bump, the release PR will flag it.

It baselines against the last version published to crates.io, prereleases included, and applies 0.x rules — where a breaking change needs a minor bump. So graduating 0.2.0-pre.1 to 0.2.0 can be disputed even though it's exactly what a prerelease train is for. A red check here is a question to answer, not proof of a regression.

FAQ

Does a release PR get created on every merge to main?

release-plz doesn't create a new PR each time — it updates the same open release PR. So commits accumulate in a single PR until you merge it.

Do we have to merge the release PR every time?

No. You can let changes pile up and merge the release PR whenever you're ready to cut a release. It's a standing "release when ready" PR.

What happens if we skip one?

Nothing bad. The next push to main updates the existing release PR with the additional changes. The changelog and version bump will reflect everything since the last release.

Can I edit the release PR by hand?

Yes — steps 3 and 4 both require it. But the branch is regenerated on the next push to main, and your edits go with it. Do the rewrite when you're ready to merge, not as changes land.

Minimum supported Rust version

Raise a crate's MSRV only in a minor release, never in a patch release. Record the new requirement in the release notes. Edit rust-version in the workspace or package manifest, then synchronize the documentation:

python3 .github/scripts/sync_msrv.py .
python3 .github/scripts/sync_msrv.py . --check

The script requires Python 3.11 or newer and no third-party packages. It reads the root README, workspace member READMEs (including inherited paths), and Rust doc comments under each member's src directory or custom library entry path. New members are discovered automatically. In Rust source, only //! and /// lines are edited; code and ordinary comments are left alone.

Mark each current Rust requirement with an invisible, single-line pair:

Requires Rust <!-- msrv:vitaminc-protected -->**1.88.0**<!-- /msrv -->.
//! Requires Rust <!-- msrv:vitaminc-random-derives -->**1.88.0**<!-- /msrv -->.

Use workspace for the workspace floor, a package name for that crate's effective rust-version (including workspace inheritance), or a declared package/feature scenario. Plain, bold, and backtick-formatted versions are supported. For historical claims, use <!-- msrv:keep -->...<!-- /msrv -->. Unmarked version numbers on lines mentioning Rust, MSRV, or rust-version are rejected in these documentation files. The script validates every file before writing any changes; --check reports drift without writing.

CI gets its compiler versions from sync_msrv.py . --matrix. It groups every workspace member, including unpublished test fixtures, by its declared MSRV and runs cargo check --locked --all-targets for each group. Every member must declare rust-version or inherit it. There are no compiler-version literals to update in the MSRV jobs.

Features that raise a crate's floor have an explicit scenario in its manifest:

[package.metadata.msrv.features]
aws-kms = ["vitaminc-kms"]

For the vitaminc facade, this defines the vitaminc/aws-kms documentation source and an additional CI build with --no-default-features --features aws-kms. Its Rust requirement is the highest declared MSRV among the facade and the listed workspace dependencies. These scenarios do not infer registry dependency requirements; compiling the locked graph checks that the declared floor works.

The release workflow runs the same synchronizer from trusted main against the release worktree as data, alongside README version and lockfile updates. No Cargo commands or code from the release branch are executed by this step.

Dependency updates in patch releases must continue to build at the existing MSRV; constrain or defer updates that raise it. Synchronization does not enforce the minor-release-only rule; confirm the release version and notes during review.