Repository navigation
Release pipeline always bumps patch; AGENTS.md claims versions derive from commit types #54
Description
Activity
A concrete case is coming up: #53 lands as
fix!:with aBREAKING CHANGE:footer and theStatus: Break Changelabel.release.yml:49-56will still cut a patch release, and--generate-noteslists only PR titles, so the footer will not appear in the notes. Until this issue is fixed, the next release draft needs the breaking change written into the notes by hand, or a manual minor tag.Decided design (2026-10-07):
- Rule. Scan every commit since the latest
v*tag; the highest bump wins.- breaking (
type!:/type(scope)!:subject, or aBREAKING CHANGE:/BREAKING-CHANGE:footer line): minor while on 0.y, major at 1.0 and above. feat: minor.- anything else: patch.
- no tag: start from
v0.0.0. Release-As: vX.Y.Zfooter: use exactly that version. It must be well-formed and greater than the latest tag, otherwise the job fails.- Every push to
mainstill releases.
- breaking (
- Why the whole range and not only the last commit: one release can cover several merges. v0.2.25 covered fix(ts): strip dotted API-version prefixes (#52) #56 and fix: strip only numeric API-version prefixes in Go and Rust (#57) #58, because the release run for
a654ff8never reached the version job. - Notes. A generated "Breaking changes" section (subjects plus footer text) is passed to
gh release create --notes-file … --generate-notes, which prepends it to the generated notes. That replaces hand-editing, as was done for v0.2.26. - Implementation. Logic moves into
scripts/release-version.shandscripts/release-notes.sh. Tests come first inscripts/release-version_test.sh, with one case per rule row, run bymake test-releaseand a CI job.release.ymlcalls the scripts. - Docs.
docs/release-versioning.mdholds the rule table, the reasoning and the rejected alternatives. AGENTS.md step 4 points to it. - This PRs squash message carries
Release-As: v0.3.0. The merge then cuts v0.3.0, reflecting Percent-encoded container names: Go routes on the decoded path, Rust/TS on the raw path #53 (shipped as v0.2.26) and feat!: dockerd-parity listening socket, Unix path only #47 (shipped as v0.2.22). - Rejected alternatives: release-please / semantic-release (heavier, and they take over changelogs and PRs); correcting only AGENTS.md; and
feat→ patch below 1.0.
- Rule. Scan every commit since the latest
- added a commit that references this issue
on Oct 7, 2026 - added a commit that references this issue
on Oct 8, 2026
Problem
.github/workflows/release.yml("Bump patch version" step) unconditionally increments the patch number: every merge tomainships asvX.Y.Z+1, whatever the commit type. MeanwhileAGENTS.md(Contribution Workflow, step 4) tells contributors "The release pipeline derives version bumps from these [commit types], so the type is not cosmetic" — which is not true today.Concrete consequence: PR #47 (
feat!:— removed--listen-socket-modeandfd://socket activation, a documented breaking change with aBREAKING CHANGE:footer) shipped as v0.2.22, a patch release. The draft notes had to be hand-edited to surface the breaking change.Proposed solution
Make the version step parse the squash-commit subject since the last tag:
feat!:/BREAKING CHANGE→ minor bump while on 0.y (major once 1.0 lands),feat:→ minor, everything else → patch. Keep the rest of the pipeline unchanged. Alternatively adopt a ready-made action that implements conventional-commit semver.Alternatives considered
feat!shipping as a patch, which misleads downstream consumers about compatibility.Which implementation(s) would this affect?