Skip to content

docs: Conform CHANGELOG to the Keep a Changelog format it declares - #208

Merged
tablackburn merged 2 commits into
mainfrom
docs/changelog-keep-a-changelog-format
Aug 28, 2026
Merged

docs: Conform CHANGELOG to the Keep a Changelog format it declares#208
tablackburn merged 2 commits into
mainfrom
docs/changelog-keep-a-changelog-format

Conversation

@tablackburn

Copy link
Copy Markdown
Contributor

Summary

CHANGELOG.md declares that it follows Keep a Changelog, but
parts of it did not. This is a formatting pass over released sections only — no entry's wording
or meaning is changed, and the ## Unreleased section is untouched.

  • 0.7.1's ### Fixes renamed to ### Fixed — Keep a Changelog defines exactly six change types
    (Added, Changed, Deprecated, Removed, Fixed, Security) and Fixes is not one.
  • 0.3.0's ### Breaking changes folded into its sibling ### Changed section, with the entry
    gaining the inline **Breaking:** marker.
  • Eleven version headings normalized to the ## [x.y.z] - YYYY-MM-DD form.

No changelog entry accompanies this pull request. CHANGELOG.md documents user-facing changes
to the shipped module; reformatting the changelog itself is not one.

Judgement calls

1. Where ### Breaking changes should go

The section held a single entry: Refactor build properties into a single hashtable
$PSBPreference
. Removed was 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 existing
functionality") rather than Removed's. Reading it as Removed would also misdescribe the
release: $PSBPreference was introduced, not deleted.

Folding it into Changed on 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 ### Changed section whose breaking entries open with **Breaking:**. Using
it 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 the
closing 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:

Tagged Untagged
0.3.1, 0.5.0, 0.6.0, 0.6.1, 0.7.0, 0.7.1, 0.7.2, 0.7.3, 0.8.0, 0.8.1, 0.8.2 0.1.0, 0.1.1, 0.2.0, 0.3.0, 0.4.0, 0.6.2, 0.5.0 (beta1)

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

  • Two releases share the version identifier 0.5.0## [0.5.0] - 2021-02-27 and
    ## [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 asserts
    something about how that release was published, and no v0.5.0-beta1 tag exists to corroborate
    it. 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.
  • 0.6.2 has a changelog section but no git tag or GitHub release, unlike its neighbours.
    Noted here only because it surfaced while auditing tags.

Test plan

  • pwsh -NoProfile -c "./build.ps1 -Task Test" — 503 passed, 0 failed, 3 skipped (matches
    the baseline on main)
  • tests/Manifest.tests.ps1 still resolves the changelog version and matches it against the
    manifest, specifically checked because it parses ## [x.y.z] headings
  • File is CRLF throughout after the edits — 496 CRLF, zero lone LF, zero lone CR, zero
    \r\r\n, no BOM, single trailing newline
  • git diff confirms 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

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
Copilot AI lite review requested due to automatic review settings August 28, 2026 18:21

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

@github-actions

github-actions Bot commented Aug 28, 2026

Copy link
Copy Markdown

Test Results

    4 files  ±0    785 suites  ±0   2m 46s ⏱️ -8s
  508 tests ±0    505 ✅ ±0   3 💤 ±0  0 ❌ ±0 
2 015 runs  ±0  1 943 ✅ ±0  72 💤 ±0  0 ❌ ±0 

Results for commit db231a5. ± Comparison against base commit b3bbe9e.

♻️ This comment has been updated with latest results.

## [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
@tablackburn
tablackburn merged commit 229771b into main Aug 28, 2026
9 checks passed
@tablackburn
tablackburn deleted the docs/changelog-keep-a-changelog-format branch August 28, 2026 19:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants