fix: derive minimum template compatibility fixture

Author: hesreallyhim

docs/BAD_RELEASE_REPONSE_RUNBOOK.md

@@ -18,7 +18,7 @@ The guiding rule is: immutable release history is not rewritten. Recovery happen
 Use this operational runbook before and after public launch. Do not defer recovery practices until after public release. Before treating the release process as ready, ensure:
 
 - `template-contract.yml` records `accepted_action` with action tag and SHA.
-- `minimum_compatible_template_version` and `protected_template_refs` are accurate.
+- `minimum_compatible_template_version` is accurate.
 - `make template-compat-e2e` gates action releases against current and minimum compatible templates.
 - `make template-release-gates` gates template publication against the accepted action release.
 - Template release notes state compatibility resets explicitly.
@@ -54,7 +54,7 @@ First identify the failure layer:
 4. Template acceptance PR merged but template release/publication failed.
 5. Generated template release exists but publication state is incomplete.
 6. Generated template was published with wrong contents/provenance.
-7. Released action breaks an older protected template.
+7. Released action breaks an older supported template.
 8. Released template gives new users broken setup.
 
 Record:
@@ -164,7 +164,7 @@ Corrective release example:
 Corrects the generated template provenance for vA.B.C. Users who copied the previous generated template during the affected window should update from vA.B.D or verify `.reponomics/template-provenance.json`.
 ```
 
-## 7. Released Action Breaks An Older Protected Template
+## 7. Released Action Breaks An Older Supported Template
 
 Impact: compatibility promise violated.
 
@@ -216,13 +216,12 @@ Use only when supporting older templates is intentionally no longer viable.
 Required steps:
 
 1. Open a PR changing `minimum_compatible_template_version`.
-2. Update `protected_template_refs`.
-3. Explain why older templates are no longer supported.
-4. Add migration guidance.
-5. Add release notes under `## Template release notes`.
-6. Run `make template-compat-e2e`.
-7. Run `make template-release-gates`.
-8. Use a SemVer bump appropriate to user impact. While the project is pre-public and remains on `v0`, a breaking reset does not require a major version bump.
+2. Explain why older templates are no longer supported.
+3. Add migration guidance.
+4. Add release notes under `## Template release notes`.
+5. Run `make template-compat-e2e`.
+6. Run `make template-release-gates`.
+7. Use a SemVer bump appropriate to user impact. While the project is pre-public and remains on `v0`, a breaking reset does not require a major version bump.
 
 Example:
 
@@ -276,7 +275,7 @@ Use one or more scenarios:
 2. Template acceptance PR merged, but `template-release.yml` failed.
 3. Source template tag exists, but `template-release.yml` failed before generated publication.
 4. Generated template publication completed with wrong provenance.
-5. Action patch release breaks the minimum compatible protected template.
+5. Action patch release breaks the minimum compatible template.
 6. Template release gives new copied repositories broken setup.
 
 For each scenario, record:

scripts/accept_action_release.py

