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.
Go aialertsdashboarddockerdocker-monitoringgohomelabinfrastructure-monitoringkubernetesmonitoringmspproxmoxproxmox-backup-serverproxmox-mail-gatewayproxmox-veself-hostedtruenastypescriptvspherewebhooks
#!/usr/bin/env python3
"""Unit tests for shared release-promotion metadata resolution."""
from __future__ import annotations
from pathlib import Path
import unittest
from unittest.mock import patch
import json
import subprocess
import tempfile
import resolve_release_promotion as resolver
REPO_ROOT = Path(__file__).resolve().parents[2]
class ResolveReleasePromotionTest(unittest.TestCase):
def test_candidate_clock_uses_exact_release_publication(self) -> None:
payload = dict(tagName="v6.5.0-rc.2", isDraft=False,
isPrerelease=True, publishedAt="2026-09-05T00:00:00Z")
with patch.object(resolver.subprocess, "run") as run:
run.return_value.stdout = json.dumps(payload)
self.assertEqual(resolver.release_published_unix("v6.5.0-rc.2"),
1788566400)
self.assertEqual(run.call_args.args[0][:4],
["gh", "release", "view", "v6.5.0-rc.2"])
self.assertEqual(run.call_count, 1)
def test_candidate_clock_fails_closed_without_publication(self) -> None:
payload = dict(tagName="v6.5.0-rc.2", isDraft=False,
isPrerelease=True, publishedAt="2026-09-05T00:00:00Z")
for change in (dict(isDraft=True), dict(isPrerelease=False),
dict(publishedAt=None), dict(tagName="v6.5.0-rc.1"),
dict(publishedAt="2026-09-05T00:00:00")):
with self.subTest(change=change), patch.object(resolver.subprocess, "run") as run:
run.return_value.stdout = json.dumps(payload | change)
with self.assertRaises(ValueError):
resolver.release_published_unix("v6.5.0-rc.2")
with patch.object(resolver.subprocess, "run", side_effect=subprocess.CalledProcessError(1, "gh")):
with self.assertRaises(subprocess.CalledProcessError):
resolver.release_published_unix("v6.5.0-rc.2")
def test_published_release_versions_use_explicit_maturity_stages(self) -> None:
for version, expected in (
("6.5.0-alpha.1", "alpha"),
("6.5.0-beta.2", "beta"),
("6.5.0-rc.3", "rc"),
("6.5.0", "stable"),
):
with self.subTest(version=version):
self.assertEqual(resolver.release_stage(version), expected)
for unsupported in ("6.5.0-dev", "6.5.0-preview.1", "6.5.0-beta.0"):
with self.subTest(unsupported=unsupported):
with self.assertRaisesRegex(ValueError, "Unsupported release version"):
resolver.release_stage(unsupported)
def test_prerelease_requires_explicit_stable_rollback(self) -> None:
metadata = resolver.resolve_metadata(
version="6.0.0-rc.2",
promoted_from_tag_input="",
rollback_version_input="5.1.14",
ga_date_input="",
v5_eos_date_input="",
hotfix_exception=False,
hotfix_reason_input="",
release_notes_input="",
tag_exists_fn=lambda tag: tag == "v5.1.14",
)
self.assertEqual(metadata["rollback_tag"], "v5.1.14")
self.assertEqual(metadata["rollback_command"], "sudo /bin/update --version v5.1.14")
self.assertEqual(metadata["promoted_from_tag"], "")
self.assertEqual(metadata["soak_hours"], "")
self.assertEqual(metadata["release_stage"], "rc")
def test_beta_uses_the_published_prerelease_path(self) -> None:
metadata = resolver.resolve_metadata(
version="6.5.0-beta.1",
promoted_from_tag_input="",
rollback_version_input="6.4.1",
ga_date_input="",
v5_eos_date_input="",
hotfix_exception=False,
hotfix_reason_input="",
release_notes_input="",
tag_exists_fn=lambda tag: tag == "v6.4.1",
)
self.assertEqual(metadata["release_stage"], "beta")
self.assertEqual(metadata["promotion_mode"], "prerelease")
self.assertEqual(metadata["promoted_from_tag"], "")
def test_first_rc_has_no_observation_window_to_wait_for(self) -> None:
metadata = resolver.resolve_metadata(
version="6.4.0-rc.1",
promoted_from_tag_input="",
rollback_version_input="6.3.2",
ga_date_input="",
v5_eos_date_input="",
hotfix_exception=False,
hotfix_reason_input="",
release_notes_input="",
enforce_prerelease_observation_window=True,
list_published_prereleases_fn=lambda: [
("v6.3.0-rc.8", 100),
("v6.5.0-rc.1", 200),
],
tag_exists_fn=lambda tag: tag == "v6.3.2",
now_unix_fn=lambda: 10_000,
)
self.assertEqual(metadata["previous_prerelease_tag"], "")
self.assertEqual(metadata["prerelease_observation_hours"], "")
def test_same_version_rc_is_rejected_inside_observation_window(self) -> None:
with self.assertRaisesRegex(
ValueError,
"after only 23 hours of public observation.*require 24 hours",
):
resolver.resolve_metadata(
version="6.4.0-rc.13",
promoted_from_tag_input="",
rollback_version_input="6.3.2",
ga_date_input="",
v5_eos_date_input="",
hotfix_exception=False,
hotfix_reason_input="",
release_notes_input="",
enforce_prerelease_observation_window=True,
list_published_prereleases_fn=lambda: [
("v6.4.0-rc.11", 100),
("v6.4.0-rc.12", 200),
],
tag_exists_fn=lambda tag: tag == "v6.3.2",
now_unix_fn=lambda: 200 + (23 * 3600) + 3599,
)
def test_same_version_rc_is_allowed_after_observation_window(self) -> None:
metadata = resolver.resolve_metadata(
version="6.4.0-rc.13",
promoted_from_tag_input="",
rollback_version_input="6.3.2",
ga_date_input="",
v5_eos_date_input="",
hotfix_exception=False,
hotfix_reason_input="",
release_notes_input="",
enforce_prerelease_observation_window=True,
list_published_prereleases_fn=lambda: [
("v6.3.0-rc.8", 300),
("v6.4.0-rc.12", 200),
],
tag_exists_fn=lambda tag: tag == "v6.3.2",
now_unix_fn=lambda: 200 + (24 * 3600),
)
self.assertEqual(metadata["previous_prerelease_tag"], "v6.4.0-rc.12")
self.assertEqual(metadata["prerelease_observation_hours"], "24")
def test_observation_window_is_scoped_to_the_same_maturity_stage(self) -> None:
metadata = resolver.resolve_metadata(
version="6.5.0-rc.1",
promoted_from_tag_input="",
rollback_version_input="6.4.1",
ga_date_input="",
v5_eos_date_input="",
hotfix_exception=False,
hotfix_reason_input="",
release_notes_input="",
enforce_prerelease_observation_window=True,
list_published_prereleases_fn=lambda: [
("v6.5.0-alpha.2", 100),
("v6.5.0-beta.4", 200),
],
tag_exists_fn=lambda tag: tag == "v6.4.1",
now_unix_fn=lambda: 201,
)
self.assertEqual(metadata["release_stage"], "rc")
self.assertEqual(metadata["previous_prerelease_tag"], "")
def test_rehearsal_does_not_query_or_enforce_publication_window(self) -> None:
metadata = resolver.resolve_metadata(
version="6.4.0-rc.13",
promoted_from_tag_input="",
rollback_version_input="6.3.2",
ga_date_input="",
v5_eos_date_input="",
hotfix_exception=False,
hotfix_reason_input="",
release_notes_input="",
enforce_prerelease_observation_window=False,
list_published_prereleases_fn=lambda: self.fail("publication lookup should not run"),
tag_exists_fn=lambda tag: tag == "v6.3.2",
)
self.assertEqual(metadata["previous_prerelease_tag"], "")
def test_missing_rollback_is_rejected_without_derivation(self) -> None:
with self.assertRaisesRegex(
ValueError,
"rollback_version is required for every release rehearsal and promotion",
):
resolver.resolve_metadata(
version="6.0.5-rc.3",
promoted_from_tag_input="",
rollback_version_input="",
ga_date_input="",
v5_eos_date_input="",
hotfix_exception=False,
hotfix_reason_input="",
release_notes_input="",
tag_exists_fn=lambda tag: True,
)
def test_scheduled_rehearsal_derives_latest_preceding_stable_rollback(self) -> None:
metadata = resolver.resolve_metadata(
version="6.0.5-rc.3",
promoted_from_tag_input="",
rollback_version_input="",
ga_date_input="",
v5_eos_date_input="",
hotfix_exception=False,
hotfix_reason_input="",
release_notes_input="",
derive_rollback_when_missing=True,
list_stable_tags_fn=lambda: ["v5.1.35", "v6.0.1", "v6.0.4", "v6.0.2"],
tag_exists_fn=lambda tag: True,
)
self.assertEqual(metadata["rollback_tag"], "v6.0.4")
self.assertEqual(metadata["rollback_command"], "sudo /bin/update --version v6.0.4")
def test_explicit_rollback_input_wins_over_derivation(self) -> None:
metadata = resolver.resolve_metadata(
version="6.0.5-rc.3",
promoted_from_tag_input="",
rollback_version_input="6.0.3",
ga_date_input="",
v5_eos_date_input="",
hotfix_exception=False,
hotfix_reason_input="",
release_notes_input="",
derive_rollback_when_missing=True,
list_stable_tags_fn=lambda: ["v6.0.4"],
tag_exists_fn=lambda tag: tag == "v6.0.3",
)
self.assertEqual(metadata["rollback_tag"], "v6.0.3")
def test_derivation_never_selects_the_rehearsal_version_or_prereleases(self) -> None:
self.assertEqual(
resolver.derive_latest_stable_rollback_tag(
"6.0.5",
["v6.0.5", "v6.0.5-rc.3", "v6.0.4", "v5.1.35"],
),
"v6.0.4",
)
def test_derivation_requires_a_preceding_stable_tag(self) -> None:
with self.assertRaisesRegex(ValueError, "no stable release tag precedes"):
resolver.resolve_metadata(
version="6.0.5-rc.3",
promoted_from_tag_input="",
rollback_version_input="",
ga_date_input="",
v5_eos_date_input="",
hotfix_exception=False,
hotfix_reason_input="",
release_notes_input="",
derive_rollback_when_missing=True,
list_stable_tags_fn=lambda: [],
tag_exists_fn=lambda tag: True,
)
def test_stable_requires_matching_promoted_rc_and_soak(self) -> None:
metadata = resolver.resolve_metadata(
changed_paths_fn=lambda tag: ["VERSION"],
version="6.0.0",
promoted_from_tag_input="6.0.0-rc.2",
rollback_version_input="5.1.14",
ga_date_input="2026-03-20",
v5_eos_date_input="2026-06-18",
hotfix_exception=False,
hotfix_reason_input="",
release_notes_input="maintenance-only support 2026-03-20 2026-06-18",
tag_exists_fn=lambda tag: tag in {"v6.0.0-rc.2", "v5.1.14"},
tag_commit_fn=lambda tag: "abc123",
head_descends_from_fn=lambda commit: commit == "abc123",
release_published_unix_fn=lambda tag: 100,
now_unix_fn=lambda: 100 + (73 * 3600),
)
self.assertEqual(metadata["promoted_from_tag"], "v6.0.0-rc.2")
self.assertEqual(metadata["soak_hours"], "73")
self.assertEqual(metadata["require_windows_signing"], "true")
self.assertEqual(metadata["unsigned_windows_exception"], "false")
def test_v610_owner_exception_allows_disclosed_unsigned_windows_candidate(self) -> None:
metadata = resolver.resolve_metadata(
changed_paths_fn=lambda tag: ["VERSION"],
version="6.1.0",
promoted_from_tag_input="v6.1.0-rc.4",
rollback_version_input="v6.0.5",
ga_date_input="",
v5_eos_date_input="",
hotfix_exception=True,
hotfix_reason_input="Owner waived the remaining prerelease soak.",
release_notes_input=(
"Windows Unified Agent binaries are not Authenticode-signed for v6.1.0."
),
unsigned_windows_exception=True,
unsigned_windows_reason_input=(
"Release owner accepted the Windows unknown-publisher warning for v6.1.0."
),
tag_exists_fn=lambda tag: tag in {"v6.1.0-rc.4", "v6.0.5"},
tag_commit_fn=lambda tag: "rc4-commit",
head_descends_from_fn=lambda commit: commit == "rc4-commit",
release_published_unix_fn=lambda tag: 100,
now_unix_fn=lambda: 100 + (27 * 3600),
)
self.assertEqual(metadata["require_windows_signing"], "false")
self.assertEqual(metadata["unsigned_windows_exception"], "true")
self.assertEqual(
metadata["unsigned_windows_reason"],
"Release owner accepted the Windows unknown-publisher warning for v6.1.0.",
)
def test_v611_owner_exception_allows_disclosed_emergency_patch(self) -> None:
metadata = resolver.resolve_metadata(
version="6.1.1",
promoted_from_tag_input="",
rollback_version_input="v6.1.0",
ga_date_input="",
v5_eos_date_input="",
hotfix_exception=True,
hotfix_reason_input="Active customer update harm.",
release_notes_input=(
"Windows Unified Agent binaries are not Authenticode-signed for v6.1.1."
),
unsigned_windows_exception=True,
unsigned_windows_reason_input=(
"Release owner accepted the Windows unknown-publisher warning for v6.1.1."
),
list_stable_tags_fn=lambda: ["v6.1.0", "v6.0.5"],
list_same_version_rc_tags_fn=lambda version: [],
changed_paths_fn=lambda tag: ["install.sh"],
tag_exists_fn=lambda tag: tag == "v6.1.0",
tag_commit_fn=lambda tag: "v610-commit",
head_descends_from_fn=lambda commit: commit == "v610-commit",
)
self.assertEqual(metadata["promotion_mode"], "emergency-stable-patch")
self.assertEqual(metadata["rollback_tag"], "v6.1.0")
self.assertEqual(metadata["require_windows_signing"], "false")
self.assertEqual(metadata["unsigned_windows_exception"], "true")
def test_v612_owner_exception_allows_disclosed_emergency_patch(self) -> None:
metadata = resolver.resolve_metadata(
version="6.1.2",
promoted_from_tag_input="",
rollback_version_input="v6.1.1",
ga_date_input="",
v5_eos_date_input="",
hotfix_exception=True,
hotfix_reason_input="Active customer-impact fixes.",
release_notes_input=(
"Windows Unified Agent binaries are not Authenticode-signed for v6.1.2."
),
unsigned_windows_exception=True,
unsigned_windows_reason_input=(
"SignPath company verification is still processing; the release owner accepts "
"unsigned Windows binaries for v6.1.2."
),
list_stable_tags_fn=lambda: ["v6.1.1", "v6.1.0"],
list_same_version_rc_tags_fn=lambda version: [],
changed_paths_fn=lambda tag: ["scripts/install.sh"],
tag_exists_fn=lambda tag: tag == "v6.1.1",
tag_commit_fn=lambda tag: "v611-commit",
head_descends_from_fn=lambda commit: commit == "v611-commit",
)
self.assertEqual(metadata["promotion_mode"], "emergency-stable-patch")
self.assertEqual(metadata["rollback_tag"], "v6.1.1")
self.assertEqual(metadata["require_windows_signing"], "false")
self.assertEqual(metadata["unsigned_windows_exception"], "true")
def test_v620_owner_exception_allows_disclosed_stable_promotion(self) -> None:
metadata = resolver.resolve_metadata(
changed_paths_fn=lambda tag: ["VERSION"],
version="6.2.0",
promoted_from_tag_input="v6.2.0-rc.11",
rollback_version_input="v6.1.2",
ga_date_input="",
v5_eos_date_input="",
hotfix_exception=True,
hotfix_reason_input="Owner waived the remaining prerelease soak.",
release_notes_input=(
"Windows Unified Agent binaries are not Authenticode-signed for v6.2.0."
),
unsigned_windows_exception=True,
unsigned_windows_reason_input=(
"The release certificate CSR remains pending; the release owner accepts "
"unsigned Windows binaries for v6.2.0."
),
tag_exists_fn=lambda tag: tag in {"v6.2.0-rc.11", "v6.1.2"},
tag_commit_fn=lambda tag: "rc11-commit",
head_descends_from_fn=lambda commit: commit == "rc11-commit",
release_published_unix_fn=lambda tag: 100,
now_unix_fn=lambda: 100 + (13 * 3600),
)
self.assertEqual(metadata["promotion_mode"], "stable-rc-promotion")
self.assertEqual(metadata["rollback_tag"], "v6.1.2")
self.assertEqual(metadata["require_windows_signing"], "false")
self.assertEqual(metadata["unsigned_windows_exception"], "true")
def test_v621_owner_exception_allows_disclosed_emergency_patch(self) -> None:
metadata = resolver.resolve_metadata(
version="6.2.1",
promoted_from_tag_input="",
rollback_version_input="v6.2.0",
ga_date_input="",
v5_eos_date_input="",
hotfix_exception=True,
hotfix_reason_input="Active customer-impact fixes.",
release_notes_input=(
"Windows Unified Agent binaries are not Authenticode-signed for v6.2.1."
),
unsigned_windows_exception=True,
unsigned_windows_reason_input=(
"The release certificate CSR remains pending; the release owner accepts "
"unsigned Windows binaries for v6.2.1."
),
list_stable_tags_fn=lambda: ["v6.2.0", "v6.1.2"],
list_same_version_rc_tags_fn=lambda version: [],
changed_paths_fn=lambda tag: ["scripts/install.sh"],
tag_exists_fn=lambda tag: tag == "v6.2.0",
tag_commit_fn=lambda tag: "v620-commit",
head_descends_from_fn=lambda commit: commit == "v620-commit",
)
self.assertEqual(metadata["promotion_mode"], "emergency-stable-patch")
self.assertEqual(metadata["rollback_tag"], "v6.2.0")
self.assertEqual(metadata["require_windows_signing"], "false")
self.assertEqual(metadata["unsigned_windows_exception"], "true")
def test_v630_owner_exception_allows_disclosed_stable_promotion(self) -> None:
metadata = resolver.resolve_metadata(
changed_paths_fn=lambda tag: ["VERSION"],
version="6.3.0",
promoted_from_tag_input="v6.3.0-rc.6",
rollback_version_input="v6.2.1",
ga_date_input="",
v5_eos_date_input="",
hotfix_exception=True,
hotfix_reason_input="Owner accepted the shortened prerelease soak.",
release_notes_input=(
"Windows Unified Agent binaries are not Authenticode-signed for v6.3.0."
),
unsigned_windows_exception=True,
unsigned_windows_reason_input=(
"Windows signing is not yet available; the release owner accepts unsigned "
"Windows binaries for v6.3.0."
),
tag_exists_fn=lambda tag: tag in {"v6.3.0-rc.6", "v6.2.1"},
tag_commit_fn=lambda tag: "rc6-commit",
head_descends_from_fn=lambda commit: commit == "rc6-commit",
release_published_unix_fn=lambda tag: 100,
now_unix_fn=lambda: 100 + (24 * 3600),
)
self.assertEqual(metadata["promotion_mode"], "stable-rc-promotion")
self.assertEqual(metadata["rollback_tag"], "v6.2.1")
self.assertEqual(metadata["require_windows_signing"], "false")
self.assertEqual(metadata["unsigned_windows_exception"], "true")
def test_v631_owner_exception_allows_disclosed_emergency_patch(self) -> None:
metadata = resolver.resolve_metadata(
version="6.3.1",
promoted_from_tag_input="",
rollback_version_input="v6.3.0",
ga_date_input="",
v5_eos_date_input="",
hotfix_exception=True,
hotfix_reason_input="Active customer-impact fixes.",
release_notes_input=(
"Windows Unified Agent binaries are not Authenticode-signed for v6.3.1."
),
unsigned_windows_exception=True,
unsigned_windows_reason_input=(
"The SignPath production certificate remains CSR pending; the release owner "
"accepts unsigned Windows binaries for v6.3.1."
),
list_stable_tags_fn=lambda: ["v6.3.0", "v6.2.1"],
list_same_version_rc_tags_fn=lambda version: [],
changed_paths_fn=lambda tag: ["scripts/install.sh"],
tag_exists_fn=lambda tag: tag == "v6.3.0",
tag_commit_fn=lambda tag: "v630-commit",
head_descends_from_fn=lambda commit: commit == "v630-commit",
)
self.assertEqual(metadata["promotion_mode"], "emergency-stable-patch")
self.assertEqual(metadata["rollback_tag"], "v6.3.0")
self.assertEqual(metadata["require_windows_signing"], "false")
self.assertEqual(metadata["unsigned_windows_exception"], "true")
def test_v632_standing_unavailable_policy_allows_disclosed_emergency_patch(self) -> None:
metadata = resolver.resolve_metadata(
version="6.3.2",
promoted_from_tag_input="",
rollback_version_input="v6.3.1",
ga_date_input="",
v5_eos_date_input="",
hotfix_exception=True,
hotfix_reason_input=(
"Metrics memory growth can wedge stable and disabled offline policies emit alert noise."
),
release_notes_input=(
"Windows Unified Agent binaries are not Authenticode-signed for v6.3.2."
),
unsigned_windows_exception=False,
unsigned_windows_reason_input="",
list_stable_tags_fn=lambda: ["v6.3.1", "v6.3.0"],
list_same_version_rc_tags_fn=lambda version: [],
changed_paths_fn=lambda tag: ["internal/monitoring/metrics_history.go"],
tag_exists_fn=lambda tag: tag == "v6.3.1",
tag_commit_fn=lambda tag: "v631-commit",
head_descends_from_fn=lambda commit: commit == "v631-commit",
)
self.assertEqual(metadata["promotion_mode"], "emergency-stable-patch")
self.assertEqual(metadata["rollback_tag"], "v6.3.1")
self.assertEqual(metadata["require_windows_signing"], "false")
self.assertEqual(metadata["unsigned_windows_exception"], "true")
self.assertIn("until availability is explicitly restored", metadata["unsigned_windows_reason"])
def test_future_stable_release_stays_unsigned_until_authenticode_is_restored(self) -> None:
metadata = resolver.resolve_metadata(
changed_paths_fn=lambda tag: ["VERSION"],
version="6.4.0",
promoted_from_tag_input="v6.4.0-rc.1",
rollback_version_input="v6.3.2",
ga_date_input="",
v5_eos_date_input="",
hotfix_exception=True,
hotfix_reason_input="Release owner approved stable promotion.",
release_notes_input=(
"Windows Unified Agent binaries are not Authenticode-signed for v6.4.0."
),
list_stable_tags_fn=lambda: ["v6.3.2", "v6.3.1"],
tag_exists_fn=lambda tag: tag in {"v6.4.0-rc.1", "v6.3.2"},
tag_commit_fn=lambda tag: "rc-commit" if tag == "v6.4.0-rc.1" else "v632-commit",
head_descends_from_fn=lambda commit: True,
release_published_unix_fn=lambda tag: 100,
now_unix_fn=lambda: 100 + (73 * 3600),
)
self.assertEqual(metadata["require_windows_signing"], "false")
self.assertEqual(metadata["unsigned_windows_exception"], "true")
def test_unsigned_windows_exception_is_rejected_for_other_stable_versions(self) -> None:
with self.assertRaisesRegex(
ValueError,
"approved only for stable v6.1.0, v6.1.1, v6.1.2, v6.2.0, v6.2.1, v6.3.0, v6.3.1, or v6.3.2",
):
resolver.resolve_metadata(
changed_paths_fn=lambda tag: ["VERSION"],
version="6.4.0",
promoted_from_tag_input="",
rollback_version_input="v6.3.2",
ga_date_input="",
v5_eos_date_input="",
hotfix_exception=True,
hotfix_reason_input="Emergency patch.",
release_notes_input="Windows binaries are not Authenticode-signed.",
unsigned_windows_exception=True,
unsigned_windows_reason_input="Not approved for this version.",
windows_authenticode_available=True,
tag_exists_fn=lambda tag: True,
)
def test_unsigned_windows_exception_requires_reason_and_release_note_disclosure(self) -> None:
common = {
"version": "6.1.0",
"promoted_from_tag_input": "v6.1.0-rc.4",
"rollback_version_input": "v6.0.5",
"ga_date_input": "",
"v5_eos_date_input": "",
"hotfix_exception": True,
"hotfix_reason_input": "Owner waived the remaining prerelease soak.",
"unsigned_windows_exception": True,
"tag_exists_fn": lambda tag: True,
"tag_commit_fn": lambda tag: "rc4-commit",
"head_descends_from_fn": lambda commit: True,
"release_published_unix_fn": lambda tag: 100,
"now_unix_fn": lambda: 100 + (27 * 3600),
}
with self.assertRaisesRegex(ValueError, "unsigned_windows_reason is required"):
resolver.resolve_metadata(
**common,
release_notes_input="Windows binaries are not Authenticode-signed.",
unsigned_windows_reason_input="",
)
with self.assertRaisesRegex(ValueError, "must disclose"):
resolver.resolve_metadata(
**common,
release_notes_input="Windows agent details omitted.",
unsigned_windows_reason_input="Owner accepted the warning.",
)
def test_stable_requires_release_notes_notice_when_supplied(self) -> None:
with self.assertRaisesRegex(
ValueError,
"release_notes must include the Pulse v5 maintenance-only support notice",
):
resolver.resolve_metadata(
changed_paths_fn=lambda tag: ["VERSION"],
version="6.0.0",
promoted_from_tag_input="6.0.0-rc.2",
rollback_version_input="5.1.14",
ga_date_input="2026-03-20",
v5_eos_date_input="2026-06-18",
hotfix_exception=False,
hotfix_reason_input="",
release_notes_input="missing notice 2026-03-20 2026-06-18",
tag_exists_fn=lambda tag: True,
tag_commit_fn=lambda tag: "abc123",
head_descends_from_fn=lambda commit: True,
release_published_unix_fn=lambda tag: 100,
now_unix_fn=lambda: 100 + (73 * 3600),
)
def test_current_stable_v6_packet_resolves_with_publish_dates(self) -> None:
release_notes = (REPO_ROOT / "docs/releases/RELEASE_NOTES_v6.md").read_text(encoding="utf-8")
metadata = resolver.resolve_metadata(
changed_paths_fn=lambda tag: ["VERSION"],
version="6.0.0",
promoted_from_tag_input="v6.0.0-rc.7",
rollback_version_input="v5.1.35",
ga_date_input="2026-07-04",
v5_eos_date_input="2026-10-02",
hotfix_exception=False,
hotfix_reason_input="",
release_notes_input=release_notes,
tag_exists_fn=lambda tag: tag in {"v6.0.0-rc.7", "v5.1.35"},
tag_commit_fn=lambda tag: "rc7-commit",
head_descends_from_fn=lambda commit: commit == "rc7-commit",
release_published_unix_fn=lambda tag: 100,
now_unix_fn=lambda: 100 + (163 * 3600),
)
self.assertEqual(metadata["promoted_from_tag"], "v6.0.0-rc.7")
self.assertEqual(metadata["rollback_tag"], "v5.1.35")
self.assertEqual(metadata["rollback_command"], "sudo /bin/update --version v5.1.35")
self.assertEqual(metadata["ga_date"], "2026-07-04")
self.assertEqual(metadata["v5_eos_date"], "2026-10-02")
def test_stable_patch_hotfix_can_omit_promoted_prerelease(self) -> None:
metadata = resolver.resolve_metadata(
version="6.0.2",
promoted_from_tag_input="",
rollback_version_input="6.0.1",
ga_date_input="",
v5_eos_date_input="",
hotfix_exception=True,
hotfix_reason_input="Patch release for v6.0.1 agent upgrade recovery.",
release_notes_input="",
list_stable_tags_fn=lambda: ["v6.0.1"],
list_same_version_rc_tags_fn=lambda version: ["v6.0.2-rc.1"],
changed_paths_fn=lambda tag: ["internal/api/auth.go"],
tag_exists_fn=lambda tag: tag == "v6.0.1",
tag_commit_fn=lambda tag: "rollback-commit",
head_descends_from_fn=lambda commit: commit == "rollback-commit",
)
self.assertEqual(metadata["promoted_from_tag"], "")
self.assertEqual(metadata["rollback_tag"], "v6.0.1")
self.assertEqual(metadata["rollback_command"], "sudo /bin/update --version v6.0.1")
self.assertEqual(metadata["hotfix_exception"], "true")
self.assertEqual(
metadata["hotfix_reason"],
"Patch release for v6.0.1 agent upgrade recovery.",
)
self.assertEqual(metadata["soak_hours"], "")
self.assertEqual(metadata["promotion_mode"], "emergency-stable-patch")
def test_routine_stable_patch_can_omit_rc_ceremony(self) -> None:
metadata = resolver.resolve_metadata(
version="6.0.2",
promoted_from_tag_input="",
rollback_version_input="6.0.1",
ga_date_input="",
v5_eos_date_input="",
hotfix_exception=False,
hotfix_reason_input="",
release_notes_input="bounded customer fixes",
list_stable_tags_fn=lambda: ["v5.1.35", "v6.0.1"],
list_same_version_rc_tags_fn=lambda version: [],
changed_paths_fn=lambda tag: ["frontend-modern/src/features/settings/Settings.tsx"],
tag_exists_fn=lambda tag: tag == "v6.0.1",
tag_commit_fn=lambda tag: "rollback-commit",
head_descends_from_fn=lambda commit: commit == "rollback-commit",
)
self.assertEqual(metadata["promotion_mode"], "routine-stable-patch")
self.assertEqual(metadata["is_stable_patch"], "true")
self.assertEqual(metadata["rollback_tag"], "v6.0.1")
self.assertEqual(metadata["hotfix_exception"], "false")
def test_routine_stable_patch_requires_latest_stable_rollback(self) -> None:
with self.assertRaisesRegex(ValueError, "latest preceding stable tag v6.0.1"):
resolver.resolve_metadata(
version="6.0.2",
promoted_from_tag_input="",
rollback_version_input="6.0.0",
ga_date_input="",
v5_eos_date_input="",
hotfix_exception=False,
hotfix_reason_input="",
release_notes_input="bounded customer fixes",
list_stable_tags_fn=lambda: ["v6.0.0", "v6.0.1"],
list_same_version_rc_tags_fn=lambda version: [],
changed_paths_fn=lambda tag: [],
tag_exists_fn=lambda tag: True,
)
def test_routine_stable_patch_requires_rc_for_risk_changes(self) -> None:
with self.assertRaisesRegex(ValueError, "RC-required runtime changes"):
resolver.resolve_metadata(
version="6.0.2",
promoted_from_tag_input="",
rollback_version_input="6.0.1",
ga_date_input="",
v5_eos_date_input="",
hotfix_exception=False,
hotfix_reason_input="",
release_notes_input="authentication correction",
list_stable_tags_fn=lambda: ["v6.0.1"],
list_same_version_rc_tags_fn=lambda version: [],
changed_paths_fn=lambda tag: ["internal/api/auth.go"],
tag_exists_fn=lambda tag: True,
tag_commit_fn=lambda tag: "rollback-commit",
head_descends_from_fn=lambda commit: True,
)
def test_routine_stable_patch_requires_rc_when_candidate_exists(self) -> None:
with self.assertRaisesRegex(ValueError, "same-version release candidates already exist"):
resolver.resolve_metadata(
version="6.0.2",
promoted_from_tag_input="",
rollback_version_input="6.0.1",
ga_date_input="",
v5_eos_date_input="",
hotfix_exception=False,
hotfix_reason_input="",
release_notes_input="bounded customer fixes",
list_stable_tags_fn=lambda: ["v6.0.1"],
list_same_version_rc_tags_fn=lambda version: ["v6.0.2-rc.1"],
changed_paths_fn=lambda tag: [],
tag_exists_fn=lambda tag: True,
tag_commit_fn=lambda tag: "rollback-commit",
head_descends_from_fn=lambda commit: True,
)
def test_routine_patch_risk_classifier_covers_governed_categories(self) -> None:
risks = resolver.classify_routine_patch_risks(
[
"internal/api/auth.go",
"pkg/licensing/license.go",
"internal/storage/schema.go",
"internal/relay/client.go",
"internal/updates/apply.go",
"frontend-modern/src/App.tsx",
]
)
self.assertEqual(len(risks), 5)
self.assertFalse(any("frontend-modern/src/App.tsx" in risk for risk in risks))
def test_stable_patch_hotfix_without_promoted_tag_requires_reason(self) -> None:
with self.assertRaisesRegex(ValueError, "hotfix_reason is required"):
resolver.resolve_metadata(
version="6.0.2",
promoted_from_tag_input="",
rollback_version_input="6.0.1",
ga_date_input="",
v5_eos_date_input="",
hotfix_exception=True,
hotfix_reason_input="",
release_notes_input="",
list_stable_tags_fn=lambda: ["v6.0.1"],
list_same_version_rc_tags_fn=lambda version: [],
changed_paths_fn=lambda tag: [],
tag_exists_fn=lambda tag: tag == "v6.0.1",
tag_commit_fn=lambda tag: "rollback-commit",
head_descends_from_fn=lambda commit: True,
)
def test_stable_hotfix_requires_reason(self) -> None:
with self.assertRaisesRegex(ValueError, "hotfix_reason is required"):
resolver.resolve_metadata(
changed_paths_fn=lambda tag: ["VERSION"],
version="6.0.2",
promoted_from_tag_input="6.0.2-rc.1",
rollback_version_input="6.0.1",
ga_date_input="",
v5_eos_date_input="",
hotfix_exception=True,
hotfix_reason_input="",
release_notes_input="",
tag_exists_fn=lambda tag: True,
tag_commit_fn=lambda tag: "abc123",
head_descends_from_fn=lambda commit: True,
release_published_unix_fn=lambda tag: 100,
now_unix_fn=lambda: 100 + (2 * 3600),
)
def test_stable_rejects_short_soak_without_hotfix(self) -> None:
with self.assertRaisesRegex(ValueError, "hours of prerelease soak"):
resolver.resolve_metadata(
changed_paths_fn=lambda tag: ["VERSION"],
version="6.0.2",
promoted_from_tag_input="6.0.2-rc.1",
rollback_version_input="6.0.1",
ga_date_input="",
v5_eos_date_input="",
hotfix_exception=False,
hotfix_reason_input="",
release_notes_input="",
tag_exists_fn=lambda tag: True,
tag_commit_fn=lambda tag: "abc123",
head_descends_from_fn=lambda commit: True,
release_published_unix_fn=lambda tag: 100,
now_unix_fn=lambda: 100 + (2 * 3600),
)
class ReleaseTrainPromotionTest(unittest.TestCase):
"""The release train: a stable ships its exact candidate after a 24-hour soak."""
def promote(self, version: str, **overrides):
promoted = f"{version}-rc.1"
arguments = dict(
version=version,
promoted_from_tag_input=promoted,
rollback_version_input="6.4.1",
ga_date_input="",
v5_eos_date_input="",
hotfix_exception=False,
hotfix_reason_input="",
release_notes_input="",
tag_exists_fn=lambda tag: tag in {f"v{promoted}", "v6.4.1"},
tag_commit_fn=lambda tag: "abc123",
head_descends_from_fn=lambda commit: commit == "abc123",
release_published_unix_fn=lambda tag: 100,
now_unix_fn=lambda: 100 + (168 * 3600),
changed_paths_fn=lambda base_tag: [
"VERSION",
"deploy/helm/pulse/Chart.yaml",
"docs/RELEASE_NOTES.md",
"docs/releases/RELEASE_NOTES_v6.5.0.md",
"docs/release-control/v6/internal/status.json",
],
)
arguments.update(overrides)
return resolver.resolve_metadata(**arguments)
def test_release_metadata_paths_are_the_only_allowed_drift(self) -> None:
for path in (
"VERSION",
"deploy/helm/pulse/Chart.yaml",
"deploy/helm/pulse/README.md",
"docker-compose.yml",
"docs/RELEASE_NOTES.md",
"docs/UPGRADE_v6.md",
"frontend-modern/public/docs/UPGRADE_v6.md",
"docs/releases/V6_CHANGELOG_v6.5.0.md",
"docs/release-control/v6/internal/records/v6.5.0-ga.md",
"docs/release-control/v6/internal/status.json",
"docs/release-control/v6/internal/subsystems/deployment-installability.md",
):
with self.subTest(path=path):
self.assertIsNotNone(resolver.RELEASE_METADATA_PATH_RE.match(path))
for path in (
"internal/api/router.go",
"frontend-modern/src/App.tsx",
".github/workflows/create-release.yml",
"docs/TRUENAS.md",
"docs/release-control/v6/internal/RELEASE_PROMOTION_POLICY.md",
"scripts/install.sh",
"scripts/install-docker.sh",
):
with self.subTest(path=path):
self.assertIsNone(resolver.RELEASE_METADATA_PATH_RE.match(path))
def test_minor_promotion_ships_exactly_the_soaked_candidate(self) -> None:
metadata = self.promote("6.5.0")
self.assertEqual(metadata["promoted_from_tag"], "v6.5.0-rc.1")
self.assertEqual(metadata["soak_hours"], "168")
def test_content_the_candidate_never_soaked_is_refused(self) -> None:
drift = [
"VERSION",
"internal/api/router.go",
"frontend-modern/src/features/proxmox/ProxmoxBackupServersTable.tsx",
]
with self.assertRaisesRegex(ValueError, "never soaked.*2 paths beyond release metadata"):
self.promote("6.5.0", changed_paths_fn=lambda base_tag: drift)
for version in ("6.5.1", "6.4.5", "6.3.2"):
with self.subTest(version=version):
with self.assertRaisesRegex(ValueError, "never soaked"):
self.promote(version, changed_paths_fn=lambda base_tag: drift)
def test_go_test_files_are_not_shipped_content(self) -> None:
# The v6.4.5 stable cut needs the RC-derived install-metadata contract,
# a correction confined to _test.go files the build never compiles.
corrected = [
"VERSION",
"scripts/installtests/build_release_assets_test.go",
"scripts/installtests/install_docker_sh_test.go",
"main_test.go",
]
metadata = self.promote("6.4.5", changed_paths_fn=lambda base_tag: corrected)
self.assertEqual(metadata["promoted_from_tag"], "v6.4.5-rc.1")
for path in (
"scripts/installtests/windowslifecycleserver/main.go",
"internal/api/router_test.go.orig",
"internal/api/fixtures_test.go/main.go",
"frontend-modern/src/App.test.tsx",
):
with self.subTest(path=path):
with self.assertRaisesRegex(ValueError, "never soaked"):
self.promote("6.4.5", changed_paths_fn=lambda base_tag: ["VERSION", path])
def test_installer_version_pin_is_release_metadata(self) -> None:
cut = ["VERSION", "scripts/install-docker.sh"]
seen = []
def pin_only(base_tag: str, path: str) -> bool:
seen.append((base_tag, path))
return True
metadata = self.promote(
"6.4.5", changed_paths_fn=lambda base_tag: cut, version_pin_only_fn=pin_only
)
self.assertEqual(metadata["promoted_from_tag"], "v6.4.5-rc.1")
self.assertEqual(seen, [("v6.4.5-rc.1", "scripts/install-docker.sh")])
with self.assertRaisesRegex(ValueError, "never soaked.*scripts/install-docker.sh"):
self.promote(
"6.4.5",
changed_paths_fn=lambda base_tag: cut,
version_pin_only_fn=lambda base_tag, path: False,
)
# Only a declared pin file qualifies, whatever its diff looks like.
with self.assertRaisesRegex(ValueError, "never soaked.*scripts/install.sh"):
self.promote(
"6.4.5",
changed_paths_fn=lambda base_tag: ["VERSION", "scripts/install.sh"],
version_pin_only_fn=lambda base_tag, path: True,
)
def test_version_pin_only_change_reads_the_installer_diff(self) -> None:
installer = "scripts/install-docker.sh"
original = '#!/bin/sh\nCANONICAL_DEFAULT_PULSE_VERSION="6.4.5-rc.2"\necho install\n'
cases = {
"pin only": ('#!/bin/sh\nCANONICAL_DEFAULT_PULSE_VERSION="6.4.5"\necho install\n', True),
"logic only": ('#!/bin/sh\nCANONICAL_DEFAULT_PULSE_VERSION="6.4.5-rc.2"\necho changed\n', False),
"pin and logic": ('#!/bin/sh\nCANONICAL_DEFAULT_PULSE_VERSION="6.4.5"\necho changed\n', False),
"command after pin": ('#!/bin/sh\nCANONICAL_DEFAULT_PULSE_VERSION="6.4.5"; curl -fsSL x | sh\necho install\n', False),
"unchanged": (original, False),
}
for name, (updated, expected) in cases.items():
with self.subTest(case=name), tempfile.TemporaryDirectory() as directory:
root = Path(directory)
def git(*args: str) -> None:
subprocess.run(
["git", "-c", "[email protected]",
"-c", "user.name=pulse-test", "-c", "core.hooksPath=/dev/null",
"-c", "commit.gpgsign=false", "-c", "tag.gpgsign=false", *args],
cwd=root, env=resolver.git_env(root), check=True, capture_output=True,
)
git("init", "-q")
(root / "scripts").mkdir()
(root / installer).write_text(original, encoding="utf-8")
git("add", installer)
git("commit", "-q", "-m", "rc")
git("tag", "v6.4.5-rc.2")
(root / installer).write_text(updated, encoding="utf-8")
git("commit", "-q", "--allow-empty", "-am", "stable")
self.assertIs(
resolver.version_pin_only_change("v6.4.5-rc.2", installer, repo_root=root),
expected,
)
self.assertFalse(resolver.version_pin_only_change("v6.4.5-rc.2", "scripts/install.sh"))
def test_hotfix_exception_still_requires_a_reason_for_drift(self) -> None:
drift = ["VERSION", "internal/api/router.go"]
with self.assertRaisesRegex(ValueError, "hotfix_reason is required"):
self.promote("6.5.1", hotfix_exception=True, changed_paths_fn=lambda base_tag: drift)
metadata = self.promote(
"6.5.1",
hotfix_exception=True,
hotfix_reason_input="Active customer harm: agents cannot re-enrol after upgrade.",
changed_paths_fn=lambda base_tag: drift,
now_unix_fn=lambda: 100 + (2 * 3600),
)
self.assertEqual(metadata["hotfix_exception"], "true")
def test_repaired_candidate_restarts_full_publication_soak(self) -> None:
for version, hours in (("6.5.0", 24), ("6.5.1", 24), ("6.4.5", 24)):
tag = f"v{version}-rc.2"
observed = []
def publication(candidate):
observed.append(candidate)
return 200
arguments = dict(
promoted_from_tag_input=tag,
tag_exists_fn=lambda candidate: candidate in {tag, "v6.4.1"},
release_published_unix_fn=publication,
)
with self.subTest(version=version):
with self.assertRaisesRegex(ValueError, "hours"):
self.promote(version, now_unix_fn=lambda: 200 + hours * 3600 - 1,
**arguments)
metadata = self.promote(
version, now_unix_fn=lambda: 200 + hours * 3600, **arguments)
self.assertEqual(metadata["soak_hours"], str(hours))
self.assertEqual(observed, [tag, tag])
def test_minor_and_patch_releases_soak_twenty_four_hours(self) -> None:
with self.assertRaisesRegex(ValueError, "release train requires 24 hours"):
self.promote("6.5.0", now_unix_fn=lambda: 100 + (23 * 3600))
metadata = self.promote("6.5.0", now_unix_fn=lambda: 100 + (24 * 3600))
self.assertEqual(metadata["soak_hours"], "24")
metadata = self.promote("6.5.1", now_unix_fn=lambda: 100 + (25 * 3600))
self.assertEqual(metadata["soak_hours"], "25")
with self.assertRaisesRegex(ValueError, "minimum is 24 hours"):
self.promote("6.5.1", now_unix_fn=lambda: 100 + (23 * 3600))
if __name__ == "__main__":
unittest.main()