docs: open the 1.0.0-beta.1 section, and a fresh Unreleased above it - #78
Merged
Conversation
Keep a Changelog holds work under [Unreleased] until it ships; releasing is renaming that heading and opening an empty one above. Both languages move together, which the structural comparison enforces. This is no longer only bookkeeping. Release notes are read out of the changelog now rather than generated from pull-request titles, so the heading is what decides whether `gh release create` has anything to publish — and the extractor refuses an absent section, an empty one, and [Unreleased] by name. Proven here rather than at tag time: it returns 417 lines for 1.0.0-beta.1, exits 2 on Unreleased, and exits 1 on a version with no section. The notes say what beta claims, since it claims more than preview did and less than a candidate would: the surface is settled, the behaviour behind it is not yet proven anywhere but here. Everything the tag will touch was exercised at the real version rather than assumed from it. `dotnet pack -p:Version=1.0.0-beta.1` produces the four files under their beta names and the packaging verifier accepts both; release.yml's own SemVer regex, extracted from the workflow rather than retyped, accepts the version, and the hyphen rule derives prerelease=true, which is what keeps a beta off the repository's latest-release slot. No tag is pushed by this. The `v*` ruleset forbids deletion and update, so the dry run has to exercise the final commit — which is this one, once merged. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GcQ3umdkRNsR7FRB9s2P2w
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.
Summary
Releasing, in Keep a Changelog terms, is renaming
[Unreleased]to the version and opening an empty one above it. Both languages move together. No tag is pushed by this — it is the commit the tag will point at.Type of change
The heading is now load-bearing
Release notes are read out of the changelog rather than generated from pull-request titles, so
## [1.0.0-beta.1]is what decides whethergh release createhas anything to publish. Proven here rather than at tag time, when nothing can be taken back:changelog-section.sh 1.0.0-beta.1changelog-section.sh Unreleasedchangelog-section.sh 9.9.9## [9.9.9]section"The freshly opened
[Unreleased]is empty, which is exactly the state the extractor refuses to publish — so the section it will read cannot silently be the wrong one.What beta claims
The notes now say it, because beta claims more than preview did and less than a candidate would:
Exercised at the real version, not assumed from it
dotnet pack -c Release -p:Version=1.0.0-beta.1produces the four files under their beta names, andtools/packaging/verify-packages.shaccepts both packages — framework reference, analyzers,build/*.targets, and theMicrosoft.OpenApi2.11.0 floor.release.yml's SemVer regex, extracted from the workflow rather than retyped, accepts1.0.0-beta.1.prerelease=true, which is what keeps a beta off the repository's latest-release slot.Testing
dotnet build -c Release— 0 warnings, 0 errorsdotnet test -c Release— 972 passedtests/PackageSmokeTest/run.sh— the published package behaves as documentedlint-layout.sh, its own test, and the changelog extractor's test all pass.Public API
Documentation
docs/updatedCHANGELOG.mdanddocs/for-users/CHANGELOG.fr.mdboth updatedWhat is left, and not done here
release.ymlbyworkflow_dispatchwith1.0.0-beta.1— the plan requires it to exercise the final commit, which is this one once merged, so it comes after this PR rather than inside it.v1.0.0-beta.1, which I will not push without being told to. Thev*ruleset forbidsdeletionandupdate: a tag that fails to publish cannot be reused.One open question for the notes: this beta exists because bugs were found. If any of them should be listed as known issues before publishing, say which and I will add them to the section — I have not invented entries for defects I have not seen.
Related issues
—
Generated by Claude Code