docs(releasing): correct the handover — bootstrap-sha does not limit the scan - #354
Merged
Conversation
…the scan The first release-please run disproved what I wrote when adding it. The config carries a bootstrap-sha, but the run found the existing v2.0.0 tag and scanned from there, so the release PR describes every commit since v2.0.0 rather than only those after the bootstrap commit. bootstrap-sha appears to apply only when no prior release is found. The consequence is better than the plan it replaces: no final manual release is needed, since the generated section already covers the work. What does need doing moves onto the release PR itself — folding in or dropping the now-stranded hand-written [Unreleased] block, which the generated section is prepended above, and checking the version, since the bot proposes a patch without a feat: or a breaking marker and this repo has merged neither in a long time. Refs #347 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01F22e2ft66y7nuBJjzdThBr
Review panel feedback, three findings converging on the same paragraph: the overwrite caveat was stated in passing, no recovery was described, and the Release-As route was presented as interchangeable with editing the PR when it is in fact the thing that triggers the overwrite. All three were refuted as wording preferences, and taken anyway — because I have since read the mechanism out of the release-please source rather than inferring it. updatePullRequest rebuilds the changeset from commits and pushes it with force: true. Not a merge: every manual edit to the release branch is discarded, on every push to main. That turns the two handover steps from a checklist into an ordered pair — set the version first, since Release-As is itself a push to main, and fold in last with nothing in between. Also records why the hand-written block stays on main until that moment: it is the only copy of those entries. Adds an observed / read-from-source / not-yet-observed split, as the CTO lens asked and as the instruction this setup came from does for its own claims. Refs #347 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01F22e2ft66y7nuBJjzdThBr
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
2 participants
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.
Fixes a claim I got wrong in #352, disproved by the first release-please run (#353) an hour later.
What I wrote
What actually happened
The run found the existing
v2.0.0tag and scanned from there. #353's changelog reaches back to #56, #63 and #69 — every commit sincev2.0.0, not just those after the bootstrap commit.bootstrap-shaappears to be consulted only when no prior release is found.Why the correction is good news
No final manual release is needed after all: the generated section already covers the work, so the three-step handover I described is replaced by two edits on the release PR itself.
## [Unreleased]block is stranded. The generated section is prepended above it, so it now sits below a released version with nothing to ever clear it — the exact failure mode the old text warned about, which happened anyway because the premise was wrong. Its entries carry causes and consequences the commit subjects do not, so folding the worthwhile ones into the generated section beats deleting them.feat:or a breaking marker, and this repo has merged neither sincev2.0.0— so chore(main): release 2.1.0 #353 proposes2.0.1for work that includes new public API.Release-As:or a direct edit raises it.AGENTS.mdis updated to match: contributors should stop adding to## [Unreleased].Refs #347
🤖 Generated with Claude Code
https://claude.ai/code/session_01F22e2ft66y7nuBJjzdThBr
Generated by Claude Code