fix(release): retain upstream refs in highlights

Collect owner/repository#number references from Upstream-Ref, Bug-Ref, Refs, and Follow-up-To trailers and append any that an explicit or fallback highlight omits. Apply the same behavior to stack component commits and keep integration-harness fixes out of automatic user-facing highlights.

Document the trailer contract and cover component-derived references plus integration-scope suppression in the release-note tests.

Author: stephenlclarke

BRANCHES.md

@@ -54,7 +54,7 @@ make repackage-release VERSION=MAJOR.MINOR.PATCH
 
 `make repackage-release VERSION=MAJOR.MINOR.PATCH` repairs an existing stable tag without moving it. It dispatches the stable package workflow again, verifies the release archive, checksum asset, Homebrew formula URL, version, and SHA, then syncs the checked-in source formula template to the verified release asset.
 
-Release notes are rendered by [Tools/release/release-notes.py](Tools/release/release-notes.py). The notes include a raw commit audit list, and they promote user-facing `Release-Note:` or `Release-Highlight:` commit trailers into a `Highlights` section before that list. Use single-line trailers that describe the Docker Compose feature, CLI option, or workflow users now get; internal release, CI, and documentation chores should normally omit the trailer or use `Release-Note: none`.
+Release notes are rendered by [Tools/release/release-notes.py](Tools/release/release-notes.py). The notes include a raw commit audit list, and they promote user-facing `Release-Note:` or `Release-Highlight:` commit trailers into a `Highlights` section before that list. Use single-line trailers that describe the Docker Compose feature, CLI option, or workflow users now get; internal release, CI, and documentation chores should normally omit the trailer or use `Release-Note: none`. For upstream-driven work, also record the original `owner/repository#number` under `Upstream-Ref:`, `Bug-Ref:`, `Refs:`, or `Follow-up-To:`. The renderer preserves references already written into the highlight and appends any missing references, including highlights collected from stack component commits.
 
 `VERSION_SELECTOR` accepts:
 

Tools/release/release-notes.py

@@ -32,13 +32,21 @@
 EXPLICIT_RELEASE_LINE_PATTERN = re.compile(
     r"^Release-(?:Note|Highlight):[ \t]*(?P<value>.*)$"
 )
+REFERENCE_TRAILER_PATTERN = re.compile(
+    r"^(?:Upstream-Ref|Bug-Ref|Refs|Follow-up-To):[ \t]*(?P<value>.*)$",
+    re.IGNORECASE,
+)
+GITHUB_REFERENCE_PATTERN = re.compile(
+    r"(?<![A-Za-z0-9_.-])(?P<reference>[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+#[0-9]+)\b"
+)
 
 
 @dataclass(frozen=True)
 class CommitSummary:
     short_hash: str
     subject: str
     highlights: tuple[str, ...]
+    upstream_references: tuple[str, ...]
 
 
 @dataclass(frozen=True)
@@ -177,6 +185,7 @@ def commits_for_revision(repo: Path, revision: str) -> list[CommitSummary]:
                 short_hash=short_hash,
                 subject=subject,
                 highlights=tuple(explicit_release_highlights_from_body(body)),
+                upstream_references=tuple(upstream_references_from_body(body)),
             )
         )
     return commits
@@ -213,6 +222,23 @@ def explicit_release_highlights_from_body(body: str) -> list[str]:
     return explicit_release_highlights(*values)
 
 
+def upstream_references_from_body(body: str) -> list[str]:
+    references: list[str] = []
+    seen: set[str] = set()
+    for line in body.splitlines():
+        trailer = REFERENCE_TRAILER_PATTERN.match(line.strip())
+        if trailer is None:
+            continue
+        for match in GITHUB_REFERENCE_PATTERN.finditer(trailer.group("value")):
+            reference = match.group("reference")
+            key = reference.lower()
+            if key in seen:
+                continue
+            seen.add(key)
+            references.append(reference)
+    return references
+
+
 CONVENTIONAL_SUBJECT_PATTERN = re.compile(
     r"^(?P<type>[a-z]+)(?:[(](?P<scope>[^)]+)[)])?(?P<breaking>!)?: (?P<summary>.+)$"
 )
@@ -221,6 +247,7 @@ def explicit_release_highlights_from_body(body: str) -> list[str]:
     "ci",
     "deps",
     "docs",
+    "integration",
     "quality",
     "release",
     "status",
@@ -256,6 +283,25 @@ def release_highlights(commits: list[CommitSummary]) -> list[str]:
             if fallback is not None:
                 commit_highlights = [fallback]
 
+        missing_references = [
+            reference
+            for reference in commit.upstream_references
+            if not any(
+                reference.lower() in highlight.lower()
+                for highlight in commit_highlights
+            )
+        ]
+        if commit_highlights and missing_references:
+            label = (
+                "Upstream reference"
+                if len(missing_references) == 1
+                else "Upstream references"
+            )
+            commit_highlights[-1] = (
+                f"{ensure_sentence(commit_highlights[-1])} {label}: "
+                f"{', '.join(missing_references)}."
+            )
+
         for highlight in commit_highlights:
             if highlight in seen:
                 continue

Tools/release/test_release_notes.py

@@ -80,6 +80,7 @@ def test_main_validation_tag_rerun_keeps_full_stable_range(self) -> None:
             self.git(repo, "tag", "--no-sign", "0.6.0")
             self.commit(repo, "ci(release): simplify package publishing")
             self.commit(repo, "fix(release): commit new tap formula files")
+            self.commit(repo, "fix(integration): preserve serial rootfs")
             self.git(repo, "tag", "--no-sign", "homebrew-main-123-abcdef123456")
 
             notes = module.render_release_notes(
@@ -95,6 +96,7 @@ def test_main_validation_tag_rerun_keeps_full_stable_range(self) -> None:
             self.assertIn("Commits since `0.6.0`", notes)
             self.assertIn("ci(release): simplify package publishing", notes)
             self.assertIn("fix(release): commit new tap formula files", notes)
+            self.assertIn("fix(integration): preserve serial rootfs", notes)
             self.assertNotIn("## Highlights", notes)
             self.assertNotIn("chore: initial import", notes)
 
@@ -266,7 +268,11 @@ def test_stack_component_changes_render_highlights(self) -> None:
                 Clean up attached exec sessions when the client disappears
                 while preserving detached exec process lifetime.
 
-                Release-Highlight: Improves container compose exec reliability by killing attached exec processes when the client disconnects, preventing orphaned sessions from blocking later exec or stop operations while preserving detached exec; ports the useful cleanup from apple/container#1926 for apple/container#1916.
+                Upstream-Ref: apple/container#1926
+
+                Bug-Ref: apple/container#1916
+
+                Release-Highlight: Improves container compose exec reliability by killing attached exec processes when the client disconnects, preventing orphaned sessions from blocking later exec or stop operations while preserving detached exec.
                 """,
             )
             current_component_ref = self.git(component, "rev-parse", "HEAD")
@@ -315,8 +321,8 @@ def test_stack_component_changes_render_highlights(self) -> None:
                 "- Improves container compose exec reliability by killing attached "
                 "exec processes when the client disconnects, preventing orphaned "
                 "sessions from blocking later exec or stop operations while "
-                "preserving detached exec; ports the useful cleanup from "
-                "apple/container#1926 for apple/container#1916.",
+                "preserving detached exec. Upstream references: "
+                "apple/container#1926, apple/container#1916.",
                 notes,
             )
             self.assertIn("## Component Changes", notes)