Pulse/docs/release-control/v6/internal/RELEASE_PROMOTION_POLICY.md

# Pulse v6 Release Promotion Policy

This document defines how Pulse v6 and later releases move from development to
customer-facing availability. It is the release-trust contract for Pulse Pro,
Cloud, and self-hosted production users.

## Goals

1. Stable customers must not become the first test cohort for new changes.
2. Development speed must stay decoupled from customer exposure.
3. Every broad rollout must have explicit validation and rollback rules.

## Channel Contract

1. `stable`
   - Default for new installs.
   - The only recommended channel for paid and production environments.
   - Publishes only non-prerelease tags.
   - The only channel eligible for unattended broad rollout.
2. `rc`
   - Opt-in preview channel for internal use, staging-like environments, and
     explicitly willing preview users.
   - Publishes prerelease tags such as `6.0.0-rc.1`.
   - Must never be the default channel.
   - In v6, `rc` affects manual and in-app update selection; unattended
     systemd auto-updates remain `stable`-only.
3. Source builds
   - Are not a customer-facing release channel.
   - Remain reserved for development, debugging, and branch validation.

## Development Model

1. Use short-lived feature branches and feature flags for incomplete or risky
   work.
2. Do not move directly from "issue fixed" to "all customers updated".
3. Channel promotion is the primary customer-safety boundary.
4. Branch topology may change over time; the `stable` versus `rc` customer
   contract must not.
5. The active release profile in `docs/release-control/control_plane.json`
   owns the governed prerelease and stable release branches for the current
   line; release automation must resolve branch requirements from that file
   instead of assuming `main`.

## Prerelease Rules

1. Every candidate intended for broad customer use must ship to `rc` before it
   is eligible for `stable`.
2. Each published prerelease must have:
   - Targeted automated checks for touched release surfaces.
   - A smoke install on a fresh or staging-like environment.
   - Release notes plus the rollback target and exact reinstall command recorded before publish.
   - At least one live run of the release pipeline for the prerelease tag itself, not
     only structural workflow validation.
   - A governed prerelease publication record; an accidental git tag by itself
     does not count as a shipped prerelease.
3. Failed prereleases are fixed forward and replaced with a new prerelease. They are never
   promoted as-is to `stable`.

## v5 Maintenance Policy

1. When Pulse v6 reaches `stable`, Pulse v5 immediately enters
   maintenance-only support.
2. The maintenance-only window lasts 90 calendar days from the v6 GA or stable
   release date.
3. During that window, v5 fixes are limited to:
   - critical security issues
   - critical correctness or data-loss issues
   - migration blockers that prevent customers from reaching a safe v6 path
4. v5 will not receive:
   - new features
   - normal bug-fix backports
   - pricing-model exceptions
   - entitlement-model parity work introduced for v6
5. After the 90-day window ends, v5 may continue running for users who choose
   to stay on it, but it is unsupported.
6. The v6 GA announcement must publish the exact v5 end-of-support date
   calculated from the GA publication date.
7. Before GA promotion is actually cleared, release notes may keep placeholder
   dates for the GA notice; those placeholders do not satisfy the promotion
   gate by themselves.
8. `V5_MAINTENANCE_SUPPORT_POLICY.md` is the canonical source for this policy
   and the required GA release notice.

## Stable Promotion Rules

1. A stable tag must be promoted from a commit that has already been exercised
   as a published prerelease.
2. A prerelease git tag counts as stable-promotion lineage only if that prerelease was
   actually published through the governed prerelease path; accidental or abandoned git
   tags do not satisfy the stable-promotion requirement.
3. For v6 GA, do not promote to `stable` until the active control-plane target
   is the GA-promotion target and satisfies its `release_ready` completion
   rule.
4. Every stable promotion requires:
   - Applicable items in `PRE_RELEASE_CHECKLIST.md` complete.
   - Applicable entries in `HIGH_RISK_RELEASE_VERIFICATION_MATRIX.md` cleared.
   - No known unresolved RC-era user-visible issues intended for the v6 GA
     scope remain open. Each one must be fixed in the candidate, proven
     invalid with evidence, or conservatively superseded with the original
     failure resolved or explicitly narrowed.
   - The previous stable rollback target and exact reinstall command recorded.
   - A live release-pipeline exercise already completed for the promoted prerelease tag,
     not only YAML lint or static workflow validation.
   - The locked 90-day v5 maintenance-only policy in
     `V5_MAINTENANCE_SUPPORT_POLICY.md` and the exact end-of-support notice
     ready to publish with the promotion.
5. Normal stable promotions require a minimum 72-hour prerelease soak after the
   candidate is available to internal or staging-like users.
6. Hotfix exception:
   - A shorter soak is allowed only for narrowly scoped fixes to active
     customer harm.
   - The exception plus the rollback target and exact reinstall command must be
     recorded in the release notes or release ticket before promotion.

## Rollout Rules

1. Default installs stay on `stable`.
2. Broad customer announcements and unattended updates target `stable` only.
3. `rc` enrollment must be explicit and reversible.
4. Paid production tenants should remain on `stable` unless they are knowingly
   participating in preview validation.

## Rollback Rules

1. Never delete or rewrite shipped tags to hide a bad release; supersede them
   with a newer release and explicit guidance.
2. If a prerelease is bad, hold it in `rc`, fix forward, and cut the next prerelease. Do not
   promote it.
3. If a stable release is bad:
   - Pause further promotion or auto-update exposure.
   - Direct affected users to the prior stable pin.
   - Cut and validate a hotfix or rollback release.
4. The previous stable version must remain installable by exact version pin
   until the replacement stable release is trusted.

## Required Release Artifacts

1. Release notes.
2. Rollback target version and exact pin command.
3. Checklist evidence and gate status.
4. Staging or internal validation note.
5. v5 maintenance-only support policy and end-of-support note for the GA cutover.
6. Exact v6 GA and v5 end-of-support dates locked before GA publish and then
   published in the GA release notes.
7. Prerelease-to-GA rehearsal record plus the machine-generated
   `rc-to-ga-rehearsal-summary` artifact, including the GitHub Actions run URL
   for the non-publish dry run and the canonical promotion metadata envelope:
   candidate stable tag, promotion channel, promoted prerelease tag, rollback target,
   exact rollback command, planned GA date, and planned v5 end-of-support
   date. Materialize that dated record with
   `python3 scripts/release_control/record_rc_to_ga_rehearsal.py --run-id <run-id>`
   unless an explicitly different output path is needed.
8. The pushed governed release-branch copy of `.github/workflows/release-dry-run.yml`
   must already accept that stable rehearsal metadata envelope through
   `workflow_dispatch`, and the local release branch must match `origin` before
   dispatch, because GitHub executes the selected remote ref and does not see
   local-only governance state.
9. For v6 GA, the exact self-hosted public forward and rollback packet must be
   locked in the launch ticket before promotion: preview deploy/audit commands,
   production deploy/audit commands, and the explicit rollback deploy/audit
   commands that return `pulserelay.pro` to the approved v5 posture.
10. For v6 GA, attach the dated RC issue-closure record for the candidate so
    the final issue set and its dispositions are explicit in the promotion
    packet rather than implied.

## Authority

If conflicts appear:

1. `SOURCE_OF_TRUTH.md` owns the locked decision that this policy is mandatory.
2. `status.json` owns whether the decision is open or resolved and whether the
   active target is release-ready.
3. `PRE_RELEASE_CHECKLIST.md` and
   `HIGH_RISK_RELEASE_VERIFICATION_MATRIX.md` own execution proof for a
   specific promotion.