Skip to content

build(release): tools/release_notes.py for GitHub release text - #391

Merged
homer6 merged 1 commit into
devfrom
docs/390-release-notes-unwrap
Nov 4, 2026
Merged

homer6 merged 1 commit into
devfrom
docs/390-release-notes-unwrap

Conversation

@homer6

@homer6 homer6 commented Nov 4, 2026

Copy link
Copy Markdown
Owner

Closes #390.

GitHub shows every newline in a release description as a line break. Our notes pages are wrapped at about 78 columns, so every GitHub release so far showed its sentences broken mid-line. The release step only made the links absolute.

Changes

  • tools/release_notes.py vX.Y.Z: prints the GitHub release text for docs/releases/vX.Y.Z.md.
    • It joins the wrapped lines of each paragraph, list item and quote.
    • It leaves headings, tables, fenced code, HTML comments and Markdown hard breaks alone.
    • It makes relative links absolute at the tag (tree/ for a link that ends in /), and errors on a link that points outside the repo.
    • --self-test runs 11 built-in samples.
  • CLAUDE.md: release checklist step 5 now publishes and edits the release from the script, and says why.
  • docs/releases/README.md: one sentence pointing to the script.
  • README.md: not changed. This is a release tool, not a reader-facing feature.

Already done outside this PR

I rewrote the descriptions of all six releases, v0.1.0–v0.5.0, the same way:

  • The rendered <br> count is now 0 on each, with the tables and the v0.4.0 quote intact.
  • A word-by-word comparison of each description before and after found no difference, apart from the > markers of joined quote lines.

Tested

  • Self-test: python3 tools/release_notes.py --self-test gives OK (11 samples). It caught a bug where a blank > line was merged into the next quote line, which is now fixed. No published release has a blank quote line.
  • Against the published releases:
    • For v0.5.0, tools/release_notes.py v0.5.0 matches the published description byte for byte.
    • For v0.1.0–v0.4.0, the output matches what's published, apart from trailing blank lines and the tree/ folder links.
  • Repo checks: check_links.py CLAUDE.md docs/releases/README.md passes, and gen_index.py --check reports the index up to date.

GitHub shows every newline in a release description as a line break, so
the wrapped notes pages broke mid-sentence on every release page. The
script joins wrapped paragraph, list and quote lines and makes relative
links absolute at the tag; the release checklist names it.

Related to #390
@homer6 homer6 self-assigned this Nov 4, 2026
@homer6
homer6 merged commit 7d9c49a into dev Nov 4, 2026
@homer6
homer6 deleted the docs/390-release-notes-unwrap branch November 4, 2026 15:57
@homer6

homer6 commented Nov 4, 2026

Copy link
Copy Markdown
Owner Author

Merged into dev as a merge commit (7d9c49aa) on Steve's review. Checked: --self-test OK (11 samples); tools/release_notes.py v0.5.0 matches the published v0.5.0 description byte for byte; links and index checks pass. The six release descriptions were already rewritten on GitHub. Still owed: Steve asked to include this PR in v0.5.0, so a re-release follows.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant