Canonical version+hash identity and PR-driven release notes - #113
Merged
Conversation
… notes Two follow-ups to the release machinery, both requested for the NEXT release rather than needed for the first. 1. VERSION BOUND TO BUILD HASH, canonically. `keel --version` already showed both; it now reports them as semver build metadata -- `keel 0.1.0+c11baba726af [release]` -- via BuildInfo.full_version. The version alone is ambiguous (many commits share a version between bumps); the `+<commit>` form is the string that actually pins which code is running, and `+` is the separator tooling recognises. 2. RELEASE NOTES GENERATED FROM MERGED PRs since the previous tag, grouped by label (.github/release.yml). The release workflow calls GitHub's generate-notes API, composes it under the build-hash line and the install block, and publishes via --notes-file. First release has no previous tag and generates from the start of history. Plus docs/RELEASING.md: the version-bump-in-a-PR flow, the label -> section mapping (so notes are useful, PRs must be labelled), and the issue/commit convention to ADOPT from the next cycle -- open an issue per unit of work, reference it with `Closes #N` so GitHub links the commit and it flows into the notes. The mechanics are in place; the discipline is a process commitment that only works if followed. Verified: full_version forms (release/checkout/unknown) tested; the note-composition shell logic proven with a stubbed gh (build-hash line + install block + generated change list, in order); both YAML files parse. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
eaitbrahim
added a commit
that referenced
this pull request
Jul 20, 2026
docs: correct RELEASING.md — issues not enforced (missed #113's merge)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Two follow-ups to the release machinery (#112), both for the next release rather than needed for the first.
1. Version bound to the build hash, canonically
keel --versionalready showed both; it now reports them as semver build metadata:0.1.0+c11baba726afis the canonical "which build is this" string. The version alone is ambiguous — many commits share a version between bumps — so the+<commit>form is what actually pins the running code, and+is the separator tooling recognises (BuildInfo.full_version).2. Release notes generated from merged PRs
The change list in each release is now auto-generated from the PRs merged since the previous tag, grouped by label via
.github/release.yml. The workflow calls GitHub's generate-notes API, composes it under the build-hash line and the install block, and publishes with--notes-file. First release has no previous tag and generates from the start of history.This only produces useful notes if PRs are labelled — the label→section mapping is in
docs/RELEASING.md, and an unlabelled PR falls into "Other changes".3.
docs/RELEASING.md— including the issue discipline to adoptCovers the version-bump-in-a-PR flow, the label mapping, and the convention to adopt from the next cycle: open an issue per unit of work, reference it with
Closes #Nso GitHub links the commit and it flows into the release notes.release.yml,Closes #Nlinking) are in place here; the discipline is the part that has to actually be followed. Until now the project worked PR-per-change with no issue tracker.Verified
full_versionforms (release / checkout / unknown) tested;describestill flags DIRTY and source.gh— build-hash line + install block + generated change list, in order.Note on labels
This repo has no issue/PR labels yet. GitHub auto-creates the default set (
bug,enhancement,documentation), but the custom ones (compliance,research,rails,tooling,experiment,norelease,breaking) need creating before they categorise anything — I can add them withgh label create, or they can be added as they're first used.🤖 Generated with Claude Code