Pulse v6 Prerelease Runbook

This runbook captures the branch-specific operational path that was used while main continued to serve v5 releases during the v6 prerelease period.

Canonical customer-channel and promotion rules now live in docs/release-control/v6/RELEASE_PROMOTION_POLICY.md. Current release-branch authority lives in docs/release-control/control_plane.json. If this historical runbook and the release-control policy disagree, the release-control policy wins.

Branch Model (Current)

main: v5 stable (current public/stable line)
pulse/v6-release: active v6 prerelease and stable release line until an explicit post-GA branch cutover is governed

Do not move main to v6 during prerelease.

Enforced Workflow Policy

Release workflows now enforce branch/tag lineage rules:

Pulse Release Pipeline (create-release.yml)
- Resolves stable versus prerelease branch requirements from docs/release-control/control_plane.json.
- For the current v6 profile, both stable and prerelease releases dispatch from pulse/v6-release.
publish-docker.yml, promote-floating-tags.yml, publish-helm-chart.yml, and update-demo-server.yml
- Validate the release tag commit is reachable from the governed branch for that version instead of assuming main.
update-demo-server.yml
- Accepts stable tags only.
- Stable tag must be reachable from the governed stable branch.

This prevents accidental cross-line releases from non-governed branches even if the stable branch changes later.

Important Scope Note

The Pulse release workflow in this repo (.github/workflows/create-release.yml) builds from the checked-out Pulse ref and runs ./scripts/build-release.sh, which builds ./cmd/pulse.

It does not automatically check out or build pulse-enterprise.

Versioning Rules

v5 stable examples: 5.1.14
v6 prerelease examples: 6.0.0-rc.1, 6.0.0-rc.2
v6 GA example: 6.0.0

The workflow auto-marks -rc.N/-alpha.N/-beta.N as prerelease.

Preconditions for Each RC

pulse/v6-release is pushed and green in CI.
VERSION file in pulse/v6-release exactly matches the release input version.
Release notes are prepared.
PULSE_LICENSE_PUBLIC_KEY secret is present in GitHub Actions.

RC Release Steps

Update version on pulse/v6-release:

git checkout pulse/v6-release
git pull --ff-only
echo "6.0.0-rc.1" > VERSION
git add VERSION
git commit -m "chore(release): bump version to 6.0.0-rc.1"
git push origin pulse/v6-release

Optional preflight dry run:
- Run workflow: Release Dry Run
- Ref: pulse/v6-release
- Inputs:
  - version: 6.0.0-rc.1
  - optional note
Create draft prerelease:
- Run workflow: Pulse Release Pipeline
- Ref: pulse/v6-release
- Inputs:
  - version: 6.0.0-rc.1
  - release_notes: markdown text
  - draft_only: true
Validate draft outputs:
- Confirm assets exist and checksums match.
- Confirm GitHub release is marked prerelease.
- Smoke install on a test host/container.
Publish prerelease:
- Re-run Pulse Release Pipeline on pulse/v6-release
- Same version and notes
- draft_only: false
- Demo server update is skipped automatically for prereleases.
Canary rollout:
- Upgrade a small user subset first.
- Collect regressions, fix on pulse/v6-release, then cut rc.2/rc.3 as needed.

Keep v5 Stable During v6 RC

Continue v5 patch releases from main as normal.
Do not merge pulse/v6-release into main during prerelease.
Keep v5 and v6 changelogs/release notes separate.

GA Cutover (Only After RC Confidence)

Do this only when v6 is proven stable in production-like usage.

Create v5 long-tail branch from current main:

git checkout main
git pull --ff-only
git checkout -b pulse/v5-maintenance
git push -u origin pulse/v5-maintenance

Keep the governed v6 release line on pulse/v6-release for GA:

git checkout pulse/v6-release
git pull --ff-only

Release 6.0.0 from pulse/v6-release using Pulse Release Pipeline. Before the real GA publish, run ./scripts/trigger-release-dry-run.sh 6.0.0 from pulse/v6-release. That helper validates the default-branch workflow-dispatch contract before calling GitHub so stale main workflow inputs fail locally instead of returning an opaque 422 from gh workflow run. The governed Release Dry Run must still carry:
- version: 6.0.0
- promoted_from_tag: exact RC tag being promoted
- rollback_version: prior stable
- ga_date: exact published v6 GA date
- v5_eos_date: exact published v5 end-of-support date
- optional hotfix_exception and hotfix_reason Attach the rc-to-ga-rehearsal-summary artifact and run URL to the release ticket, and confirm the artifact carries the canonical promotion metadata envelope for that candidate: candidate stable tag, promotion channel, promoted RC tag, rollback target, exact rollback command, planned GA date, and planned v5 end-of-support date.
Publish the exact v6 GA date and v5 end-of-support date in the GA release notice using docs/release-control/v6/V5_MAINTENANCE_SUPPORT_POLICY.md as the canonical policy.
Continue critical v5 fixes from pulse/v5-maintenance only.
- The support window lasts 90 calendar days from v6 GA.
- Only critical security issues, critical correctness/data-loss issues, installer or updater failures, licensing or billing blockers, and safe migration blockers are eligible during that window.
- After that window, v5 is unsupported.
Treat any future move of stable v6 releases away from pulse/v6-release as a separate post-GA governance change; do not assume an automatic cutover to main.

Rollback Strategy

If an RC is bad:

Do not promote to GA.
Keep fixing on pulse/v6-release.
Cut next RC.
Keep v5 users on main stable releases.

If GA has a severe regression:

Patch quickly on pulse/v6-release (v6.0.1), or
Advise affected users to hold at prior stable while fix ships.
Continue v5 emergency fixes from pulse/v5-maintenance only if the published maintenance-only window is still active or I explicitly announce an exception.

Minimal Per-Release Checklist

Version file matches workflow input.
CI green on release ref.
Draft release validated.
Checksums and assets verified.
Canary cohort upgraded successfully.
Rollback note prepared before publish.

6.4 KiB Raw Blame History