Skip to content

docs: link every changelog version, name the parser in the spec - #358

Merged
vyncint merged 1 commit into
mainfrom
docs/changelog-links-and-parse-in-design
Sep 16, 2026
Merged

vyncint merged 1 commit into
mainfrom
docs/changelog-links-and-parse-in-design

Conversation

@vyncint

@vyncint vyncint commented Sep 16, 2026

Copy link
Copy Markdown
Owner

Two documentation issues, and one gate change they needed.

Every version heading links to its diff (#319)

CHANGELOG.md says in its header that it follows Keep a Changelog, whose
format ends with one link reference definition per version. It had zero,
so every heading rendered as literal [0.11.0] brackets pointing nowhere,
on GitHub and in the release notes. Nineteen definitions are now at the foot
of the file — eighteen versions plus [Unreleased], which compares v0.11.0
to HEAD.

Two judgement calls worth reviewing:

  • [0.4.2] compares against v0.4.0, not v0.4.1. The v0.4.1 tag
    exists in git, but 0.4.1 was never published — its own 0.4.2 entry records
    that ("tagged for exactly this content and never published: its release
    run caught a latent race"). The link should be the diff a consumer can
    reason about, which is from the last version they could install. Every one
    of the eighteen tags referenced was checked against git ls-remote --tags origin.
  • [0.1.0] points at the release tag, since there is nothing to compare
    it against.

extract-changelog.sh stops at the definitions

This is the "Care" note in #319, and it was a real problem. The script
slices the file by ## [ headings and collects to EOF for the oldest
section, so link definitions at the foot would have been appended to
v0.1.0's GitHub Release notes.

The fix is one awk rule: stop at the first [label]: http…. Verified by
extracting all nineteen sections before and after the change
byte-identical (diff -r), which is the Done-when box. And verified to be
load-bearing: with the rule deleted, v0.1.0's notes grow by twenty-two lines.

An in-file HTML comment explaining the block was drafted and then removed
for the same reason — it sat above the first definition and leaked into
v0.1.0's notes. The explanation lives in docs/RELEASING.md, where the
person who needs it is looking.

docs/RELEASING.md step 2

A changelog convention that is not in the release checklist decays on its
first release, so step 2 now says to repoint [Unreleased] and add the new
version's line, shows the two lines, and suggests running
extract-changelog.sh X.Y.Z to see what the GitHub Release will say.

docs/DESIGN.md §3 names its reader (#305)

§3 is the normative spec for the snapshot text format — what someone reads
to implement against it or to trust a saved snapshot — and it never
mentioned Screen::parse, the function that reads the format back. A new
"Reading it back" subsection, placed between the rules and "What a
reader skips", states:

  • what parse accepts, and that the termlens CLI's diff and render
    are built on it;
  • that the round trip is exact for what the format carries — same text,
    same styles: block, diffs empty — and not ==, with rule 5's own
    equality paragraph as the reason;
  • what does not survive: an erased cell and a written blank are one
    character either way, out-of-band state comes back default, and a hidden
    cursor's position is not recorded so cursor: hidden parses back at
    0,0;
  • that the header's row count decides where the grid ends, and the one
    ambiguous input that follows from it.

Every claim is taken from Screen::parse's rustdoc and the tests that
already assert it (a_hidden_cursor_round_trips_as_the_same_picture,
a_grid_holding_the_words_of_a_styles_block_round_trips), so this is a
pointer and not a second spec — which is what #305 asked for. The
hidden-cursor claim was also checked by hand through the CLI rather than
copied from the rustdoc.

Also

[Unsupported] in the 0.11.0 entry was a shortcut reference with no
definition anywhere in the file, so it rendered as literal brackets. It gets
one, alongside the version links. Out of the letter of #319 and squarely
inside its point; call it out if you would rather it were separate.

Verification

  • extract-changelog.sh for all 19 sections, before vs after: identical.
  • check-candidate-statement.sh, check-readme-links.sh,
    check-ci-gates-listed.sh, cargo test --workspace --all-features: green.

What this does not do

  • No automated check that a release adds its link definition. #319 asks
    for the RELEASING.md line and that is what is here; a gate for it would be
    a fourth drift script and is worth its own issue if the checklist proves
    insufficient.
  • The compare URLs are not fetched over the network — the tags they name are
    each confirmed to exist on origin, which is what determines whether the
    URL resolves.

Closes #305
Closes #319

@vyncint
vyncint force-pushed the docs/changelog-links-and-parse-in-design branch 2 times, most recently from 7d45687 to bc044d3 Compare September 16, 2026 13:18
CHANGELOG.md says it follows Keep a Changelog, whose format ends with a
link reference definition per version. It had none, so every heading
rendered as literal `[0.11.0]` brackets linking nowhere and "what actually
changed between these two releases?" was zero clicks away instead of one.
0.4.2 compares against v0.4.0, not the v0.4.1 tag: 0.4.1 was tagged and
never published, which its own entry records. docs/RELEASING.md now tells
the next releaser to add a line, since a changelog convention that is not
in the checklist decays on its first release.

extract-changelog.sh slices the file by `## [` headings, so definitions at
the foot fell inside the oldest release's section and would have been
appended to v0.1.0's GitHub Release notes. It now stops at the first of
them. Verified by extracting all nineteen sections before and after: byte
identical.

docs/DESIGN.md §3 is the normative spec for the snapshot text format and
never mentioned `Screen::parse`, the function that reads it back — so
someone implementing against the format went to the rustdoc to discover it
round-trips at all. A new "Reading it back" subsection states what survives
the trip and what does not, in the facts `Screen::parse`'s rustdoc already
holds.

Also defines `[`Unsupported`]`, which 0.11.0's entry referenced with no
definition anywhere in the file.

Closes #305
Closes #319

Signed-off-by: Vyncint Ng <115854244+vyncint@users.noreply.github.com>
@vyncint
vyncint force-pushed the docs/changelog-links-and-parse-in-design branch from bc044d3 to e67177e Compare September 16, 2026 14:37
@vyncint
vyncint merged commit e2e9acf into main Sep 16, 2026
16 checks passed
@vyncint
vyncint deleted the docs/changelog-links-and-parse-in-design branch September 16, 2026 14:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

1 participant