Today — CHANGELOG.md follows Keep a Changelog and says so in its header. That format ends with link reference definitions, one per version, pointing at the compare view:
[0.10.1]: https://github.com/vyncint/termlens/compare/v0.10.0...v0.10.1
Measured on 0.10.1: grep -c '^\[.*\]: https' CHANGELOG.md → 0. Every heading renders as literal [0.10.1] brackets that link nowhere, on GitHub and in the release notes extract-changelog.sh produces.
Why it is worth fixing — "what actually changed between these two releases?" is one click away from a changelog entry and currently zero clicks are available. It is also the difference between the file following the format it claims and merely resembling it.
Fix — add the definitions at the end of CHANGELOG.md, one per released version plus [Unreleased] comparing the newest tag to HEAD. Then add a line to docs/RELEASING.md's cutting steps so a release adds the new one — a changelog convention that is not in the release checklist decays immediately.
Care — .github/scripts/extract-changelog.sh slices the file by ## [ headings and is what builds the GitHub Release notes. Run it (.github/scripts/extract-changelog.sh 0.10.1) before and after and confirm the output is unchanged.
Done when
A good first contribution: one file, no architecture decisions. Start with
CONTRIBUTING.md
— §1 lists every gate you can run locally, and §3 asks that a change land
with a test. Commits are Conventional Commits and need git commit -s
(DCO). Happy to review a draft PR early.
Today —
CHANGELOG.mdfollows Keep a Changelog and says so in its header. That format ends with link reference definitions, one per version, pointing at the compare view:Measured on 0.10.1:
grep -c '^\[.*\]: https' CHANGELOG.md→ 0. Every heading renders as literal[0.10.1]brackets that link nowhere, on GitHub and in the release notesextract-changelog.shproduces.Why it is worth fixing — "what actually changed between these two releases?" is one click away from a changelog entry and currently zero clicks are available. It is also the difference between the file following the format it claims and merely resembling it.
Fix — add the definitions at the end of
CHANGELOG.md, one per released version plus[Unreleased]comparing the newest tag toHEAD. Then add a line todocs/RELEASING.md's cutting steps so a release adds the new one — a changelog convention that is not in the release checklist decays immediately.Care —
.github/scripts/extract-changelog.shslices the file by## [headings and is what builds the GitHub Release notes. Run it (.github/scripts/extract-changelog.sh 0.10.1) before and after and confirm the output is unchanged.Done when
[Unreleased]compares the newest tag toHEAD.extract-changelog.shproduces the same notes as before for an existing version.docs/RELEASING.mdtells the next releaser to add one.A good first contribution: one file, no architecture decisions. Start with
CONTRIBUTING.md
— §1 lists every gate you can run locally, and §3 asks that a change land
with a test. Commits are Conventional Commits and need
git commit -s(DCO). Happy to review a draft PR early.