docs: Conform CHANGELOG to the Keep a Changelog format it declares - #208
Merged
Conversation
The file's header states it follows Keep a Changelog, but three released sections did not. Keep a Changelog defines exactly six change types (Added, Changed, Deprecated, Removed, Fixed, Security), and the version heading form is `## [x.y.z] - YYYY-MM-DD`. - 0.7.1 used `### Fixes`, which is not a type. Renamed to `### Fixed`. - 0.3.0 used `### Breaking changes`, which is not a type either. Its one entry describes a refactor of existing configuration surface, not a removal, so it is folded into the sibling `### Changed` section and carries the inline `**Breaking:**` marker this file already uses in the Unreleased section. The marker keeps the information the heading carried; the entry wording is unchanged. - Eleven version headings (0.5.0 through 0.8.2) omitted the ` - ` separator before the date, while 0.4.0 and older included it. Added the separator so every released heading reads the same way. No entry wording or meaning was changed anywhere, and the Unreleased section is untouched. There is no CHANGELOG entry for this commit: the changelog documents user-facing changes to the shipped module, and reformatting the changelog itself is not one. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U1Jhu7fgTRJq7LK5MuKteE
## [0.5.0] (beta1) - 2020-11-15 -> ## [0.5.0-beta1] - 2020-11-15 This was left out of the first pass as a content decision rather than a formatting one, on the reasoning that rewriting a released version's identifier asserts something about how it was published, and that no v0.5.0-beta1 tag corroborates it. That reasoning was sound but the conclusion does not hold: "0.5.0 (beta1)" and "0.5.0-beta1" say the same thing, and the second is the spelling both Semantic Versioning and Keep a Changelog use for a prerelease. Nothing is being asserted that the parenthetical did not already assert. Two things improve for free. The file no longer carries two headings labelled [0.5.0]. A duplicate identifier makes the version ambiguous to a reader and unlinkable to a tool, and it is part of why the linkability question raised in this pull request has no clean answer -- one label cannot serve two releases. And it is the last heading in the file that the Keep a Changelog format check rejects. That check is proposed for the shared module workflow in psake/.github#8, and psake/PowerShellBuild is its only consumer today, so this heading was the one thing standing between that workflow and a green run here. Verified: the check now passes over this branch, 496 lines, no findings. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U1Jhu7fgTRJq7LK5MuKteE
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.
Summary
CHANGELOG.mddeclares that it follows Keep a Changelog, butparts of it did not. This is a formatting pass over released sections only — no entry's wording
or meaning is changed, and the
## Unreleasedsection is untouched.### Fixesrenamed to### Fixed— Keep a Changelog defines exactly six change types(
Added,Changed,Deprecated,Removed,Fixed,Security) andFixesis not one.### Breaking changesfolded into its sibling### Changedsection, with the entrygaining the inline
**Breaking:**marker.## [x.y.z] - YYYY-MM-DDform.No changelog entry accompanies this pull request.
CHANGELOG.mddocuments user-facing changesto the shipped module; reformatting the changelog itself is not one.
Judgement calls
1. Where
### Breaking changesshould goThe section held a single entry: Refactor build properties into a single hashtable
$PSBPreference.Removedwas the alternative — the individual build properties did go away —but what the entry actually describes is a restructuring of the configuration surface that
survived under a new shape, which is
Changed's definition ("for changes in existingfunctionality") rather than
Removed's. Reading it asRemovedwould also misdescribe therelease:
$PSBPreferencewas introduced, not deleted.Folding it into
Changedon its own would have dropped the fact that the change was breaking,which the heading was carrying. This repository already has a convention for that, visible in
## Unreleased: a### Changedsection whose breaking entries open with**Breaking:**. Usingit here preserves the information and makes the file self-consistent. The entry's own wording is
untouched — the marker is prepended, and the line is wrapped to the file's prevailing width.
2. Whether to normalize the version headings
Done, for all eleven that needed it (0.5.0 through 0.8.2, which omitted the
-separator).0.4.0 and everything older already used the Keep a Changelog form, so the file was inconsistent
with itself as well as with the spec, and the drift was one-directional — every heading added
since 0.5.0 has compounded it. The change carries no risk worth weighing against that: dates and
version numbers are byte-identical, and the only machine reader of these headings,
tests/Manifest.tests.ps1, matches^##\s\[(?<Version>(\d+\.){1,3}\d+)\]and stops at theclosing bracket, so it is indifferent to what follows. Verified: the suite is green.
The counter-argument is that this edits released history for appearance alone. It does, but the
edit is confined to the heading's punctuation, which is metadata about the release rather than a
claim the release made.
3. Linkability — found, deliberately not fixed
Keep a Changelog says versions and sections should be linkable, and every version heading here
uses
[x.y.z]bracket syntax. There are no link reference definitions anywhere in the file.In CommonMark a shortcut reference link with no matching definition renders as literal text, so
today all sixteen version headings render with visible brackets and none of them link anywhere.
(The GitHub release titles show the same thing:
[0.8.2] 2026-07-08, brackets and all.)The conventional fix is a comparison-link block at the bottom, and I did not add one, because it
is not mechanical here. Only eleven of the sixteen versions have git tags:
A complete compare-link block would therefore point six versions at tags that do not exist —
replacing literal-text non-links with 404s, which is worse. Adding definitions for only the
tagged versions leaves the file inconsistent in a way that reads as an oversight. Either route
needs a maintainer decision that is out of scope for a formatting pass: whether to create the six
missing tags retroactively, or to accept partially-linked history.
Found and deliberately not fixed
## [0.5.0] - 2021-02-27and## [0.5.0] (beta1) - 2020-11-15. The SemVer spelling of the second would be## [0.5.0-beta1] - 2020-11-15, but rewriting a released version's identifier assertssomething about how that release was published, and no
v0.5.0-beta1tag exists to corroborateit. That is a content change, not a formatting one, so I left it and am flagging it. It is also
entangled with the linkability decision above: as long as two headings carry the same label,
one link definition would have to serve both.
Noted here only because it surfaced while auditing tags.
Test plan
pwsh -NoProfile -c "./build.ps1 -Task Test"— 503 passed, 0 failed, 3 skipped (matchesthe baseline on
main)tests/Manifest.tests.ps1still resolves the changelog version and matches it against themanifest, specifically checked because it parses
## [x.y.z]headings\r\r\n, no BOM, single trailing newlinegit diffconfirms every hunk falls at line 249 or later, so## Unreleased(lines 8-248)is byte-identical and will not conflict with the open pull requests adding entries there
Breaking changes
None.
🤖 Generated with Claude Code
https://claude.ai/code/session_01U1Jhu7fgTRJq7LK5MuKteE