Name the changelog timezone and all five version places - #312
Merged
Merged
Conversation
Two gaps that each cost time during the v0.17.0 release. The changelog date requirement never named a timezone. A tag pushed in the evening US-Pacific carries a UTC timestamp on the next day, so for a few hours every night the two disagree and a reviewer reading UTC calls a correct heading stale, which is exactly what happened on #309. The convention the tags actually show is the maintainer's local day: v0.16.0 and v0.14.0 both have headings a day behind their UTC timestamps. v0.15.0 is the counter-example and it is simply wrong, a day behind its own local tag day. The version-bump item named three files. Five carry it. uv.lock locks the local package's own version and the bundled AGENTS.md stamps it into its header, and neither fails anything until an artifact is built, so both are easy to miss. They are generated, so the doc says to run the generator rather than hand-edit. Also records why the rc and real-release bumps cannot be one commit, in the place someone reads while doing it rather than in the comment at the top of the workflow.
There was a problem hiding this comment.
Copilot review overview
🟡 Changes recommended
Later release procedures omit two newly documented version locations, and the stated CI behavior is inaccurate.
Review effort: Balanced
Findings: 1
What changed in this PR
Clarifies release documentation to prevent changelog date and package version drift.
Changes:
- Defines changelog dates using the releasing maintainer’s local timezone.
- Documents five package-version locations and generated-file workflows.
- Reinforces separate RC and final-release version commits.
| File | Description |
|---|---|
RELEASING.md |
Expands changelog dating and version-bump guidance. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
The claim that nothing fails until the artifact is built was wrong three ways. A stale uv.lock fails the uv-lock pre-commit hook at commit time and uv sync --frozen in both CI and the release workflow; a stale bundled AGENTS.md fails test_agents_md_matches_generator_output. Saying no signal exists when three do is worse than saying nothing, because it teaches a maintainer not to look for the failure that will actually stop them. The two generated files are easy to miss because the checklist omitted them, not because they go undetected: you found out from a failing hook instead of from the doc, which is backwards for a checklist meant to prevent surprises. Naming each mechanism is the more useful form anyway, since it says which failure corresponds to which omission.
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
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 gaps in
RELEASING.md, each of which cost time during the v0.17.0 release.The changelog date had no timezone
The requirement said "the date matches the day the rc tag is pushed" and stopped there. A tag pushed in the evening US-Pacific carries a UTC timestamp on the following day, so for a few hours every night the two clocks disagree — and a reviewer reading UTC calls a correct heading stale, which is exactly what happened on #309.
The convention the tags actually show is the maintainer's local day:
v0.17.0v0.16.0v0.15.0v0.14.0v0.16.0andv0.14.0both have UTC timestamps on the day after their headings, which is what makes the local reading the live convention rather than a coincidence.v0.15.0is the counter-example and it is simply wrong — a day behind its own local tag day, shipped and never corrected.So the doc now names the timezone and says to set the date immediately before merging the version bump, because setting it earlier is what produces drift.
The version lands in five files, not three
The item named
pyproject.toml,__version__and the smoke-test assertion. Two more carry it:uv.locklocks the local package's own versionsrc/openarmature/AGENTS.mdstampsversion X.Y.Z (spec vA.B.C)into its headerNeither fails anything until an artifact is built, which is what makes them easy to miss. Both are generated, so the doc says to run
scripts/build_agents_md.pyand letuvtouch the lock rather than hand-editing either.The rc/real-release two-commit requirement was already documented and is now stated where someone reads it while doing the work, rather than only in the comment at the top of
release.yml. I read past it once this cycle and nearly pushedv0.17.0-rc1against a pyproject saying0.17.0, which the workflow would have rejected.Scope
Documentation only. No behaviour, no code.
tests/test_smoke.pypasses unchanged.