Releases are derived from commit history by release-please. Nobody bumps versions or writes changelogs by hand.
PR (conventional title) ──squash──▶ master ──▶ release-please updates the "release PR"
│ merge when ready to ship
▼
tag vX.Y.Z + GitHub Release + CHANGELOG.md
│
▼
publish jobs (release.yml, `release_created`)
- Every merge to
masterruns.github/workflows/release.yml. - release-please opens or updates a single PR titled
chore(master): release X.Y.Zcontaining the version bump and the generated changelog. - The release workflow regenerates
THIRD_PARTY_NOTICES.txton the release PR's branch using the pinned Rust toolchain and cargo-about. It commits the generated file when needed, then validates the exact prepared commit through CI and all four installer builds. The Conventional Commits status records successful CI on that SHA; Release validation records the combined CI and installer result. - Merge the release PR only after Release validation succeeds. Merging that PR
is the release: it creates the
vX.Y.Ztag and the GitHub Release. - Artifact build/publish jobs run only when
release_created == 'true'. They build the immutable release tag and attach its installers.
Release cadence is a human decision — merge the release PR whenever master holds something worth shipping.
SemVer 2.0. The bump is computed from commit types since the last tag:
| Commits contain | 0.y.z |
≥ 1.0.0 |
|---|---|---|
BREAKING CHANGE / ! |
minor | major |
feat |
minor | minor |
fix, perf, revert |
patch | patch |
| anything else only | no release | no release |
While on 0.y.z the public surface is considered unstable. Going to 1.0.0 is an explicit decision, made with a Release-As: 1.0.0 footer on a commit to master.
- Force a version: empty commit with a
Release-As: X.Y.Zfooter. - Fix a changelog entry: edit the merged PR's description and add a
BEGIN_COMMIT_OVERRIDE/END_COMMIT_OVERRIDEblock; release-please re-reads it. - Hotfix an old release: branch
release/X.Yfrom the tag, cherry-pick thefix:commit, and add that branch to the workflow triggers. Don't create these branches preemptively. - Pre-releases: set
"prerelease": trueand"prerelease-type": "rc"inrelease-please-config.jsonon the branch that should produceX.Y.Z-rc.N.
| File | Purpose |
|---|---|
release-please-config.json |
release strategy and changelog sections |
.release-please-manifest.json |
last released version (managed by the bot) |
version.txt |
current version (managed by the bot) |
Cargo.toml, Cargo.lock |
nocterm package version (managed by the bot) |
CHANGELOG.md |
generated on first release |
release-type is simple (bumps version.txt); extra-files also bumps the root nocterm package in Cargo.toml and Cargo.lock, so CARGO_PKG_VERSION and the Windows file version match the release. Internal crates stay at 0.0.0.
The Cargo.lock TOML selector accesses @.name.value because release-please's
parser wraps scalar values with source-location metadata. Keep the lockfile
selector regression check when upgrading release-please. License fingerprints
continue to cover complete Cargo files, vendored sources, assets, and packaging
inputs; release version changes require notice regeneration too.
- Settings → Actions → General → enable Allow GitHub Actions to create and approve pull requests.
- Settings → General → Pull Requests: allow squash merging only, default commit message Pull request title.
- Branch protection on
master: require PRs, theConventional Commitscheck, and linear history. Review Release validation before merging a release PR; do not require this release-only status on every development PR. - PRs opened or updated with
GITHUB_TOKENdo not trigger pull-request workflows. The release workflow explicitly calls reusable CI and Package workflows for the prepared SHA and publishes Conventional Commits and Release validation on that SHA. It needscontents: write,pull-requests: write, andstatuses: write; no separate PAT is needed for preparation and validation. Reusable workflow checks appear on the triggering workflow, while commit statuses appear on the release PR. The bot PR's Conventional Commits status succeeds only after the complete reusable CI workflow, including its title and commit checks, succeeds.
A GitHub Release can exist even if its installer jobs fail. Inspect the Package
jobs and release assets before announcing a release. The historical v1.1.0
release has no installers because its lockfile and license notices were stale.
Keep its tag unchanged; release the repaired source through the next validated
release PR instead of attaching installers built from a different source tree.
If only an external service failure interrupted publication, retry the failed Release workflow jobs. Artifact builds must still use the original release tag; never move that tag to a newer commit.