docs: link every changelog version, name the parser in the spec - #358
Merged
Merged
Conversation
vyncint
force-pushed
the
docs/changelog-links-and-parse-in-design
branch
2 times, most recently
from
September 16, 2026 13:18
7d45687 to
bc044d3
Compare
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
force-pushed
the
docs/changelog-links-and-parse-in-design
branch
from
September 16, 2026 14:37
bc044d3 to
e67177e
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Two documentation issues, and one gate change they needed.
Every version heading links to its diff (#319)
CHANGELOG.mdsays in its header that it follows Keep a Changelog, whoseformat 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 comparesv0.11.0to
HEAD.Two judgement calls worth reviewing:
[0.4.2]compares againstv0.4.0, notv0.4.1. Thev0.4.1tagexists 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 compareit against.
extract-changelog.shstops at the definitionsThis 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 oldestsection, 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 byextracting all nineteen sections before and after the change —
byte-identical (
diff -r), which is the Done-when box. And verified to beload-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 theperson who needs it is looking.
docs/RELEASING.mdstep 2A 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 newversion's line, shows the two lines, and suggests running
extract-changelog.sh X.Y.Zto 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:
parseaccepts, and that thetermlensCLI'sdiffandrenderare built on it;
same
styles:block,diffs empty — and not==, with rule 5's ownequality paragraph as the reason;
character either way, out-of-band state comes back default, and a hidden
cursor's position is not recorded so
cursor: hiddenparses back at0,0;ambiguous input that follows from it.
Every claim is taken from
Screen::parse's rustdoc and the tests thatalready 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 apointer 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 nodefinition 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.shfor 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
#319asksfor 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.
each confirmed to exist on
origin, which is what determines whether theURL resolves.
Closes #305
Closes #319