From 0533bebc87f15a0d6c9caa9774226e892027e6b6 Mon Sep 17 00:00:00 2001 From: John Travers Date: Wed, 4 Nov 2026 22:28:58 +0000 Subject: [PATCH] Docs: resolve the changelog's links from the repository root The manual includes CHANGELOG.md from docs/changelog.md without saying where its links start, so the first fragment to link a page failed the documentation build on the rolling release pull request, and would have failed the release. A test now checks fragments' links, so a bad one fails on the pull request that adds it. Co-Authored-By: Claude Opus 5.5 --- changelog.d/README.md | 4 +++- changelog.d/changelog-links.fixed.md | 1 + docs/changelog.md | 1 + tests/test_release_metadata.py | 15 +++++++++++++++ 4 files changed, 20 insertions(+), 1 deletion(-) create mode 100644 changelog.d/changelog-links.fixed.md diff --git a/changelog.d/README.md b/changelog.d/README.md index a1be0a2..c662e3b 100644 --- a/changelog.d/README.md +++ b/changelog.d/README.md @@ -16,7 +16,9 @@ Write one entry without a heading or leading bullet. Describe the observable cha including migration instructions for a break, and say whether a recommended value moved. Cite register entries as `TC-n` and OEPs by number; `poe register-sync` renumbers a fragment's citations with the rest of the branch, and `tests/test_register.py` checks -them. Markdown links are relative to the root `CHANGELOG.md`, where the text will appear. +them. Markdown links are relative to the root `CHANGELOG.md`, where the text will appear, +and must point to a page under `docs/`, since the manual includes the changelog; use a full +URL for anything else. `tests/test_release_metadata.py` checks them. Use a unique slug to avoid conflicts. A later correction can edit the original fragment while it is still pending. diff --git a/changelog.d/changelog-links.fixed.md b/changelog.d/changelog-links.fixed.md new file mode 100644 index 0000000..8c44eab --- /dev/null +++ b/changelog.d/changelog-links.fixed.md @@ -0,0 +1 @@ +A release note can link a page of the manual: the manual's changelog page now resolves links from the repository root, as `changelog.d/README.md` says. No value, model or public name changed. diff --git a/docs/changelog.md b/docs/changelog.md index 66efc0f..03395c5 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -1,2 +1,3 @@ ```{include} ../CHANGELOG.md +:relative-docs: docs/ ``` diff --git a/tests/test_release_metadata.py b/tests/test_release_metadata.py index 29ec8f6..aacfe32 100644 --- a/tests/test_release_metadata.py +++ b/tests/test_release_metadata.py @@ -60,3 +60,18 @@ def test_the_citation_names_the_latest_release(): _scalar(citation, "version"), _scalar(citation, "date-released"), ) == released[0] + + +def test_changelog_links_resolve_in_the_manual(): + # A fragment's link first reaches the manual when the release pull request collects + # it, and a broken one then fails the documentation build, so check it here. + include = (ROOT / "docs/changelog.md").read_text(encoding="utf-8") + assert ":relative-docs: docs/" in include + notes = [ROOT / "CHANGELOG.md", *(ROOT / "changelog.d").glob("*.*.md")] + for path in notes: + text = path.read_text(encoding="utf-8") + for target in re.findall(r"\]\(([^)#\s]+)[^)]*\)", text): + if re.match(r"[a-z]+:", target): + continue + assert target.startswith("docs/"), f"{path.name}: {target}" + assert (ROOT / target).is_file(), f"{path.name}: {target}"