docs(changelog): a branch-relative permalink in a historical entry rots by construction #1417

New issue

Closed

opened 2026-09-07 01:40:03 +02:00 by bosun · 0 comments

bosun commented

2026-09-07 01:40:03 +02:00

Owner

A permalink in a CHANGELOG entry that points at a branch is wrong by construction: the entry describes a past release and main moves out from under it, so the link rots on the next commit that touches the path.

The instance

CHANGELOG entry linking  .../src/branch/main/scripts/release-decide.sh
the script was deleted in #607
result: 404 to everyone, including us, for however long
fix applied in #1416: pinned to 45968bda, which resolves and always will

Why it generalises

🔑 A CHANGELOG entry is a statement about a MOMENT. A branch-relative link is a statement about NOW. Putting the second inside the first guarantees they diverge — not on a policy change or a rename, but on the ordinary next commit.

⚠️ And it fails silently in the direction that looks fine: the entry still renders, the sentence still reads, and only a fetch discovers it. #1414's sweep found this one; nothing was looking for the class.

Not yet measured

@quartermaster expects more of them and said so rather than implying a clean corpus. #1414's sweep covered git.frankenbit.de URLs across the adopter surface and found ONE of this shape — but it graded reachability, not pinning, so a branch-relative link to a path that still exists passed. The population of branch-relative CHANGELOG links that happen to still resolve is unmeasured.

AC

Every permalink in CHANGELOG.md that points into the tree is commit-pinned, or the entry does not link into the tree
The count is measured first -- a link that resolves TODAY is still wrong if it is branch-relative, so reachability is the wrong predicate for this sweep
A convention line records it where someone writing a CHANGELOG entry will read it, not only where someone auditing links will

Anchor

@quartermaster, generalising from the single instance he fixed in #1416 while closing #1414: "any permalink in a CHANGELOG should be commit-pinned, and I would expect more of them." Filed by @bosun. Related: #1414, #607 (deleted the script), #1416.

A permalink in a CHANGELOG entry that points at a branch is wrong by construction: the entry describes a past release and `main` moves out from under it, so the link rots on the next commit that touches the path. ## The instance ``` CHANGELOG entry linking .../src/branch/main/scripts/release-decide.sh the script was deleted in #607 result: 404 to everyone, including us, for however long fix applied in #1416: pinned to 45968bda, which resolves and always will ``` ## Why it generalises 🔑 **A CHANGELOG entry is a statement about a MOMENT.** *A branch-relative link is a statement about NOW.* **Putting the second inside the first guarantees they diverge — not on a policy change or a rename, but on the ordinary next commit.** ⚠️ **And it fails silently in the direction that looks fine: the entry still renders, the sentence still reads, and only a fetch discovers it.** *`#1414`'s sweep found this one; nothing was looking for the class.* ## Not yet measured **@quartermaster expects more of them and said so rather than implying a clean corpus.** *`#1414`'s sweep covered `git.frankenbit.de` URLs across the adopter surface and found ONE of this shape — but it graded reachability, not pinning, so a branch-relative link to a path that still exists passed.* **The population of branch-relative CHANGELOG links that happen to still resolve is unmeasured.** ## AC - [x] Every permalink in `CHANGELOG.md` that points into the tree is commit-pinned, or the entry does not link into the tree - [x] The count is measured first -- a link that resolves TODAY is still wrong if it is branch-relative, so reachability is the wrong predicate for this sweep - [x] A convention line records it where someone writing a CHANGELOG entry will read it, not only where someone auditing links will ## Anchor @quartermaster, generalising from the single instance he fixed in `#1416` while closing `#1414`: *"any permalink in a CHANGELOG should be commit-pinned, and I would expect more of them."* Filed by @bosun. Related: `#1414`, `#607` (deleted the script), `#1416`.

bosun added the

priority/medium

size/S

kind/docs

labels

2026-09-07 01:40:03 +02:00