Skip to content

docs: CHANGELOG.md is missing comparison-link footer required by release instructions #46

@tablackburn

Description

@tablackburn

Summary

`instructions/releases.instructions.md` (lines 71-72) calls for adding a comparison-link footer to `CHANGELOG.md` for each new version:

  1. Update changelog links: Add comparison link for the new version at the bottom of CHANGELOG.md (e.g., `[0.2.0]: https://github.com/owner/repo/compare/v0.1.0...v0.2.0\`)

But `CHANGELOG.md` currently has zero such links — `grep -E '^[[\d.]+]:\s*https?://' CHANGELOG.md` returns nothing. None of the prior releases (0.11.0 in #41, 0.11.1 in #44, etc.) added one either, so the practice has drifted from the instruction file.

This was noticed during the v0.11.2 release planning for #45.

Why this matters

  • Reference-style links allow consumers (and the Keep-a-Changelog spec) to jump from a version header to its diff against the prior version
  • The `[Unreleased]` section header is currently a plain bracketed string with no link target, so it doesn't render as a link in GitHub's markdown view either
  • Following our own documented release process keeps the instruction file authoritative

Options

  1. Backfill all historical versions in one PR — adds ~25 footer lines (one per prior release back to 0.1.0 plus an `[Unreleased]: .../compare/v0.11.2...HEAD`), then add the new link as part of every future release.
  2. Start from the next release forward — only add links from 0.11.3 onward; leave history un-linked.
  3. Update `releases.instructions.md` to drop step 5 if we've decided in practice we don't want comparison links.

Suggested next steps

  • Decide between options 1, 2, or 3
  • If 1 or 2: file a follow-up PR (or fold into the next release PR)
  • If 3: update `instructions/releases.instructions.md` to remove step 5

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions