Docs: resolve the changelog's links from the repository root

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.
 

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.

docs/changelog.md

@@ -1,2 +1,3 @@
 ```{include} ../CHANGELOG.md
+:relative-docs: docs/
 ```

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}"