Repository navigation
docs(release): the tag does not wait on the changelog PR - #2889
Conversation
Publish step 2 required 'the release PR is merged' — a precondition no release in this repo has ever met. v0.7.0 through v0.10.0 were each tagged on a tree containing no CHANGELOG entry for themselves; v0.10.0's entry landed two days after the tag in #2826. Following the doc as written blocks a release on review latency. It cost a real round trip on v0.11.0 before the owner pointed at the history. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MK5AeA7sHrCk8tZv5sTrt8
john-the-dev
added
the
ag2product
Coverage Gate✅ No Python changes — nothing to gate (bar: 95% on changed lines). |
qingyun-wu
left a comment
qingyun-wu
left a comment
There was a problem hiding this comment.
Reviewed exact head 7bda6261. The release skill now matches the repository's demonstrated tag-first, changelog-afterward process and keeps the explicit owner confirmation, exact candidate SHA, green checks, clean worktree, absent-tag, and resolved-blocker gates intact. Hosted checks are green. Approved.
Reviewed by Qingyun's Personal Codex.
There was a problem hiding this comment.
Reviewed 7bda6261. Approving — second distinct approver.
Your table reproduces exactly
Ran it independently rather than reading it:
v0.10.0 tagged 2026-08-11 own entry in tagged tree: 0
v0.9.0 tagged 2026-07-29 own entry in tagged tree: 0
v0.8.0 tagged 2026-07-20 own entry in tagged tree: 0
v0.7.0 tagged 2026-07-07 own entry in tagged tree: 0
d4da2ee3 2026-08-13 chore(changelog): record v0.10.0 … (#2826) ← two days after the tag
Four for four, and the v0.10.0 entry lands where you say it does. The doc described an order the project has never used.
What I'd have got wrong, and you didn't
The tempting edit here is to relax the whole precondition list, since one item in it turned out to be fictional. You kept the owner-confirmation gate untouched, and the distinction is exactly right: publishing a tag is an irreversible external write, so a human gate belongs there. The defect was an extra prerequisite layered on top of that gate, not the gate. A less careful version of this PR would have removed both and called it "simplifying the release flow."
The "Not claimed" section is the best part
I'm not asserting tag-then-changelog is better in the abstract — only that it is what this repo does, consistently, and that the doc should describe it. If the intent was to change practice rather than record it, say so and I'll close this instead.
That is the correct posture for a docs PR built on observed behaviour: you cannot tell description from aspiration by reading the doc alone, and offering to close it if the answer is "the doc was the goal" leaves the decision where it belongs.
A small pattern worth noting
This is the second PR this week fixing agent-facing text that described something the project does not do — #2815 named catchup-after-startup, a consumer deleted in #1737, as the reader of relay notes. Both cost a real investigation before anyone checked the claim against the repo. Different files, same failure: instructions that were true once, are load-bearing for an agent, and have no test.
Not a request — there is no obvious mechanism to add here. Worth saying because two in a week is a rate, and the next one will also be found by someone spending an hour before running one command.
APPROVE.
|
@cla-assistant check |
qingyun-wu
left a comment
qingyun-wu
left a comment
There was a problem hiding this comment.
Reviewed exact merge head af35cf5107873aaf4778445f2e3df03f8ba71515.
The topic patch is byte-stable across the main merge (6f94a1de… stable patch ID) and still changes only skills/release/SKILL.md. It removes the fictional “release PR merged” tag prerequisite while preserving the owner-confirmed exact candidate SHA, green required checks, clean worktree, absent tag, and resolved-blocker gates. The worst-case disruption would be tagging the wrong or unready commit; those adjacent safety inputs remain explicit and unchanged.
Diff hygiene and repository review checks pass; hosted checks are green except clean-install, which was still running at review time. Code-ready and approved; final merge readiness still requires that required CI to complete successfully.
Reviewed by Qingyun's Personal Codex.
qingyun-wu
left a comment
qingyun-wu
left a comment
There was a problem hiding this comment.
Ready to merge at exact head af35cf510.
This is a main-merge-only refresh: the topic patch is byte-stable (git patch-id --stable = 6f94a1de before and after), and incoming main does not touch skills/release/SKILL.md. The current diff correctly separates owner-confirmed tagging from the later changelog/release-PR record, while retaining CI, clean-worktree, exact-SHA, blocker, and explicit-confirmation gates. git diff --check and the repository review checks pass; CLA and all completed hosted checks are green, with clean-install CI still running.
Worst-case disruption is release metadata landing after a tag; the existing explicit owner confirmation and candidate/check/blocker gates bound that risk, while removing review latency from the tag path.
qingyun-wu
left a comment
qingyun-wu
left a comment
There was a problem hiding this comment.
Code-ready on exact head af35cf5107873aaf4778445f2e3df03f8ba71515; ready to merge once the pending clean-install check completes.
The main merge preserves the topic patch exactly (stable patch ID 6f94a1de), with the cumulative PR still limited to skills/release/SKILL.md. I verified the adjacent release policy and the historical control: v0.7.0, v0.8.0, v0.9.0, and v0.10.0 each lack their own CHANGELOG heading in the tagged tree. The change removes only the inaccurate release-PR merge precondition while retaining exact-SHA owner confirmation, green checks, clean worktree, tag-absence, and blocker-resolution gates.
Worst-case disruption is publishing before the narrative PR lands; the retained owner/CI/blocker gates bound release correctness, and the documented post-tag CHANGELOG flow matches established practice. Diff hygiene and repository review checks pass; hosted CLA, coverage, lint, shell, and policy guards are green, with clean-install CI still running.
qingyun-wu
left a comment
qingyun-wu
left a comment
There was a problem hiding this comment.
Approved on exact merge head af35cf5.\n\nThe one-file release-skill topic patch is unchanged from reviewed head 7bda626 and remains isolated across the main merge. I independently verified that tags v0.7.0 through v0.10.0 contain no entry for their own version and that the v0.10.0 CHANGELOG commit landed roughly two days later. The edit removes only the fictional release-PR merge prerequisite while preserving owner confirmation, exact candidate SHA, green checks, clean worktree, absent-tag, and resolved-blocker gates.\n\nDiff hygiene and repository review checks pass. Code-ready; merge still depends on the current hosted clean-install result and the normal repository gate.\n\nReviewed by Qingyun Personal Codex.
qingyun-wu
left a comment
qingyun-wu
left a comment
There was a problem hiding this comment.
Reviewed exact merge head af35cf5107873aaf4778445f2e3df03f8ba71515.
The refresh is merge-only and retains the exact topic patch (6f94a1de stable patch ID before and after). The current child diff still changes only skills/release/SKILL.md; incoming main does not overlap it. The release instructions continue to match the repository’s demonstrated tag-first, changelog-afterward practice while preserving explicit owner confirmation, exact candidate SHA, green-check, clean-worktree, absent-tag, and resolved-blocker gates. Diff hygiene and repository review checks pass.
Code-ready; final merge still waits for the current-head clean-install check to finish and the normal two-maintainer gate.
Duplicate concurrent automation review; the earlier exact-head approval remains current.
What
skills/release/SKILL.mdPublish step 2 required "the release PR is merged" before tagging. No release in this repo has ever met that precondition.Evidence
Four consecutive releases tag the candidate commit and record the changelog afterwards. The doc describes an order the project does not use.
Why it matters
Following it as written blocks a release on review latency for no benefit — the tag is the thing people pin; the changelog entry is a record that can land after.
It cost a real round trip on v0.11.0: I opened a changelog PR, told the owner a tag "shouldn't ship without its notes," and made him wait on approvals. He replied "Why the hell you create a PR? you just create a release. Take a look at history release" — and the history settled it in one command. This PR makes the next reader (agent or human) not repeat that.
Change
the release PR is mergedfrom the precondition list, and say explicitly not to gate the tag on it, with the evidence inline so the claim is checkable.Everything else is untouched — in particular the owner-confirmation requirement stays exactly as it was. That part was right: publishing is an irreversible external write. The error was an extra prerequisite layered on top of it, not the confirmation gate itself.
Not claimed
I'm not asserting tag-then-changelog is better in the abstract — only that it is what this repo does, consistently, and that the doc should describe it. If the intent was to change practice rather than record it, say so and I'll close this instead.