[Epic] Release Tracks: per-environment update channel selection

[sfreudenthaler]

Summary

Introduce Release Tracks for dotCMS Cloud environments: each environment subscribes to a named update channel (latest / standard / trailing) that determines how recent a release it receives.

v1 scope (this epic): track selection, operated by dotCMS. Tracks are real and per-environment, the promotion and reconciliation machinery is live, and customers choose their posture — but track changes are made by dotCMS: customers request a change via a support ticket, actioned per the interim support runbook (#36522). Self-service (UI, public API, customer-initiated changes) is deliberately split out to the related epic #36775 and is not required for this epic to be done.

Background

dotCMS Cloud customers run multiple environments (dev, UAT, prod, etc.) and have asked for more predictability over how updates flow into those environments. Today, every dotCMS Cloud environment effectively receives the same release stream on the same cadence. Customers want the option to take updates conservatively in production while still validating newer releases in lower environments.

This epic introduces a named, documented model — Release Tracks — that makes the update posture an explicit, customer-owned choice instead of an implicit platform default.

User Story

As a dotCMS Cloud customer with multiple environments,
I want to choose a Release Track per environment
so that I can validate new releases in lower environments before they reach production.

Tracks

Track	Description	Intended use
latest	Receives releases as soon as they are cut	Dev / early validation
standard	Receives releases after a short stabilization window	Default for most environments
trailing	Receives releases after an extended stabilization window	Conservative / production-leaning

Key properties

• Tracks are per-environment, not per-tenant. A customer can put dev on latest and prod on trailing within the same account.
• Tracks describe version age, not update cadence. The platform decides when each track advances; standard/trailing move only on a deliberate, human-approved maintenance-window promotion (Rebuild track promotion engine to honor 2-week maintenance-window cadence #36520), latest per release.
• Tracks do not introduce a separate code line. All tracks install the same released artifacts, at different points in time. No backporting.
• Changing tracks is forward-only in normal use: moving faster applies at the next update; moving slower never rolls an environment back.

In scope (v1)

• Floating track tags + promotion engine with taint/hold/forward-only semantics, manual maintenance-window dispatch (Floating Docker tags for Release Tracks: latest/standard/trailing promotion engine #36160, Rebuild track promotion engine to honor 2-week maintenance-window cadence #36520 — shipped).
• Per-environment track assignment via the dotcms.cloud/evergreen-track label in infrastructure-as-code manifests (Define Release Tracks data model and per-environment persistence #36528 — shipped; fleet labeled).
• In-cluster evergreen-tracks reconciler: detect floating-tag digest changes, roll subscribed environments in the maintenance window, verify convergence, alert — built, deployed, and armed across the prod fleet (dotCMS/infrastructure-as-code#8098).
• Canary customer dev environments on latest (dotCMS/infrastructure-as-code#7987).
• "Contact support" track-change flow: support-facing runbook + CX briefing (Write the interim track-change runbook and brief CX/support #36522) and in-repo operator runbook for taint/hold exceptions (Operator runbook: taint a release, hold a track, hold a single environment #36769).
• Customer-facing release policy / docs (Finalize and publish the Release Tracks doc-site announcement #36521 — shipped) and automated release changelog publishing ([Sub-Epic] Release changelog automation & publishing pipeline #36752).
• Telemetry: per-environment track feed in dotUsage; fleet observability dashboard (Build the fleet track observability dashboard #36533 — shipped); Ninety scorecard updated via local command for now (dotCMS/dotusage#71).
• Internal enablement on the tagging mechanism (dotCMS/private-issues#653).

Out of scope

• Self-service — Release Track Picker UI, public REST API, audit logging/eventing, persistence as source of truth, and the Cloud Console vs dotAdmin surface/auth ADR → split to related epic [Epic] Release Tracks self-service: Cloud Console/UI, public API, customer-initiated track changes #36775. Until then, the answer is "contact support."
• Customer-selectable update cadence, pin-to-version, future-dated updates, plugin pre-flight checks, custom health-check gating, mission-critical flags — future follow-on epics.
• Self-hosted / on-prem track support (Cloud only).
• Returning tag promotion to a scheduled cron — open question pending GTM/CX feedback, tracked standalone in Consider switching evergreen tag-promotion from manual kickoff back to a daily cron (once cluster reconciler crons are trusted) #36705 (self-hosted floating-tag users and cloud-control envs would be impacted).

Acceptance criteria (v1 = done)

• Track model defined; floating tags + promotion engine live with taint/hold/forward-only semantics (Floating Docker tags for Release Tracks: latest/standard/trailing promotion engine #36160, Rebuild track promotion engine to honor 2-week maintenance-window cadence #36520).
• Every Cloud environment has a track assignment with a documented default (Define Release Tracks data model and per-environment persistence #36528, backfills).
• Customer-facing release policy published (Finalize and publish the Release Tracks doc-site announcement #36521).
• Fleet track observability dashboard (Build the fleet track observability dashboard #36533).
• Reconciler armed (PUSH_ENABLED) across prod clusters; environments advance automatically per track (dotCMS/infrastructure-as-code#8098).
• Canary coverage on latest: bcbs/dev-2310 (deemed sufficient for v1; CX lining up more customers as ongoing adoption) (dotCMS/infrastructure-as-code#7987).
• Support can action a track-change request end-to-end: runbook published, CX briefed, one real request actioned (Write the interim track-change runbook and brief CX/support #36522); operator exception runbook merged (Operator runbook: taint a release, hold a track, hold a single environment #36769).
• Release changelogs publish automatically to dev.dotcms.com ([Sub-Epic] Release changelog automation & publishing pipeline #36752).
• Per-environment track telemetry flowing into dotUsage; scorecard measurables updatable (dotCMS/dotusage#71).
• Enablement session delivered (dotCMS/private-issues#653).

References

• Related epic: [Epic] Release Tracks self-service: Cloud Console/UI, public API, customer-initiated track changes #36775 — Release Tracks self-service (UI, public API, customer-initiated changes).
• Standalone follow-up: Consider switching evergreen tag-promotion from manual kickoff back to a daily cron (once cluster reconciler crons are trusted) #36705 — cron vs manual promotion cadence (pending GTM/CX input).
• Design mockup: Release Track Picker (internal) — now referenced from [Epic] Release Tracks self-service: Cloud Console/UI, public API, customer-initiated track changes #36775.
• Related: Evergreen release process.

Desired Outcome

Customers choose an update posture per environment; the platform honors it automatically; track changes are a routine support request. Self-service follows in #36775.

Target Personas

• Developer teams
• Content teams
• DevOps teams
• System administrators (dotCMS)

Links

• [Epic] Release Tracks self-service: Cloud Console/UI, public API, customer-initiated track changes #36775