From eb78f7acf6d47e5144e58bc9546bb4529d2d9cab Mon Sep 17 00:00:00 2001
From: Jamie Wells <jamiet.wells10@gmail.com>
Date: Wed, 28 Oct 2026 23:36:06 +0000
Subject: [PATCH 1/2] Announce installer releases in Change Log discussions

---
 .github/CI.md                           |  17 ++++
 .github/scripts/installer_release.py    |  99 +++++++++++++++++++++++
 .github/tests/test_installer_release.py | 100 +++++++++++++++++++++++-
 .github/workflows/installer-release.yml |   1 +
 4 files changed, 215 insertions(+), 2 deletions(-)

diff --git a/.github/CI.md b/.github/CI.md
index 98128444..1efa66a2 100644
--- a/.github/CI.md
+++ b/.github/CI.md
@@ -43,6 +43,23 @@ published as prereleases with the Windows `.exe` attached. Both build workflows
 share one publication concurrency group, and retrying a build or publication
 repairs the release for that commit rather than allocating another version.
 
+After the EXE upload and release publication succeed, the same job announces the
+release in Discussions → **Change Log** (category slug `change-log`). Each post
+includes direct EXE download links, a brief plain-text overview from the merged
+PR title, and changed file names with addition/deletion counts and expandable
+diff previews. File links open their full PR diffs; the post also links the full
+file list and downloadable patch. Binary files or diffs omitted by GitHub have
+links instead of previews. Large posts limit previews and direct readers to the
+complete file list to stay within GitHub's size limit. GitHub's PR-files API
+returns at most 3,000 files; the full diff and patch links remain available.
+
+The workflow token needs `discussions: write` alongside its existing permissions,
+and Discussions must contain the `change-log` category. Retrying publication
+updates the announcement identified by its hidden release-tag marker instead of
+creating a duplicate. Keep that marker when editing an announcement manually.
+An announcement failure fails the job but leaves the uploaded release available;
+fix category access or permissions and rerun the job to repair the announcement.
+
 The publishing workflow must be merged into the default branch before GitHub
 can trigger it. To diagnose publication, open `Publish installer release` in
 Actions. Missing/expired artifacts, missing merged-PR metadata, or insufficient
diff --git a/.github/scripts/installer_release.py b/.github/scripts/installer_release.py
index f06b92d4..22dcc2d9 100644
--- a/.github/scripts/installer_release.py
+++ b/.github/scripts/installer_release.py
@@ -1,11 +1,14 @@
 """Publish an already-built installer; never execute downloaded artifacts."""
 
+import hashlib
+import html
 import json
 import os
 from pathlib import Path
 import re
 import subprocess
 import tempfile
+from urllib.parse import quote
 
 
 VERSION = re.compile(r"v(\d+)\.(\d)-pre-alpha", re.IGNORECASE)
@@ -32,6 +35,101 @@ def next_tag(releases):
     return f"v{version // 10}.{version % 10}-Pre-Alpha"
 
 
+def graphql(query, **variables):
+    result = json.loads(gh("api", "graphql", "-f", f"query={query}", *(
+        arg for key, value in variables.items() for arg in ("-f", f"{key}={value}")
+    )))
+    if result.get("errors"):
+        raise RuntimeError(f"Discussion API failed: {result['errors']}")
+    return result["data"]
+
+
+def discussion_body(repository, tag, pr, installers, files):
+    root = f"https://github.com/{repository}"
+    pr_url = f"{root}/pull/{pr['number']}"
+    # A short plain-text overview from the merged PR; no copied Markdown body.
+    summary = html.escape(" ".join(pr["title"].split())[:240])
+    summary = re.sub(r"([\\`*_{}\[\]<>#|~])", r"\\\1", summary)
+    lines = [f"<!-- installer-release:{tag} -->", summary, ""]
+    for installer in installers:
+        url = f"{root}/releases/download/{quote(tag, safe='')}/{quote(installer.name, safe='')}"
+        lines.append(f"[Download {installer.name}]({url})")
+    lines += ["", f"[Release]({root}/releases/tag/{quote(tag, safe='')}) · "
+              f"[All changed files and full diff]({pr_url}/files) · "
+              f"[Download patch]({pr_url}.patch)", "", "## Files changed", ""]
+    # Keep well below GitHub's body limit, even for very large PRs.
+    for file in files:
+        name = file["filename"]
+        anchor = hashlib.sha256(name.encode("utf-8")).hexdigest()
+        label = html.escape(name).replace("`", "&#96;")
+        entry = [f"- [`{label}`]({pr_url}/files#diff-{anchor}) — "
+                 f"{file['status']}, +{file['additions']} / -{file['deletions']}"]
+        if file.get("previous_filename"):
+            entry.append("  Renamed from: " + html.escape(file["previous_filename"]))
+        patch = file.get("patch")
+        if patch:
+            preview = patch[:1200]
+            # An HTML pre block prevents source content from closing a Markdown fence.
+            entry += ["", "<details><summary>Diff preview</summary>", "",
+                      "<pre>" + html.escape(preview) + "</pre>", "",
+                      "See the file link for the complete diff.", "</details>", ""]
+        else:
+            entry += ["  Diff preview unavailable (binary or omitted by GitHub); see the file link.", ""]
+        if len(("\n".join(lines + entry)).encode("utf-8")) > 50000:
+            lines.append("More files are included in the full diff linked above.")
+            break
+        lines.extend(entry)
+    return "\n".join(lines)
+
+
+def announce(repository, tag, pr, installers):
+    owner, name = repository.split("/")
+    data = graphql("""query($owner:String!, $name:String!) {
+      repository(owner:$owner, name:$name) {
+        id discussionCategories(first:100) { nodes { id slug } }
+      }
+    }""", owner=owner, name=name)["repository"]
+    categories = [c for c in data["discussionCategories"]["nodes"] if c["slug"] == "change-log"]
+    if len(categories) != 1:
+        raise ValueError("The change-log Discussion category is missing or inaccessible.")
+    category = categories[0]["id"]
+    marker = f"<!-- installer-release:{tag} -->"
+    cursor = ""
+    discussion_id = None
+    while True:
+        page = graphql("""query($owner:String!, $name:String!, $category:ID!, $cursor:String) {
+          repository(owner:$owner, name:$name) {
+            discussions(first:100, categoryId:$category, after:$cursor) {
+              nodes { id body } pageInfo { hasNextPage endCursor }
+            }
+          }
+        }""", owner=owner, name=name, category=category,
+            **({"cursor": cursor} if cursor else {}))["repository"]["discussions"]
+        matches = [d["id"] for d in page["nodes"] if d["body"].startswith(marker + "\n")]
+        if matches:
+            discussion_id = matches[0]
+            break
+        if not page["pageInfo"]["hasNextPage"]:
+            break
+        cursor = page["pageInfo"]["endCursor"]
+    files = api_list(f"repos/{repository}/pulls/{pr['number']}/files?per_page=100")
+    body = discussion_body(repository, tag, pr, installers, files)
+    title = f"{tag} — Windows installer"
+    if discussion_id:
+        result = graphql("""mutation($id:ID!, $title:String!, $body:String!) {
+          updateDiscussion(input:{discussionId:$id, title:$title, body:$body}) {
+            discussion { url }
+          }
+        }""", id=discussion_id, title=title, body=body)["updateDiscussion"]
+    else:
+        result = graphql("""mutation($repo:ID!, $category:ID!, $title:String!, $body:String!) {
+          createDiscussion(input:{repositoryId:$repo, categoryId:$category, title:$title, body:$body}) {
+            discussion { url }
+          }
+        }""", repo=data["id"], category=category, title=title, body=body)["createDiscussion"]
+    print(f"Announced {tag}: {result['discussion']['url']}")
+
+
 def publish(repository, run, directory):
     if (
         run["conclusion"] != "success"
@@ -83,6 +181,7 @@ def publish(repository, run, directory):
         if not existing or existing[0]["draft"]:
             gh("release", "edit", tag, "--repo", repository, "--draft=false")
     print(f"Published {tag}: https://github.com/{repository}/releases/tag/{tag}")
+    announce(repository, tag, pulls[0], installers)
 
 
 if __name__ == "__main__":
diff --git a/.github/tests/test_installer_release.py b/.github/tests/test_installer_release.py
index d777db89..36cee23a 100644
--- a/.github/tests/test_installer_release.py
+++ b/.github/tests/test_installer_release.py
@@ -57,8 +57,12 @@ def gh(*args):
 
         with patch.object(release, "api_list", side_effect=[
             [self.pr] if pulls is None else pulls, list(releases)
-        ]), patch.object(release, "gh", side_effect=gh):
+        ]), patch.object(release, "gh", side_effect=gh), \
+                patch.object(release, "announce") as announce:
             release.publish(REPOSITORY, self.run, self.temp.name)
