diff --git a/docs/release-control/v6/internal/CANONICAL_DEVELOPMENT_PROTOCOL.md b/docs/release-control/v6/internal/CANONICAL_DEVELOPMENT_PROTOCOL.md index 4ebf92050..d9705d9bf 100644 --- a/docs/release-control/v6/internal/CANONICAL_DEVELOPMENT_PROTOCOL.md +++ b/docs/release-control/v6/internal/CANONICAL_DEVELOPMENT_PROTOCOL.md @@ -253,6 +253,60 @@ print a non-passing receipt skeleton with `python3 scripts/release_control/browser_verification_guard.py --print-template` after staging the intended frontend paths. +## Reporter Test Image Validation Path + +When a reviewed fix needs live confirmation from one or a few Docker-based +reporters, use an immutable reporter test image by default instead of cutting +an RC solely to obtain that narrow evidence. This is a diagnostic source-build +path. It is not a release channel, a lighter RC, or an alternate promotion +mechanism. + +The canonical operational contract lives in +`docs/release-control/v6/internal/RELEASE_PROMOTION_POLICY.md`. Every reporter +test image must satisfy these agent-facing rules: + +1. bind the image to one exact reviewed repository commit and one named issue +2. build only trusted project code in an isolated builder that cannot expose + workspace secrets, signing material, production data, or unrelated Docker + workloads +3. publish a new immutable tag shaped as `test--` and record + the registry digest, never overwrite or reuse the tag +4. stamp source, revision, and an explicit test-build version identity so the + runtime cannot be mistaken for a released stable or RC build +5. target the reporter's required platform, with multi-architecture publication + only when the validation cohort actually needs it +6. pass the targeted regression proof plus a clean-container start, health, + and version smoke before the image is offered +7. provide the exact tag and digest, focused validation steps, diagnostic-build + warning, backup guidance, rollback image, and failure-evidence request in + the approved reporter reply +8. keep the issue open until the named user-visible behavior is confirmed or + conservatively superseded by another active issue +9. treat reporter confirmation as narrow live evidence for that issue and + environment, never as release qualification or prerelease lineage +10. fix failed images forward under new commit-derived tags and never mutate + an already shared artifact + +This path must not create a GitHub release or git tag, update release notes or +update feeds, publish Helm, move Docker aliases, update the demo, stage or +promote private paid artifacts, or satisfy any RC or stable release gate. A +real RC, stable, or patch release still enters once through the canonical +single-build release workflow and rebuilds the release artifact under its +governed version and qualification contract. + +Use the full RC path when the intended cohort is broad, several independent +reporters or platforms need validation, or the proof depends on installers, +updaters, Helm, private artifacts, cross-repo compatibility, migrations, +destructive state changes, authentication or another trust boundary, or +stable-promotion lineage. When classification is uncertain, choose the RC +path. + +Successful reporter validation does not force an immediate patch release. +Severity and active customer harm decide scheduling. After a stable release +containing the fix ships and the issue is resolved, the test image becomes +eligible for removal only with explicit maintainer approval. Its tag must +never be reused. + ## Task Completion Protocol Every substantial task must finish by checking these questions: diff --git a/docs/release-control/v6/internal/RELEASE_PROMOTION_POLICY.md b/docs/release-control/v6/internal/RELEASE_PROMOTION_POLICY.md index 0b03b1228..bb1564b0a 100644 --- a/docs/release-control/v6/internal/RELEASE_PROMOTION_POLICY.md +++ b/docs/release-control/v6/internal/RELEASE_PROMOTION_POLICY.md @@ -28,6 +28,95 @@ Cloud, and self-hosted production users. - Are not a customer-facing release channel. - Remain reserved for development, debugging, and branch validation. +## Reporter Test Image Contract + +A reporter test image is an issue-scoped diagnostic source build for one or a +few explicitly participating Docker users. It exists to validate a reviewed +fix quickly without manufacturing an RC or exposing the broader preview +cohort to an unqualified candidate. + +It is not a fourth release channel. It does not count as `rc`, `stable`, a +published prerelease, release qualification, or stable-promotion lineage. + +### Eligibility + +Use a reporter test image only when all of these conditions hold: + +1. the reported behavior has a concrete diagnosis or reproduction, an exact + reviewed fix commit, and targeted automated regression proof +2. the reporter runs Docker or an equivalent OCI deployment and the affected + behavior can be validated without an installer, updater, Helm, mobile, + private paid-runtime, or other release-only surface +3. the validation cohort is one or a few named issue participants rather than + a broad preview audience +4. the reporter can pin an exact image and return to a known release image +5. the test does not require destructive data migration, production secret + handling, or a widened authentication, authorization, tenant, billing, + licensing, relay, or other trust boundary + +If any condition is false or uncertain, use the governed RC path. + +### Build And Publication + +1. Build from one exact reviewed commit in the canonical Pulse repository. + Never build arbitrary contributor code on a machine or builder that can + access registry credentials, signing material, production data, workspace + secrets, or unrelated Docker workloads. +2. Use an isolated builder and clean source state. Do not pass host secrets, + production mounts, privileged runtime access, or unrelated Docker sockets + into the build. +3. Publish a new immutable tag shaped as `test--`, for + example `rcourtman/pulse:test-1437-44a3f194`. Never overwrite or reuse the + tag. +4. Stamp OCI source and revision labels. The running Pulse version must identify + the released base plus test issue and commit metadata, for example + `v6.2.1+test.1437.44a3f194`. It must not impersonate a stable or RC version. +5. Build only the reporter's required platform unless more than one platform + is part of the named validation cohort. Record every published platform. +6. Run the targeted regression proof plus a clean-container start, health + check, and version check before sharing the image. Pull the published image + by digest for the final smoke so registry publication itself is exercised. +7. Record the source commit, image tag, registry digest, platform, proof + commands, smoke result, exact pull or Compose override, and exact rollback + image in the task handoff. Preserve the tag, digest, test steps, and rollback + image in the approved issue reply so later triage can recover the artifact + identity without relying on chat history. + +### Reporter Guidance And Claims + +1. Do not offer the image until it is published, pullable by digest, and has + passed the required smoke. +2. The approved reporter reply must include the exact tag and digest, describe + it as a temporary diagnostic build, name the focused checks, recommend a + backup and non-production use where practical, provide the prior stable + rollback image, and request fresh diagnostics from the same reproduction + window if validation fails. +3. Keep the issue open until the named user-visible behavior is confirmed or + conservatively superseded by another active issue. +4. Reporter confirmation is narrow live evidence for the named issue, + environment, commit, image digest, and exercised behavior. It does not + qualify installers, updater behavior, Helm, other architectures, private + paid runtime, cross-repo compatibility, migrations, security boundaries, + or the wider release. +5. A successful test does not force an immediate patch release. Schedule the + fix by severity and active customer harm. Any later RC, stable, or patch + must rebuild and qualify through the canonical release workflow rather + than promote the reporter image. + +### Forbidden Release Mutations And Lifecycle + +1. A reporter test image must never create a GitHub release or git tag, update + release notes or update feeds, publish Helm, move Docker aliases, update the + demo, stage or promote private paid artifacts, or satisfy an RC or stable + release gate. +2. Never attach `latest`, a stable version, an RC version, or another mutable + alias to the image. +3. Failed validation is fixed forward from a new reviewed commit and published + under a new commit-derived tag. Shared tags and digests are immutable. +4. After a stable release containing the fix ships and the issue is resolved, + the test image becomes eligible for removal only with explicit maintainer + approval. The old tag remains retired and must never be reused. + ## Development Model 1. Use short-lived feature branches and feature flags for incomplete or risky diff --git a/docs/release-control/v6/internal/SOURCE_OF_TRUTH.md b/docs/release-control/v6/internal/SOURCE_OF_TRUTH.md index 79b995629..75143f156 100644 --- a/docs/release-control/v6/internal/SOURCE_OF_TRUTH.md +++ b/docs/release-control/v6/internal/SOURCE_OF_TRUTH.md @@ -660,6 +660,17 @@ Assertion design rules: `cloud-commercial-transition-external-proof`, and `account-commercial-transition-external-proof`; they must pass before the feature is enabled. +21. A reviewed Docker fix that needs confirmation from one or a few named issue + reporters should use an immutable issue-and-commit reporter test image by + default instead of cutting an RC solely for that narrow validation. The + image is a diagnostic source build, not a release channel, prerelease, + release-qualified artifact, or stable-promotion lineage. It may not move + mutable aliases or any GitHub, updater, Helm, demo, private paid-runtime, + or other release surface. Broad, multi-platform, release-surface, + migration, destructive-state, trust-boundary, cross-repo, and promotion- + lineage validation remains on the governed RC path. Successful reporter + confirmation informs severity-based release scheduling but does not force + an immediate patch release. ## TrueNAS Support Floor diff --git a/docs/release-control/v6/internal/status.json b/docs/release-control/v6/internal/status.json index 44b30ca41..0a9f93881 100644 --- a/docs/release-control/v6/internal/status.json +++ b/docs/release-control/v6/internal/status.json @@ -10506,6 +10506,16 @@ "L2", "L3" ] + }, + { + "id": "reporter-test-image-validation-path", + "summary": "A reviewed Docker fix that needs confirmation from one or a few named issue reporters uses an immutable issue-and-commit test image by default instead of manufacturing an RC solely for narrow validation. The image remains a diagnostic source build, cannot mutate release surfaces or satisfy release lineage, and does not force an immediate patch after successful reporter confirmation.", + "kind": "release-policy", + "decided_at": "2026-08-10", + "subsystem_ids": [], + "lane_ids": [ + "L1" + ] } ] }