Skip to content

armgit / Pulse

Public Imported from GitHub
0

Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.

Point release pages at GitHub's comparison with a Source comparison section

rcourtman0bd6e8b9d88f
diff --git a/docs/release-control/v6/internal/subsystems/deployment-installability.md b/docs/release-control/v6/internal/subsystems/deployment-installability.md
index 1f61cabe18..44a268ddfc 100644
--- a/docs/release-control/v6/internal/subsystems/deployment-installability.md
+++ b/docs/release-control/v6/internal/subsystems/deployment-installability.md
@@ -5148,6 +5148,32 @@ is about 250 CPU-seconds, so under the pin it fails at 180 seconds with
`signal: killed` (reproduced; the first beta's release failed on it twice),
while a warmed cache makes the same pinned run a 16-second test. The race
build of the test binary does not warm that plain build.
+
+The release renderer appends a `## Source comparison` section after Roll back: a link to
+GitHub's comparison of the release tag with the stable rollback target it was given
+(`/compare/<rollback target>...<tag>`, from the candidate tag and rollback target the
+workflow already passes; the base is whatever lower stable target was supplied, not
+necessarily the immediately previous release). The link names bare refs, so a branch that shares
+a tag's name would win on GitHub; no such branch exists today. A `tags/` prefix, which
+GitHub's documentation describes for choosing the tag, returned HTTP 404 on the web
+comparison URL for tags that exist (checked on 2026-10-13 against v6.5.0 and
+v6.6.0-beta.2, with a nonexistent tag as a control), so the bare form is used. It is a pointer and not a
+complete list, because GitHub shows at most 250 commits in a comparison, so a larger release
+is only partly visible through it and the section says so. It is advisory. The comparison
+helper skips a missing or malformed tag or base, including a trailing newline, non-ASCII
+digits or numbers too large to convert, and raises nothing. The renderer's existing argument
+and body checks still apply to the whole render, so a rollback target that smuggles in a
+heading still fails the existing duplicate-Install check. A body that validated
+before still validates without the section, and an expected-body comparison still rejects a
+changed or deleted section when its expected body contains one. This does not establish that
+every historical published body meets today's other requirements. The post-update changelog
+dialog reads only recognised category headings, so a separate heading placed after Roll back
+is ignored by it; a `<details>` block placed inside a recognised category would be retained,
+and the sanitizer drops its collapse behaviour. Making the section required, and adding a
+generated row-level inventory that does prove completeness, needs a declarative contract
+record in the preparation snapshot: a marker in the body alone could be deleted to restore
+legacy acceptance, and a frozen in-flight release keeps its own renderer.
+
As of 2026-10-11, the governed release floor is Go `1.26.9`. It supersedes
`1.26.8`, whose standard library is reachable through twelve vulnerable Pulse
call paths reported by `govulncheck` after the 2026-10-08 advisories, including
diff --git a/scripts/release_control/render_release_body.py b/scripts/release_control/render_release_body.py
index 074aeb1597..f10c801f26 100644
--- a/scripts/release_control/render_release_body.py
+++ b/scripts/release_control/render_release_body.py
@@ -589,6 +589,41 @@ def build_rollback_section(args: argparse.Namespace) -> str:
)
+# ASCII digits only, bounded, and matched against the whole string: `$` would accept a final newline
+# (which would land inside the URL), `\d` accepts non-ASCII digits, and an unbounded number would make
+# the comparison below raise on conversion.
+_COMPARISON_HEAD = re.compile(r"v([0-9]{1,6})\.([0-9]{1,6})\.([0-9]{1,6})(?:-(?:alpha|beta|rc)\.[1-9][0-9]{0,5})?")
+_COMPARISON_BASE = re.compile(r"v([0-9]{1,6})\.([0-9]{1,6})\.([0-9]{1,6})")
+
+
+def build_source_comparison(args: argparse.Namespace) -> str | None:
+ """A pointer to GitHub's own comparison of this release with the stable rollback target it was given.
+
+ This is a pointer, not a complete list: GitHub shows at most 250 commits in a comparison, so a
+ release with more changes than that is only partly visible through it. It is also advisory. It
+ exists so a reader can look up a change the summary does not name, and it renders nothing, and
+ raises nothing, for a missing or malformed tag or for a base that is not a lower stable release.
+ """
+ head = _COMPARISON_HEAD.fullmatch(args.candidate_tag or "")
+ base = _COMPARISON_BASE.fullmatch(args.rollback_target or "")
+ if not head or not base:
+ return None
+ if tuple(map(int, base.groups())) >= tuple(map(int, head.groups())):
+ return None
+ return "\n".join(
+ [
+ "## Source comparison",
+ "",
+ f"[Browse source changes from `{args.rollback_target}` to `{args.candidate_tag}`]"
+ f"(https://github.com/rcourtman/Pulse/compare/{args.rollback_target}...{args.candidate_tag}) "
+ "on GitHub for more detail behind this summary.",
+ "",
+ "This comparison includes internal maintenance. GitHub shows at most 250 commits, "
+ "so larger comparisons may omit commits.",
+ ]
+ )
+
+
def parse_args() -> argparse.Namespace:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--version", required=True)
@@ -688,6 +723,9 @@ def main() -> int:
build_rollback_section(args),
]
)
+ comparison = build_source_comparison(args)
+ if comparison:
+ sections.append(comparison)
rendered = "\n\n".join(sections) + "\n"
validate_release_body_shape(rendered, args.version)
Path(args.output).write_text(rendered, encoding="utf-8")
diff --git a/scripts/release_control/render_release_body_test.py b/scripts/release_control/render_release_body_test.py
index 0b1b93d0a0..1012c8a43a 100644
--- a/scripts/release_control/render_release_body_test.py
+++ b/scripts/release_control/render_release_body_test.py
@@ -1024,5 +1024,146 @@ class AssetValidationWordingTest(unittest.TestCase):
self.assertIn("<!-- VALIDATION_STATUS_END -->", banner)
+class SourceComparisonTests(unittest.TestCase):
+ """The advisory tag-bound pointer to GitHub's comparison, and its place in the rendered body."""
+
+ NOTES = _REPO_ROOT / "docs" / "releases" / "RELEASE_NOTES_v6.5.0.md"
+
+ @staticmethod
+ def args(tag: str | None, base: str | None) -> "argparse.Namespace":
+ import argparse
+
+ return argparse.Namespace(candidate_tag=tag, rollback_target=base)
+
+ def render(self, version: str, tag: str, base: str, notes: Path | None = None) -> subprocess.CompletedProcess:
+ with tempfile.TemporaryDirectory() as directory:
+ output = Path(directory) / "body.md"
+ result = subprocess.run(
+ ["python3", str(_REPO_ROOT / "scripts/release_control/render_release_body.py"),
+ "--version", version, "--release-notes-file", str(notes or self.NOTES),
+ "--output", str(output), "--promotion-channel", "stable-rc-promotion",
+ "--candidate-tag", tag, "--promoted-prerelease-tag", "", "--rollback-target", base,
+ "--rollback-command", f"sudo /bin/update --version {base}",
+ "--planned-ga-date", "", "--planned-v5-eos-date", "", "--hotfix-exception", "false",
+ "--hotfix-reason", "", "--require-windows-signing", "false",
+ "--unsigned-windows-exception", "false", "--unsigned-windows-reason", ""],
+ capture_output=True, text=True, cwd=_REPO_ROOT)
+ result.body = output.read_text(encoding="utf-8") if output.exists() else ""
+ return result
+
+ def test_section_binds_the_exact_tag_and_stable_base(self) -> None:
+ section = render_release_body.build_source_comparison(self.args("v6.6.0-beta.3", "v6.5.0"))
+ self.assertIsNotNone(section)
+ self.assertTrue(section.startswith("## Source comparison\n"))
+ self.assertIn("https://github.com/rcourtman/Pulse/compare/v6.5.0...v6.6.0-beta.3)", section)
+ # GitHub caps a comparison at 250 commits, so this must not claim to be a full list.
+ self.assertIn("at most 250 commits", section)
+ self.assertIn("may omit commits", section)
+ self.assertNotIn("Full list", section)
+ # Stable promotion compares the same stable base with the final tag.
+ self.assertIn("compare/v6.5.0...v6.6.0)", render_release_body.build_source_comparison(self.args("v6.6.0", "v6.5.0")))
+
+ def test_missing_or_unusable_context_renders_nothing_and_never_raises(self) -> None:
+ huge = "v" + "1" * 5000 + ".0.0"
+ for tag, base in [(None, "v6.5.0"), ("v6.6.0-beta.3", None), ("", ""), ("6.6.0", "v6.5.0"),
+ ("v6.6.0-beta.3", "6.5.0"), ("v6.6.0-beta.3", "v6.5.0-rc.1"),
+ ("v6.6.0-beta.3", "v6.6.0"), ("v6.5.0", "v6.5.0"), ("v6.5.0", "v6.6.0"),
+ ("v6.6.0-beta.0", "v6.5.0"), ("v6.6.0-beta.3\n#", "v6.5.0"),
+ # a final newline would put a line break inside the URL
+ ("v6.5.0\n", "v6.4.5"), ("v6.5.0", "v6.4.5\n"), ("v6.6.0-beta.3\n", "v6.5.0"),
+ # non-ASCII digits, and numbers too large to convert, must not raise
+ ("v\uff16.\uff15.\uff10", "v6.4.5"), ("v6.5.0", "v\uff16.\uff14.\uff15"),
+ (huge, "v6.4.5"), ("v6.5.0", huge), ("v6.5.0", "v6.4." + "9" * 7),
+ ("v6.6.0-beta." + "9" * 7, "v6.5.0")]:
+ with self.subTest(tag=tag, base=base):
+ self.assertIsNone(render_release_body.build_source_comparison(self.args(tag, base)))
+
+ def test_rendered_body_ends_with_the_comparison_after_roll_back_and_validates(self) -> None:
+ result = self.render("6.5.0", "v6.5.0", "v6.4.5")
+ self.assertEqual(0, result.returncode, result.stderr)
+ headings = re.findall(r"(?m)^## (.+)$", result.body)
+ self.assertEqual(["Install", "Roll back", "Source comparison"], headings[-3:])
+ self.assertEqual(1, result.body.count("## Source comparison"))
+ self.assertIn("compare/v6.4.5...v6.5.0)", result.body)
+ # The stored body round-trips through the validator the edit and recovery workflows use.
+ render_release_body.validate_release_body_shape(result.body, "6.5.0")
+ clean = render_release_body.validate_release_body_shape(result.body, "6.5.0", expected_body=result.body)
+ self.assertIn("## Source comparison", clean)
+
+ def test_the_base_is_the_supplied_stable_rollback_target_and_orders_numerically(self) -> None:
+ build = render_release_body.build_source_comparison
+ # Numeric, not lexical: patch 10 follows patch 9. Alpha and release candidate heads work like betas.
+ self.assertIn("compare/v6.4.9...v6.4.10)", build(self.args("v6.4.10", "v6.4.9")))
+ self.assertIsNone(build(self.args("v6.4.9", "v6.4.10")))
+ self.assertIn("compare/v6.5.0...v6.6.0-rc.2)", build(self.args("v6.6.0-rc.2", "v6.5.0")))
+ self.assertIn("compare/v6.5.0...v6.6.0-alpha.1)", build(self.args("v6.6.0-alpha.1", "v6.5.0")))
+ # A hotfix and an older, non-immediate rollback target are used exactly as supplied.
+ self.assertIn("compare/v6.4.1...v6.5.1)", build(self.args("v6.5.1", "v6.4.1")))
+
+ def test_section_text_is_separated_by_one_blank_line_and_ends_with_one_newline(self) -> None:
+ result = self.render("6.5.0", "v6.5.0", "v6.4.5")
+ self.assertTrue(result.body.endswith("larger comparisons may omit commits.\n"), result.body[-120:])
+ self.assertFalse(result.body.endswith("\n\n"))
+ self.assertIn("\n\n## Source comparison\n\n[Browse source changes", result.body)
+ # Exactly one blank line before the section, as between every other section.
+ self.assertNotIn("\n\n\n## Source comparison", result.body)
+ before = result.body.split("\n\n## Source comparison")[0]
+ self.assertTrue(before.rstrip("\n").endswith("recreate the container."), before[-80:])
+ self.assertFalse(before.endswith("\n"))
+ self.assertIn(") on GitHub for more detail behind this summary.", result.body)
+
+ def test_edit_and_annotation_cycles_preserve_the_section_exactly(self) -> None:
+ # validate-release-assets.yml re-reads the stored body, strips its status block, prepends a
+ # fresh one and checks equality with the cleaned body. Repeat that, with the extra newline
+ # `jq -r` adds and with CRLF line endings, and the section must survive unchanged.
+ result = self.render("6.5.0", "v6.5.0", "v6.4.5")
+ block = ("<!-- VALIDATION_STATUS_START -->\n## Release Asset Validation: PASSED\n\n"
+ "**Validated**: 2026-10-13 00:00:00 UTC\n\n<!-- VALIDATION_STATUS_END -->\n\n")
+ clean = render_release_body.validate_release_body_shape(result.body, "6.5.0")
+ for cycle in range(10):
+ stored = block + clean + ("\n" if cycle % 2 else "")
+ clean = render_release_body.validate_release_body_shape(stored, "6.5.0", expected_body=None)
+ crlf = render_release_body.validate_release_body_shape(stored.replace("\n", "\r\n"), "6.5.0")
+ self.assertEqual(clean.rstrip("\n"), crlf.rstrip("\n"))
+ self.assertEqual(result.body.rstrip("\n"), clean.rstrip("\n"))
+ self.assertEqual(1, clean.count("## Source comparison"))
+
+ def test_expected_body_equality_rejects_a_changed_or_deleted_section_but_not_its_absence(self) -> None:
+ result = self.render("6.5.0", "v6.5.0", "v6.4.5")
+ render_release_body.validate_release_body_shape(result.body, "6.5.0", expected_body=result.body)
+ changed = result.body.replace("compare/v6.4.5...v6.5.0", "compare/v6.4.4...v6.5.0")
+ deleted = result.body.split("\n\n## Source comparison")[0] + "\n"
+ for label, stored in (("changed link", changed), ("deleted section", deleted)):
+ with self.subTest(label=label):
+ with self.assertRaises(render_release_body.ReleaseBodyIntegrityError):
+ render_release_body.validate_release_body_shape(stored, "6.5.0", expected_body=result.body)
+ # Shape-only validation, and equality against an expected body that also lacks it, still accept absence.
+ render_release_body.validate_release_body_shape(deleted, "6.5.0")
+ render_release_body.validate_release_body_shape(deleted, "6.5.0", expected_body=deleted)
+
+ def test_a_base_that_smuggles_a_heading_is_still_stopped_by_the_existing_checks(self) -> None:
+ # The helper itself skips this input and raises nothing, but the renderer's existing body
+ # checks still apply to the whole render, and the rollback command and target are rendered
+ # elsewhere in the body, so this fails there. The contract says exactly that.
+ smuggled = "v6.4.5\n## Install\n"
+ self.assertIsNone(render_release_body.build_source_comparison(self.args("v6.5.0", smuggled)))
+ result = self.render("6.5.0", "v6.5.0", smuggled)
+ self.assertNotEqual(0, result.returncode)
+ self.assertNotIn("## Source comparison", result.body)
+
+ def test_a_malformed_base_does_not_fail_the_render(self) -> None:
+ result = self.render("6.5.0", "v6.5.0", "v6.5.0-rc.1")
+ self.assertEqual(0, result.returncode, result.stderr)
+ self.assertNotIn("## Source comparison", result.body)
+
+ def test_bodies_without_the_section_still_validate(self) -> None:
+ # Everything published before this section existed, and any frozen in-flight release,
+ # has no such section. It is advisory: the absence must keep validating.
+ result = self.render("6.5.0", "v6.5.0", "v6.4.5")
+ legacy = result.body.split("\n\n## Source comparison")[0] + "\n"
+ self.assertNotIn("Source comparison", legacy)
+ render_release_body.validate_release_body_shape(legacy, "6.5.0")
+
+
if __name__ == "__main__":
unittest.main()