+            announce.assert_called_once_with(
+                REPOSITORY, calls[0][2], self.pr, [self.installer]
+            )
         return calls
 
     def test_new_release_uses_exact_pr_body_commit_and_installer(self):
@@ -89,11 +93,13 @@ def test_retry_reuses_release_and_repairs_assets(self):
 
     def test_upload_failure_leaves_draft_unpublished(self):
         with patch.object(release, "api_list", side_effect=[[self.pr], []]), \
-                patch.object(release, "gh", side_effect=["", RuntimeError("upload failed")]) as gh:
+                patch.object(release, "gh", side_effect=["", RuntimeError("upload failed")]) as gh, \
+                patch.object(release, "announce") as announce:
             with self.assertRaisesRegex(RuntimeError, "upload failed"):
                 release.publish(REPOSITORY, self.run, self.temp.name)
             self.assertEqual(gh.call_count, 2)
             self.assertIn("--draft", gh.call_args_list[0].args)
+            announce.assert_not_called()
 
     def test_untrusted_or_unsuccessful_runs_cannot_publish(self):
         changes = [
@@ -135,5 +141,95 @@ def test_api_list_reads_all_pages(self):
             gh.assert_called_once_with("api", "repos/example/engine/releases", "--paginate", "--slurp")
 
 
+class DiscussionTests(unittest.TestCase):
+    def setUp(self):
+        self.pr = {"number": 42, "title": "Fix editor startup"}
+        self.installers = [Path("RusticGameEngine-Setup-0.1.exe")]
+        self.file = {
+            "filename": "Engine/main.rs", "status": "modified",
+            "additions": 2, "deletions": 1, "patch": "@@ -1 +1 @@\n-old\n+new",
+        }
+        self.repository = {"repository": {
+            "id": "repo", "discussionCategories": {
+                "nodes": [{"id": "category", "slug": "change-log"}]
+            },
+        }}
+
+    def page(self, nodes=(), more=False, cursor=None):
+        return {"repository": {"discussions": {
+            "nodes": list(nodes), "pageInfo": {"hasNextPage": more, "endCursor": cursor}
+        }}}
+
+    def test_body_includes_download_overview_files_and_diffs(self):
+        body = release.discussion_body(REPOSITORY, "v0.2-Pre-Alpha", self.pr,
+                                       self.installers, [self.file])
+        for text in ["Fix editor startup", "/releases/download/v0.2-Pre-Alpha/",
+                     self.installers[0].name, "Engine/main.rs", "+2 / -1", "+new",
+                     "/pull/42/files#diff-", "/pull/42.patch"]:
+            self.assertIn(text, body)
+
+    def test_large_and_binary_diffs_have_full_diff_links(self):
+        files = [self.file | {"filename": f"file-{i}", "patch": "x" * 10000}
+                 for i in range(100)]
+        files.insert(0, self.file | {"filename": "image.png", "patch": None})
+        body = release.discussion_body(REPOSITORY, "tag", self.pr, self.installers, files)
+        self.assertLess(len(body.encode("utf-8")), 51000)
+        self.assertIn("binary or omitted", body)
+        self.assertIn("More files", body)
+        self.assertIn("/pull/42/files", body)
+
+    def test_source_cannot_close_preview_or_inject_html(self):
+        file = self.file | {"patch": "+</pre><script>alert(1)</script>\n+```"}
+        body = release.discussion_body(REPOSITORY, "tag", self.pr, self.installers, [file])
+        self.assertNotIn("<script>", body)
+        self.assertIn("&lt;/pre&gt;", body)
+
+    def test_create_uses_category_and_retry_updates_existing_on_later_page(self):
+        for existing in (False, True):
+            with self.subTest(existing=existing):
+                pages = [self.page()]
+                operation = "createDiscussion"
+                if existing:
+                    pages = [self.page(more=True, cursor="next"), self.page([{
+                        "id": "discussion", "body": "<!-- installer-release:tag -->\nold"
+                    }])]
+                    operation = "updateDiscussion"
+                responses = [self.repository, *pages, {operation: {"discussion": {"url": "url"}}}]
+                with patch.object(release, "graphql", side_effect=responses) as graphql, \
+                        patch.object(release, "api_list", return_value=[self.file]) as api:
+                    release.announce(REPOSITORY, "tag", self.pr, self.installers)
+                api.assert_called_once_with(f"repos/{REPOSITORY}/pulls/42/files?per_page=100")
+                mutation = graphql.call_args
+                self.assertIn(operation, mutation.args[0])
+                self.assertIn("Fix editor startup", mutation.kwargs["body"])
+                if existing:
+                    self.assertEqual(mutation.kwargs["id"], "discussion")
+                    self.assertEqual(graphql.call_args_list[2].kwargs["cursor"], "next")
+                else:
+                    self.assertEqual(mutation.kwargs["category"], "category")
+
+    def test_missing_category_fails_clearly(self):
+        self.repository["repository"]["discussionCategories"]["nodes"] = []
+        with patch.object(release, "graphql", return_value=self.repository):
+            with self.assertRaisesRegex(ValueError, "change-log"):
+                release.announce(REPOSITORY, "tag", self.pr, self.installers)
+
+    def test_graphql_reports_api_errors(self):
+        with patch.object(release, "gh", return_value='{"errors":[{"message":"denied"}]}'):
+            with self.assertRaisesRegex(RuntimeError, "denied"):
+                release.graphql("query {}")
+
+    def test_announcement_failure_keeps_release_published_for_retry(self):
+        fixture = InstallerReleaseTests()
+        fixture.setUp()
+        self.addCleanup(fixture.doCleanups)
+        with patch.object(release, "api_list", side_effect=[[fixture.pr], []]), \
+                patch.object(release, "gh", return_value="") as gh, \
+                patch.object(release, "announce", side_effect=RuntimeError("denied")):
+            with self.assertRaisesRegex(RuntimeError, "denied"):
+                release.publish(REPOSITORY, fixture.run, fixture.temp.name)
+        self.assertEqual(gh.call_args.args[-1], "--draft=false")
+
+
 if __name__ == "__main__":
     unittest.main()
diff --git a/.github/workflows/installer-release.yml b/.github/workflows/installer-release.yml
index 7fdb436f..27386180 100644
--- a/.github/workflows/installer-release.yml
+++ b/.github/workflows/installer-release.yml
@@ -9,6 +9,7 @@ permissions:
   contents: write
   actions: read
   pull-requests: read
+  discussions: write
 
 # Both build workflows share one version sequence. Never cancel an asset upload.
 concurrency:

From b42d4a97b2b556cd0d72783f9676f9f1013eb454 Mon Sep 17 00:00:00 2001
From: Jamie Wells <jamiet.wells10@gmail.com>
Date: Wed, 28 Oct 2026 23:38:50 +0000
Subject: [PATCH 2/2] Link published docs and commit diffs and sync
 announcement labels

---
 .github/CI.md                           | 27 ++++++++-
 .github/scripts/installer_release.py    | 60 ++++++++++++++----
 .github/tests/test_installer_release.py | 81 +++++++++++++++++++++++--
 3 files changed, 148 insertions(+), 20 deletions(-)

diff --git a/.github/CI.md b/.github/CI.md
index 1efa66a2..e9a01493 100644
--- a/.github/CI.md
+++ b/.github/CI.md
@@ -47,16 +47,39 @@ After the EXE upload and release publication succeed, the same job announces the
 release in Discussions → **Change Log** (category slug `change-log`). Each post
 includes direct EXE download links, a brief plain-text overview from the merged
 PR title, and changed file names with addition/deletion counts and expandable
-diff previews. File links open their full PR diffs; the post also links the full
-file list and downloadable patch. Binary files or diffs omitted by GitHub have
+diff previews. File links open a comparison of the PR's recorded base commit and
+release merge commit; the post also links the full file list and downloadable
+patch. Announcements contain no PR links. Binary files or diffs omitted by GitHub have
 links instead of previews. Large posts limit previews and direct readers to the
 complete file list to stay within GitHub's size limit. GitHub's PR-files API
 returns at most 3,000 files; the full diff and patch links remain available.
 
+To associate the correct documentation update, add a line to the engine PR
+description pointing to the affected **published page**, for example:
+
+```text
+Documentation: https://rustic-game-engine.pages.dev/docs/guides/gameplay-programming#hot-reload
+```
+
+Repeat the line for additional updated pages; duplicate URLs are removed. Use
+the canonical documentation site's `/docs/` URLs, including section anchors when
+helpful. Publish the documentation update before the release announcement. Do not
+put a documentation PR URL in this field. The announcement copies only these
+published-page URLs and never copies the PR description. For maintenance changes
+without a documentation update, explicitly use `Documentation: none`; no docs
+link is added. Missing or invalid mappings fail the announcement with instructions
+to fix the merged engine PR's description and rerun publication. The automation
+does not guess a matching update by title or choose the latest documentation PR,
+and does not verify that the declared page has deployed.
+
 The workflow token needs `discussions: write` alongside its existing permissions,
 and Discussions must contain the `change-log` category. Retrying publication
 updates the announcement identified by its hidden release-tag marker instead of
 creating a duplicate. Keep that marker when editing an announcement manually.
+The announcement copies all labels from the merged engine PR. Reruns synchronize
+the Discussion's labels to the PR's current labels, adding missing labels and
+removing labels no longer present on the PR (including manually added Discussion
+labels). Label failures fail the job and can be repaired with a rerun.
 An announcement failure fails the job but leaves the uploaded release available;
 fix category access or permissions and rerun the job to repair the announcement.
 
diff --git a/.github/scripts/installer_release.py b/.github/scripts/installer_release.py
index 22dcc2d9..e603ad50 100644
--- a/.github/scripts/installer_release.py
+++ b/.github/scripts/installer_release.py
@@ -12,6 +12,24 @@
 
 
 VERSION = re.compile(r"v(\d+)\.(\d)-pre-alpha", re.IGNORECASE)
+DOCS_ROOT = "https://rustic-game-engine.pages.dev/docs/"
+
+
+def documentation_links(pr):
+    """Require an explicit mapping to published pages, never infer a docs PR."""
+    entries = re.findall(r"^Documentation:[ \t]*(.+)$", pr.get("body") or "", re.MULTILINE)
+    if not entries:
+        raise ValueError("Add Documentation: <published docs URL> to the merged PR description "
+                         "(or Documentation: none for changes without a documentation update).")
+    if len(entries) == 1 and entries[0].strip().lower() == "none":
+        return []
+    urls = []
+    for entry in entries:
+        found = re.findall(re.escape(DOCS_ROOT) + r"[A-Za-z0-9_./%~-]+(?:#[A-Za-z0-9_.%~-]+)?", entry)
+        if not found:
+            raise ValueError("Documentation must link to a published page under " + DOCS_ROOT)
+        urls.extend(found)
+    return list(dict.fromkeys(urls))
 
 
 def gh(*args):
@@ -36,9 +54,10 @@ def next_tag(releases):
 
 
 def graphql(query, **variables):
-    result = json.loads(gh("api", "graphql", "-f", f"query={query}", *(
-        arg for key, value in variables.items() for arg in ("-f", f"{key}={value}")
-    )))
+    with tempfile.TemporaryDirectory() as temp:
+        payload = Path(temp) / "graphql.json"
+        payload.write_text(json.dumps({"query": query, "variables": variables}), encoding="utf-8")
+        result = json.loads(gh("api", "graphql", "--input", str(payload)))
     if result.get("errors"):
         raise RuntimeError(f"Discussion API failed: {result['errors']}")
     return result["data"]
@@ -46,7 +65,7 @@ def graphql(query, **variables):
 
 def discussion_body(repository, tag, pr, installers, files):
     root = f"https://github.com/{repository}"
-    pr_url = f"{root}/pull/{pr['number']}"
+    compare_url = f"{root}/compare/{pr['base']['sha']}...{pr['merge_commit_sha']}"
     # A short plain-text overview from the merged PR; no copied Markdown body.
     summary = html.escape(" ".join(pr["title"].split())[:240])
     summary = re.sub(r"([\\`*_{}\[\]<>#|~])", r"\\\1", summary)
@@ -54,15 +73,17 @@ def discussion_body(repository, tag, pr, installers, files):
     for installer in installers:
         url = f"{root}/releases/download/{quote(tag, safe='')}/{quote(installer.name, safe='')}"
         lines.append(f"[Download {installer.name}]({url})")
+    for url in documentation_links(pr):
+        lines.append(f"[Updated documentation]({url})")
     lines += ["", f"[Release]({root}/releases/tag/{quote(tag, safe='')}) · "
-              f"[All changed files and full diff]({pr_url}/files) · "
-              f"[Download patch]({pr_url}.patch)", "", "## Files changed", ""]
+              f"[All changed files and full diff]({compare_url}) · "
+              f"[Download patch]({compare_url}.patch)", "", "## Files changed", ""]
     # Keep well below GitHub's body limit, even for very large PRs.
     for file in files:
         name = file["filename"]
         anchor = hashlib.sha256(name.encode("utf-8")).hexdigest()
         label = html.escape(name).replace("`", "&#96;")
