Repo - FEATURE - Add naming conventions, PR release-note block and changelog - #404
Conversation
…angelog Replace the CODE - TAG - message convention with a closed Area/TAG grammar, add a release-note block to every PR, and ship a changelog plus a generator that compiles it. PR titles and release-note blocks are checked in CI; commit subjects follow the grammar by convention. Valid Areas are derived from src/ on disk, so the vocabulary cannot go stale. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
|
I did manual step (1) |
The metadata check read context.payload.pull_request, a snapshot taken when the event fired. Reviewers attached just after creation were therefore invisible, so a pull request with reviewers was reported as missing them. Adding a reviewer fired no configured event, so the comment could never clear itself. Fetch the pull request through the API, and trigger on the assignee and reviewer events so the check re-runs when that metadata changes. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
matt-pharr
left a comment
matt-pharr
left a comment
There was a problem hiding this comment.
Just this one edit and can be merged. If you don't want to do it I can do it in ~2h once my plane is in the air
| @@ -0,0 +1,347 @@ | |||
| #!/usr/bin/env python3 | |||
| """Validate pull request titles, release-note blocks, and commit subjects. | |||
There was a problem hiding this comment.
Highly recommend adding a PEP 723 convention comment header to this script, it will make sure that it is always runnable with no environment fuss with uv run or similar tools.
There was a problem hiding this comment.
Done in 198225e — no need to do it from the air.
#!/usr/bin/env python3
# /// script
# requires-python = ">=3.10"
# dependencies = []
# ///The script is stdlib-only, so the dependency list is empty; >=3.10 matches the default_language_version pin in .pre-commit-config.yaml. Verified both python3 ci/conventions/check_subject.py --title ... and uv run ci/conventions/check_subject.py --title ... still pass a valid subject and reject EQUIL - FIX - nope with the replacement hints. docs/development/naming.md now shows the uv run invocation alongside the python3 one.
Generated by Claude Code
|
labels have been updated |
Lets `uv run ci/conventions/check_subject.py` work with no Python environment set up. The script is stdlib-only, so the block declares `requires-python = ">=3.10"` and an empty dependency list. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VKyvW37urZU6HQ2oQ4hbn9
3 participants
Release note
Reworks the commit, issue and pull request conventions around AI-generated release notes. Commit and PR titles now use a closed
Area - TAG[!] - Summarygrammar, every PR carries a release-note block, andCHANGELOG.mdis compiled from those blocks by a new/release-notescommand.Regression report
No files under
src/are touched, so there is nothing for the harness to move and no harness stamp is required by the new check. Confirmed bygit diff --stat: the change is limited todocs/,.github/,ci/,CLAUDE.md,CHANGELOG.mdand.claude/.Notes for reviewers
Why this changed at all: the old
CODE - TAG - messageconvention was built for hand-consolidating release notes. Handing that to AI shifts what the metadata must carry. Measured over the last 400 non-merge commits,MINORwas the single most-used tag at 87 uses but encodes size rather than kind;BUG FIX/BUGFIX/FIXappeared under three spellings; and the one fact a GPEC user most wants at a release — did my answers change — was recorded nowhere, because it cannot be derived from a diff.Design decisions worth a look:
!marks a user-visible change and promotes it into a leadingChanged results & breaking changessection whatever its tag.REFACTOR!is deliberately legal — a restructuring that perturbs numbers is exactly what a user needs told.MINOR!,TEST!andDOCS!are rejected.MINORis kept rather than renamed toCHORE. It records the author's judgement that a commit can be skipped, which is what it was actually used for.src/on disk, not hardcoded, so the vocabulary cannot go stale. This surfaced thatCLAUDE.mdandarchitecture.mdboth still listed aSplinesmodule that no longer exists and omitted five real ones; both are corrected here.src/changed afterwards — so a report cannot silently rot during review. Docs- and test-only follow-ups never trip it.Two steps cannot be done from a branch and are still outstanding:
git log --mergesa well-formed history and what justifies not enforcing commit subjects.addLabelsauto-creates missing labels with random colors, so nothing breaks, but creating the nine tag labels pluschanged-resultsdeliberately would be better, along with retiring the stalesplineslabel.This PR is also the first live test of the
pr-conventionsworkflow — it has never run. If the checks misbehave, that is the workflow being exercised for the first time rather than the branch being broken.