semantic-release releases from main once its Checks pass; the git tag is the one version
Decided with Cansin on 2026-11-02 (grilling, noggin-27), #582. Supersedes ADR 0010’s release half: 0010 keeps the one version and the PR titles.
Release Please’s release PR only delayed releases: a draft waiting for a gate or Release Now, a release now label,
and stale merge refs (#543), on a repo where every PR already auto-merges on green. So main releases itself.
- semantic-release, its default plugins only (commit-analyzer, release-notes-generator, github;
release.config.mjs), pinned inci/package.json(ADR 0012). The conventionalcommits preset stays on 9.x while release-notes-generator bundles conventional-changelog-writer 8, which can’t render 10.x;ci/release.test.mjsrenders notes, so a bump past it fails there. TheReleaseworkflow (release.yml) runs when Checks complete for this repo’s push to main, and acts only on a success, on that push’s commit: a red main never releases. When main moved on since, semantic-release sees its commit is no longer main’s head and releases nothing; the newer commit’s run releases both. One run at a time, never cancelled. - What releases: feat, fix, perf, revert and a
!break (the conventionalcommits preset reads the title’s!). Before 1.0 a break bumps the minor and the rest the patch (releaseRules, tested inci/release.test.mjsthrough commit-analyzer itself); docs, ci, chore, build, test, style and refactor release nothing. Rules that match nothing fall through to commit-analyzer’s defaults, which release none of those types either. - A manual release (#802, Cansin 2026-11-03: one that can’t be ignored, when main never quiets down). The
Releaseworkflow’s dispatch on main, with a bump:auto(the default),patch,minorormajor. One run does it all on main’s tip at dispatch: the full Checks (checks.ymlcalled withworkflow_call, its Deploy on), then the tag and release of that same commit once they pass; a red commit never tags. While that commit is still main’s tip it releases main, as a push does. When main moved on during the run, it tags the commit it checked anyway: semantic-release releases a temporary branch at that commit (release-<run id>, deleted after, by an App token of its own with Workflows write; semantic-release’s holds contents alone), so the version math and the notes stay its own and the tag sits on a commit in main’s history. semantic-release has no force option by design, so the bump is config:release.config.mjsreads it fromRELEASE_BUMPand puts a rule matching every commit at that bump ahead of the others. commit-analyzer takes a commit’s highest match, so a forced bump is the least it releases (a forced patch over a break is still the minor);autoleaves the rules as they are, and with no commit since the last tag nothing releases, which the run’s summary says. The push-triggered release is unchanged. - The git tag is the one version.
noggin/core.pyreadsgit describe --tags:X.Y.Zon a release’s tag,X.Y.Z-N-gHASHN commits past it,0.0.0-untaggedwhere no tag is reachable (a shallow checkout). The Core’s stamp and the noggin service carry it; the service compares the base X.Y.Z. The Site’s footer links a release only on an exact tag.pyproject.tomlkeeps a placeholder0.0.0, and nothing commits back to main: no bump, no CHANGELOG.md. Each release’s notes are on its GitHub release (v0.1.0 to v0.2.5’s too). The checkouts that stamp or release fetch the tags: Release’s and Site’s whole history, a tag’s run its tag. - The bot App’s token (CONTRIBUTING.md), since a tag
GITHUB_TOKENpushes starts no workflow: the App’s tag starts Release Assets as before. Contents write only: the github plugin’s success and fail comments and itsreleasedlabel are off, so a release writes nothing on PRs or issues.
Considered options
Section titled “Considered options”- Keeping Release Please with a lighter gate: rejected, the release PR itself was the friction.
- Releasing on the push to main, before Checks: rejected, a red commit could be tagged.
- Tagging the dispatched commit by hand (
git tag,gh release create) for a forced release: rejected, the version and notes would no longer be semantic-release’s. - A forced bump that replaces the rules rather than leading them: rejected, a forced patch would then understate a break.
- Writing the version into
pyproject.toml(and a CHANGELOG.md) on release: rejected, that is a bot commit to main.
noggin v0.2.26-6-g09bf9b7 · 09bf9b7