-        entry = [f"- [`{label}`]({pr_url}/files#diff-{anchor}) — "
+        entry = [f"- [`{label}`]({compare_url}#diff-{anchor}) — "
                  f"{file['status']}, +{file['additions']} / -{file['deletions']}"]
         if file.get("previous_filename"):
             entry.append("  Renamed from: " + html.escape(file["previous_filename"]))
@@ -100,14 +121,16 @@ def announce(repository, tag, pr, installers):
         page = graphql("""query($owner:String!, $name:String!, $category:ID!, $cursor:String) {
           repository(owner:$owner, name:$name) {
             discussions(first:100, categoryId:$category, after:$cursor) {
-              nodes { id body } pageInfo { hasNextPage endCursor }
+              nodes { id body labels(first:100) { nodes { id } } }
+              pageInfo { hasNextPage endCursor }
             }
           }
         }""", owner=owner, name=name, category=category,
             **({"cursor": cursor} if cursor else {}))["repository"]["discussions"]
-        matches = [d["id"] for d in page["nodes"] if d["body"].startswith(marker + "\n")]
+        matches = [d for d in page["nodes"] if d["body"].startswith(marker + "\n")]
         if matches:
-            discussion_id = matches[0]
+            discussion_id = matches[0]["id"]
+            existing_labels = {label["id"] for label in matches[0]["labels"]["nodes"]}
             break
         if not page["pageInfo"]["hasNextPage"]:
             break
@@ -118,16 +141,27 @@ def announce(repository, tag, pr, installers):
     if discussion_id:
         result = graphql("""mutation($id:ID!, $title:String!, $body:String!) {
           updateDiscussion(input:{discussionId:$id, title:$title, body:$body}) {
-            discussion { url }
+            discussion { id url }
           }
         }""", id=discussion_id, title=title, body=body)["updateDiscussion"]
     else:
         result = graphql("""mutation($repo:ID!, $category:ID!, $title:String!, $body:String!) {
           createDiscussion(input:{repositoryId:$repo, categoryId:$category, title:$title, body:$body}) {
-            discussion { url }
+            discussion { id url }
           }
         }""", repo=data["id"], category=category, title=title, body=body)["createDiscussion"]
-    print(f"Announced {tag}: {result['discussion']['url']}")
+    discussion = result["discussion"]
+    wanted_labels = {label["node_id"] for label in pr.get("labels", [])}
+    if not discussion_id:
+        existing_labels = set()
+    # Apply additions first so a failed retry retains labels already attached.
+    for operation, labels in (("addLabelsToLabelable", wanted_labels - existing_labels),
+                              ("removeLabelsFromLabelable", existing_labels - wanted_labels)):
+        if labels:
+            graphql(f"""mutation($id:ID!, $labels:[ID!]!) {{
+              {operation}(input:{{labelableId:$id, labelIds:$labels}}) {{ clientMutationId }}
+            }}""", id=discussion["id"], labels=sorted(labels))
+    print(f"Announced {tag}: {discussion['url']}")
 
 
 def publish(repository, run, directory):
diff --git a/.github/tests/test_installer_release.py b/.github/tests/test_installer_release.py
index 36cee23a..245cb877 100644
--- a/.github/tests/test_installer_release.py
+++ b/.github/tests/test_installer_release.py
@@ -143,7 +143,11 @@ def test_api_list_reads_all_pages(self):
 
 class DiscussionTests(unittest.TestCase):
     def setUp(self):
-        self.pr = {"number": 42, "title": "Fix editor startup"}
+        self.pr = {
+            "number": 42, "title": "Fix editor startup", "merge_commit_sha": SHA,
+            "base": {"sha": "b" * 40},
+            "body": "Documentation: https://rustic-game-engine.pages.dev/docs/engine",
+        }
         self.installers = [Path("RusticGameEngine-Setup-0.1.exe")]
         self.file = {
             "filename": "Engine/main.rs", "status": "modified",
@@ -165,8 +169,29 @@ def test_body_includes_download_overview_files_and_diffs(self):
                                        self.installers, [self.file])
         for text in ["Fix editor startup", "/releases/download/v0.2-Pre-Alpha/",
                      self.installers[0].name, "Engine/main.rs", "+2 / -1", "+new",
-                     "/pull/42/files#diff-", "/pull/42.patch"]:
+                     f"/compare/{'b' * 40}...{SHA}#diff-", f"...{SHA}.patch",
+                     "[Updated documentation](https://rustic-game-engine.pages.dev/docs/engine)"]:
             self.assertIn(text, body)
