docs(changelog,contributing): revise the 1.0.0 entries and document changelog style#3
Merged
Merged
Conversation
37e1ee9 to
db5529d
Compare
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 documentation-only changes that belong together: fix the 1.0.0 changelog, and write down the guidance for keeping it that way.
## [1.0.0]CHANGELOG section: reflow each entry onto a single line, trim over-explanation, reframe the token entries as a mechanism (not a capability the module enforces), state the config-reload behaviour accurately, and a few minor wording fixes.## Changelogsection to CONTRIBUTING that codifies what earns an entry and how to write it, so the changelog stays this way.No code, no behaviour change. No new release: the
v1.0.0tag and its GitHub Release are untouched (the published notes are re-synced to this text after merge).Reasoning
Publishing 1.0.0 turned the changelog into the GitHub Release notes, which surfaced problems worth fixing at the source:
Why this is exceptional, but still the right call now
Editing an already-released
## [x.y.z]section is normally avoided: Keep a Changelog treats released sections as historical, and rewriting them can mislead anyone who already acted on them. We are doing it deliberately, and it is justified here:Accepted implications
## [1.0.0]section onmainwill differ from the CHANGELOG snapshot inside the immutablev1.0.0tag. Expected and harmless; the tag is history,mainis current.v1.0.0Release notes will be re-synced to this text after merge, withgh release edit(editing the existing release in place; no new release, no new tag).Result
The tightened
## [1.0.0]now conforms to the newly-documented CONTRIBUTING rules: the guidance and the example it governs agree, a clean starting point.