ADR: Release every main commit from its CI run¶
Record¶
| Field | Value |
|---|---|
| Date | 2026-08-17 |
| Status | Accepted |
| Owner | Maintainers |
| Author | Danny Sauer |
| Scope | How versions are chosen and how release artifacts are built and published. It doesn't make an alpha a supported production release. |
| Related | Architecture: CI and release path, maintainer guide, Debian slim runtime |
| Implementation | PR #146; release-channel trailers in PR #168 |
| Revisit when | The project has a second maintainer or a supported stable release line. |
Business driver¶
With one maintainer, every manual release step is a step that gets skipped or done inconsistently. Each release took a preparation pull request and a signed tag, then a separate workflow rebuilt the artifacts. That rebuild couldn't prove it contained the bytes CI had tested, and its long build chain often failed late.
Constraints¶
- A release must come from the exact commit that passed the required checks.
- Signatures, attestations, and provenance must bind to that tested commit.
- A partial or repeated run must never publish a second, conflicting release.
Decision¶
Y statement: We will publish a release from every successful main CI run,
inside that run, with the version derived from Git tags and commit messages,
because a release built anywhere else can't prove it matches what CI tested,
so no one maintains a release pull request, version file, or hand-made tag.
The decision has these boundaries:
- Alpha releases increment their numeric suffix. Stable releases use conventional commits to choose the bump.
- A terminal
Release-Channel: alphaorRelease-Channel: stableGit trailer is the only way to change channel. A malformed or repeated trailer fails release planning. - The published, immutable GitHub release is the completion record. A rerun reuses matching state and refuses a collision.
- Python archives are GitHub release assets; the project doesn't publish to PyPI.
Consequences¶
- One release can cover two closely spaced merges, because queued runs may start out of order and the older run then steps aside.
- Channel changes happen in commit history, so a squash merge must keep the trailer in the final commit message.
- Every merge to
mainships an artifact, somainhas to stay releasable.
Alternatives considered¶
Keep the current approach¶
Before this decision, a maintainer ran tools/prepare_prerelease.py to open a
pull request that bumped pyproject.toml, uv.lock, and CHANGELOG.md, then
pushed a signed tag that started a separate release workflow. That workflow
rebuilt the artifacts outside the CI run that tested the commit, through a
bespoke wheelhouse, a cross-architecture evidence spine, and raw OCI transport.
Small changes often failed late, and the maintenance cost outgrew the
application.
Automate release pull requests¶
A tool such as Release Please would open the version-bump pull request automatically. That removes the script, but each release still needs a second merge and a version file kept in sync, and the release still rebuilds artifacts outside the CI run that tested them.