+        self.assertNotIn("/pull/", body)
+
+    def test_documentation_uses_explicit_pages_and_deduplicates(self):
+        url = release.DOCS_ROOT + "guides/gameplay-programming#hot-reload"
+        self.pr["body"] = (f"Documentation: [Gameplay guide]({url})\n"
+                           f"Documentation: {url}\n"
+                           "Unrelated: https://github.com/example/docs/pull/123")
+        self.assertEqual(release.documentation_links(self.pr), [url])
+        body = release.discussion_body(REPOSITORY, "tag", self.pr, self.installers, [])
+        self.assertIn(f"[Updated documentation]({url})", body)
+        self.assertNotIn("/pull/", body)
+
+    def test_documentation_none_is_explicit_and_missing_mapping_fails(self):
+        self.assertEqual(release.documentation_links({"body": "Documentation: none"}), [])
+        for body in (None, "", "Unrelated docs link: " + release.DOCS_ROOT + "engine",
+                     "Documentation: https://github.com/example/docs/pull/123",
+                     "Documentation: https://unrelated.example/docs/engine",
+                     "Documentation: none\nDocumentation: " + release.DOCS_ROOT + "engine"):
+            with self.subTest(body=body), self.assertRaisesRegex(ValueError, "Documentation"):
+                release.documentation_links({"body": body})
 
     def test_large_and_binary_diffs_have_full_diff_links(self):
         files = [self.file | {"filename": f"file-{i}", "patch": "x" * 10000}
@@ -176,7 +201,7 @@ def test_large_and_binary_diffs_have_full_diff_links(self):
         self.assertLess(len(body.encode("utf-8")), 51000)
         self.assertIn("binary or omitted", body)
         self.assertIn("More files", body)
-        self.assertIn("/pull/42/files", body)
+        self.assertIn(f"/compare/{'b' * 40}...{SHA}", body)
 
     def test_source_cannot_close_preview_or_inject_html(self):
         file = self.file | {"patch": "+</pre><script>alert(1)</script>\n+```"}
@@ -191,10 +216,13 @@ def test_create_uses_category_and_retry_updates_existing_on_later_page(self):
                 operation = "createDiscussion"
                 if existing:
                     pages = [self.page(more=True, cursor="next"), self.page([{
-                        "id": "discussion", "body": "<!-- installer-release:tag -->\nold"
+                        "id": "discussion", "body": "<!-- installer-release:tag -->\nold",
+                        "labels": {"nodes": []},
                     }])]
                     operation = "updateDiscussion"
-                responses = [self.repository, *pages, {operation: {"discussion": {"url": "url"}}}]
+                responses = [self.repository, *pages, {operation: {
+                    "discussion": {"id": "discussion", "url": "url"}
+                }}]
                 with patch.object(release, "graphql", side_effect=responses) as graphql, \
                         patch.object(release, "api_list", return_value=[self.file]) as api:
                     release.announce(REPOSITORY, "tag", self.pr, self.installers)
@@ -219,6 +247,49 @@ def test_graphql_reports_api_errors(self):
             with self.assertRaisesRegex(RuntimeError, "denied"):
                 release.graphql("query {}")
 
+    def test_graphql_passes_label_arrays_as_json(self):
+        def gh(*args):
+            import json
+            payload = json.loads(Path(args[-1]).read_text(encoding="utf-8"))
+            self.assertEqual(payload["variables"], {"labels": ["one", "two"]})
+            return '{"data":{}}'
+        with patch.object(release, "gh", side_effect=gh):
+            release.graphql("mutation {}", labels=["one", "two"])
+
+    def test_discussion_labels_copy_and_sync_on_retry(self):
+        for existing in (False, True):
+            with self.subTest(existing=existing):
+                self.pr["labels"] = [{"node_id": "feature"}, {"node_id": "ci"}]
+                nodes = [{"id": "discussion", "body": "<!-- installer-release:tag -->\nold",
+                          "labels": {"nodes": [{"id": "ci"}, {"id": "old"}]}}] if existing else []
+                operation = "updateDiscussion" if existing else "createDiscussion"
+                responses = [self.repository, self.page(nodes), {operation: {
+                    "discussion": {"id": "discussion", "url": "url"}
+                }}, {}, *([{}] if existing else [])]
+                with patch.object(release, "graphql", side_effect=responses) as graphql, \
+                        patch.object(release, "api_list", return_value=[self.file]):
+                    release.announce(REPOSITORY, "tag", self.pr, self.installers)
+                add = graphql.call_args_list[3]
+                self.assertIn("addLabelsToLabelable", add.args[0])
+                self.assertEqual(add.kwargs, {"id": "discussion", "labels": (
+                    ["feature"] if existing else ["ci", "feature"]
+                )})
+                if existing:
+                    remove = graphql.call_args_list[4]
+                    self.assertIn("removeLabelsFromLabelable", remove.args[0])
+                    self.assertEqual(remove.kwargs["labels"], ["old"])
+
+    def test_empty_pr_labels_remove_old_discussion_labels(self):
+        responses = [self.repository, self.page([{
+            "id": "discussion", "body": "<!-- installer-release:tag -->\nold",
+            "labels": {"nodes": [{"id": "old"}]},
+        }]), {"updateDiscussion": {"discussion": {"id": "discussion", "url": "url"}}}, {}]
+        with patch.object(release, "graphql", side_effect=responses) as graphql, \
+                patch.object(release, "api_list", return_value=[]):
+            release.announce(REPOSITORY, "tag", self.pr, self.installers)
+        self.assertIn("removeLabelsFromLabelable", graphql.call_args.args[0])
+        self.assertEqual(graphql.call_args.kwargs["labels"], ["old"])
+
     def test_announcement_failure_keeps_release_published_for_retry(self):
         fixture = InstallerReleaseTests()
         fixture.setUp()