docs: publish the library changelogs - #650
Draft
tonyandrewmeyer wants to merge 3 commits into
Draft
tonyandrewmeyer wants to merge 3 commits into
tonyandrewmeyer wants to merge 3 commits into
Conversation
Every library has a CHANGELOG.md at its package root, but you can only read it by finding the right folder in the repo. Copy each one into the reference tree during preprocessing, under a per-library heading, and give them a Change logs page in the Reference section. Three heading conventions are in use: a per-version H1, a prose "# Changelog" with H2 versions, and Keep a Changelog with bracketed versions. A leading prose heading is dropped rather than demoted, so those pages don't carry a redundant Changelog section under their own title, and any remaining H1 is demoted so each page has one top-level heading.
Contributor
Author
|
@james-garner-canonical maybe we could talk about this and #649 together? |
tonyandrewmeyer
commented
Aug 31, 2026
Collaborator
Sure. I think this one would actually be fine to land essentially as-is, since it only requires the changelogs to be valid markdown. We could standardise accepted formats later, and build fancy things on top of that later if we wanted to. |
…"Changelog" The heuristic dropped a leading H1 whose text doesn't start with a digit, to get rid of the prose `# Changelog` the interfaces packages open with. That also deletes `# Unreleased`, which is how `nginx_k8s/CHANGELOG.md` opens: its entries ended up directly under the page title, reading as page intro, immediately above a released version they have nothing to do with. A released `# v1.2.3 - 4 May 2026` would go the same way, which is the worse version of the same bug. The prose heading is now matched by name. Every changelog test built its own fixture, so the suite never saw the files the code exists to process, and the fourth convention had been sitting in the repo the whole time with 63 tests passing. The real files are now parametrised over: the injected heading must be the only H1, and every heading in the source has to survive at one level deeper. That test fails on `nginx_k8s` without the regex change, and it will catch the fifth convention when someone invents it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
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
2 participants
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.
Every library has a
CHANGELOG.mdat its package root, but the only way to read one is to find the right folder in the repo, so nothing on the docs site tells you what changed in a release. This copies each of them into the reference tree during preprocessing and adds a Change logs page to the Reference section, so there's a page per library with the versions as subsections.Three heading conventions turned out to be in use: most packages go straight to a per-version H1 (
# 1.3.0 - 2 June 2026), the interfaces packages open with a prose# Changelogand use H2 for versions, andotlpandslothuse Keep a Changelog with bracketed versions. A leading prose heading is dropped rather than demoted - otherwise those pages get a redundantChangelogsection directly under their own title - and any remaining H1 is demoted so each page has exactly one top-level heading.just docs htmlproduces 23 pages and they all come out with a single H1 and version H2s.Preview.
Fixes #389