Release pipeline always bumps patch; AGENTS.md claims versions derive from commit types

[abienkowski]

Problem

.github/workflows/release.yml ("Bump patch version" step) unconditionally increments the patch number: every merge to main ships as vX.Y.Z+1, whatever the commit type. Meanwhile AGENTS.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-mode and fd:// socket activation, a documented breaking change with a BREAKING 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

• Correcting AGENTS.md instead (document that every release is a patch bump): honest but entrenches feat! shipping as a patch, which misleads downstream consumers about compatibility.
• Full semantic-release tooling: heavier than this repo needs; the pipeline is otherwise deliberately small.

Which implementation(s) would this affect?

• Go / Rust / TypeScript
• CI / infrastructure (release.yml, AGENTS.md)

[abienkowski]

A concrete case is coming up: #53 lands as fix!: with a BREAKING CHANGE: footer and the Status: Break Change label. release.yml:49-56 will still cut a patch release, and --generate-notes lists 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.

[abienkowski]

Decided design (2026-10-07):

• Rule. Scan every commit since the latest v* tag; the highest bump wins.
  • breaking (type!: / type(scope)!: subject, or a BREAKING 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.Z footer: use exactly that version. It must be well-formed and greater than the latest tag, otherwise the job fails.
  • Every push to main still releases.
• 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 a654ff8 never 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.sh and scripts/release-notes.sh. Tests come first in scripts/release-version_test.sh, with one case per rule row, run by make test-release and a CI job. release.yml calls the scripts.
• Docs. docs/release-versioning.md holds 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.