@@ -117,8 +117,6 @@ def accept_action_release(
         payload["compatible_action_major"] = action_major
         payload["default_action_ref"] = expected_default_ref
     payload["accepted_action"] = next_action
-    if not payload.get("protected_template_refs"):
-        payload["minimum_compatible_template_version"] = payload["template_version"]
 
     next_text = yaml.safe_dump(payload, sort_keys=False)
     contract_path.write_text(next_text, encoding="utf-8")

scripts/prepare_template_release.py

@@ -65,8 +65,6 @@ def prepare_template_release(
     previous_version = contract.template_version
     next_version = bump_version(previous_version, release_type)
     payload["template_version"] = next_version
-    if not payload.get("protected_template_refs"):
-        payload["minimum_compatible_template_version"] = next_version
     contract_path.write_text(yaml.safe_dump(payload, sort_keys=False), encoding="utf-8")
     try:
         template_contract.validate_local_contract(root)

scripts/template_compat_e2e.py

@@ -218,6 +218,12 @@ class GeneratedTemplate:
     source_commit: str
 
 
+@dataclass(frozen=True)
+class TemplateRefFixture:
+    ref: str
+    template_version: str
+
+
 def _load_mapping(path: Path) -> dict[str, Any]:
     payload = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
     if not isinstance(payload, dict):
@@ -345,38 +351,35 @@ def _current_template(
     )
 
 
+def _template_ref_for_version(template_version: str) -> str:
+    return f"reponomics-dashboard-v{template_version}"
+
+
 def _build_template_from_ref(
-    protected_ref: template_contract.ProtectedTemplateRef,
+    fixture: TemplateRefFixture,
     *,
     base_python: Path,
     work_root: Path,
 ) -> GeneratedTemplate:
     source_dir = work_root / "source"
     output_dir = work_root / "generated-template"
-    source_commit = _checkout_ref(protected_ref.ref, source_dir)
-    if source_commit != protected_ref.source_commit:
-        raise TemplateCompatibilityError(
-            (
-                f"{protected_ref.ref}: expected source commit "
-                + f"{protected_ref.source_commit}, got {source_commit}"
-            )
-        )
+    source_commit = _checkout_ref(fixture.ref, source_dir)
 
     source_contract = _load_mapping(source_dir / "template-contract.yml")
     source_version = str(source_contract.get("template_version") or "")
-    if source_version != protected_ref.template_version:
+    if source_version != fixture.template_version:
         raise TemplateCompatibilityError(
             (
-                f"{protected_ref.ref}: contract version {source_version!r} does not "
-                + f"match protected version {protected_ref.template_version}"
+                f"{fixture.ref}: contract version {source_version!r} does not "
+                + f"match fixture version {fixture.template_version}"
             )
         )
 
     build_python = _install_isolated_python_env(
         source_dir=source_dir,
         venv_dir=work_root / "template-build-runtime",
         base_python=base_python,
-        label=f"{protected_ref.ref} template build",
+        label=f"{fixture.ref} template build",
     )
     _git_output(
         [
@@ -389,20 +392,20 @@ def _build_template_from_ref(
     )
     provenance = _load_mapping(output_dir / ".reponomics" / "template-provenance.json")
     provenance_template_version = str(provenance.get("template", {}).get("version") or "")
-    if provenance_template_version != protected_ref.template_version:
+    if provenance_template_version != fixture.template_version:
         raise TemplateCompatibilityError(
-            f"{protected_ref.ref}: generated provenance does not match template version"
+            f"{fixture.ref}: generated provenance does not match template version"
         )
-    if str(provenance.get("source", {}).get("commit") or "") != protected_ref.source_commit:
+    if str(provenance.get("source", {}).get("commit") or "") != source_commit:
         raise TemplateCompatibilityError(
-            f"{protected_ref.ref}: generated provenance does not match source commit"
+            f"{fixture.ref}: generated provenance does not match source commit"
         )
 
     return GeneratedTemplate(
-        name=protected_ref.ref,
+        name=fixture.ref,
         repo_dir=output_dir,
-        template_version=protected_ref.template_version,
-        source_commit=protected_ref.source_commit,
+        template_version=fixture.template_version,
+        source_commit=source_commit,
     )
 
 
@@ -627,22 +630,27 @@ def run_compatibility_checks(
         except Exception as exc:
             failures.append(f"current template: {exc}")
 
-        protected_refs = [] if current_template_only else list(contract.protected_template_refs)
+        template_fixtures: list[TemplateRefFixture] = []
+        if not current_template_only:
+            template_fixtures.append(
+                TemplateRefFixture(
+                    ref=_template_ref_for_version(contract.minimum_compatible_template_version),
+                    template_version=contract.minimum_compatible_template_version,
+                )
+            )
         for extra_ref in extra_template_refs or []:
-            protected_refs.append(
-                template_contract.ProtectedTemplateRef(
+            template_fixtures.append(
+                TemplateRefFixture(
                     ref=extra_ref,
                     template_version=extra_ref.removeprefix("reponomics-dashboard-v"),
-                    source_commit=_ensure_git_ref(extra_ref),
-                    status="required",
                 )
             )
 
-        for protected_ref in protected_refs:
+        for template_fixture in template_fixtures:
             work_root = Path(tempfile.mkdtemp(prefix="template-", dir=compat_root))
             try:
                 generated_template = _build_template_from_ref(
-                    protected_ref,
+                    template_fixture,
                     base_python=base_python,
                     work_root=work_root,
                 )
@@ -662,7 +670,7 @@ def run_compatibility_checks(
                 if keep_temp:
                     print(f"Kept compatibility work tree: {work_root}")
             except Exception as exc:
-                failures.append(f"{protected_ref.ref}: {exc}")
+                failures.append(f"{template_fixture.ref}: {exc}")
             finally:
                 if not keep_temp:
                     _remove_worktree(work_root / "source")

scripts/template_contract.py

@@ -52,23 +52,11 @@
 ACTION_REF_RE = re.compile(r"reponomics/reponomics-dashboard-action@[^\s'\"<>)\]}]+")
 INPUT_EXPR_RE = re.compile(r"\$\{\{\s*inputs\.([A-Za-z0-9_-]+)\s*\}\}")
 GIT_SHA_RE = re.compile(r"^[0-9a-f]{40}$")
-TEMPLATE_RELEASE_REF_RE = re.compile(
-    r"^reponomics-dashboard-v(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$"
-)
-
 
 class TemplateContractError(RuntimeError):
     """Raised when the local action/template contract is invalid."""
 
 
-@dataclass(frozen=True)
-class ProtectedTemplateRef:
-    ref: str
-    template_version: str
-    source_commit: str
-    status: str = "required"
-
-
 @dataclass(frozen=True)
 class AcceptedActionRelease:
     repository: str
@@ -86,7 +74,6 @@ class TemplateContract:
     compatible_action_major: int
     accepted_action: AcceptedActionRelease
     minimum_compatible_template_version: str
-    protected_template_refs: tuple[ProtectedTemplateRef, ...]
     managed_docs_namespace: Path
 
     @property
@@ -122,11 +109,6 @@ def load_contract(root: Path = ROOT) -> TemplateContract:
         payload.get("accepted_action"),
         path=path,
     )
-    protected_template_refs = _parse_protected_template_refs(
-        payload.get("protected_template_refs"),
-        path=path,
-    )
-
     if not SEMVER_RE.fullmatch(template_version):
         raise TemplateContractError(f"template_version must be SemVer, got {template_version!r}")
     if not SEMVER_RE.fullmatch(minimum_compatible_template_version):
@@ -161,11 +143,6 @@ def load_contract(root: Path = ROOT) -> TemplateContract:
     )
     if managed_docs_namespace.as_posix() != "docs/reponomics":
         raise TemplateContractError("managed_docs_namespace must be docs/reponomics")
-    _validate_protected_template_refs(
-        protected_template_refs,
-        minimum_compatible_template_version=minimum_compatible_template_version,
-        template_version=template_version,
-    )
 
     return TemplateContract(
         template_version=template_version,
@@ -174,7 +151,6 @@ def load_contract(root: Path = ROOT) -> TemplateContract:
         compatible_action_major=compatible_action_major,
         accepted_action=accepted_action,
         minimum_compatible_template_version=minimum_compatible_template_version,
-        protected_template_refs=tuple(protected_template_refs),
         managed_docs_namespace=managed_docs_namespace,
     )
 
@@ -211,57 +187,6 @@ def validate_local_contract(root: Path = ROOT) -> TemplateContract:
     return contract
 
 
-def _parse_protected_template_refs(
-    raw_refs: object,
-    *,
-    path: Path,
-) -> list[ProtectedTemplateRef]:
-    if not isinstance(raw_refs, list):
-        raise TemplateContractError(f"{path} must declare protected_template_refs as a list")
-
-    protected: list[ProtectedTemplateRef] = []
-    for index, raw_ref in enumerate(raw_refs):
-        if not isinstance(raw_ref, dict):
-            raise TemplateContractError(
-                f"protected_template_refs[{index}] must be a YAML object"
-            )
-        ref = str(raw_ref.get("ref") or "")
-        template_version = str(raw_ref.get("template_version") or "")
-        source_commit = str(raw_ref.get("source_commit") or "")
-        status = str(raw_ref.get("status") or "required")
-
-        if not TEMPLATE_RELEASE_REF_RE.fullmatch(ref):
-            raise TemplateContractError(
-                f"protected_template_refs[{index}].ref must be reponomics-dashboard-vX.Y.Z"
-            )
-        if not SEMVER_RE.fullmatch(template_version):
-            raise TemplateContractError(
-                f"protected_template_refs[{index}].template_version must be SemVer"
-            )
-        if ref != f"reponomics-dashboard-v{template_version}":
-            raise TemplateContractError(
-                f"protected_template_refs[{index}] ref must match template_version"
-            )
-        if not GIT_SHA_RE.fullmatch(source_commit):
-            raise TemplateContractError(
-                "protected_template_refs"
-                + f"[{index}].source_commit must be a 40-character commit SHA"
-            )
-        if status != "required":
-            raise TemplateContractError(
-                f"protected_template_refs[{index}].status must be required"
-            )
-        protected.append(
-            ProtectedTemplateRef(
-                ref=ref,
-                template_version=template_version,
-                source_commit=source_commit,
-                status=status,
-            )
-        )
-    return protected
-
-
 def _parse_accepted_action_release(
     raw_action: object,
     *,
@@ -309,29 +234,6 @@ def _validate_accepted_action_release(
         raise TemplateContractError("accepted_action.sha must be a 40-character commit SHA")
 
 
-def _validate_protected_template_refs(
-    protected_template_refs: list[ProtectedTemplateRef],
-    *,
-    minimum_compatible_template_version: str,
-    template_version: str,
-) -> None:
-    seen_versions: set[str] = set()
-    for protected in protected_template_refs:
-        if protected.template_version in seen_versions:
-            raise TemplateContractError(
-                f"duplicate protected template version: {protected.template_version}"
-            )
-        seen_versions.add(protected.template_version)
-    if (
-        minimum_compatible_template_version != template_version
-        and minimum_compatible_template_version not in seen_versions
-    ):
-        raise TemplateContractError(
-            "historical minimum_compatible_template_version must be covered "
-            + "by protected_template_refs"
-        )
-
-
 def render_managed_docs_snapshot(
     *,
     contract: TemplateContract | None = None,

template-contract.yml

@@ -10,5 +10,4 @@ accepted_action:
   sha: 07708b602d253512c37cf773912375784882947d
   default_ref: v0
 minimum_compatible_template_version: 0.16.0
-protected_template_refs: []
 managed_docs_namespace: docs/reponomics