Skip to content

ccoalm/ccl-skills / skills/platform-release-engineering

platform-release-engineering

Verified

发布 / 灰度 / canary / rollback / rollout / 环境泳道 / promotion gate / 发布值班 SOP(P0·P1 打断排班、是否回滚)→ design or review how a change moves from build to traffic and back safely, including rollout strategy, approval, rollback, secrets, config, and deploy control planes. Skip when the ask is the production release lifecycle — 上线范围确认 / 合并 main / 打 tag / 生产构建 / 发布后 reset → release-coordination; release document substance → release-doc-writer.

references/version-authority-and-deprecation.md

View on GitHub
# Version authority and deprecation timing

The two cross-repo version decision-cliffs the `## Decision Points` one-liners
route here. `product-rd-workflow`'s spec/repo-contract sync gate cross-refs this;
this skill owns the layered version model and the rollout-timing decision.

## "Where the version number lives across repos" (version-authority layering)

Version management is layered, each layer one owner + one change-mode: contract version (tag — immutable, accumulate) → version combination (manifest — current-state, update-in-place) → consumer pin (dependency declaration — current-state) → repo-local **agent contract** (`AGENTS.md`: version-independent rules + a pointer to the authority; **must not copy the authoritative current pin**, which drifts on the next bump).

Exception (narrow): **non-normative historical artifacts** (audit / release-note) and **generated artifacts with a checked generation source** MAY inline a version, labeled `generated/as-of <authority> @ <ref/date>` with owner + refresh/generation path; but if anything consumes the artifact for a **current** decision it must resolve the authority at use-time or pass a freshness gate (source ref + generation command + owner + max-age/refresh + CI check). The exception is not a license to copy the current pin into any doc and call it a snapshot. `product-rd-workflow`'s spec/repo-contract sync gate cross-refs this.

**Current-state layers need a standing drift check, not same-batch discipline.** The `update-in-place` layers above (the combination manifest and consumer pins) and any agent/human status doc that restates them are the only layers that *drift* — immutable tags do not. "Update it in the same delivery batch" is a discipline rule that silently fails across sessions and teams: the manifest or status doc keeps asserting an old combination while components moved on (e.g. a status doc still naming an old contract version as "what mainline tracks" long after mainline advanced). Do not rely on an agent or person remembering to reconcile — for a manifest/status doc that is **decision-bearing across components, repos, lanes, or external consumers**, add a **standing mechanical drift check** (a CI/script fitness function, mechanics owned by `testing-strategy`); a tiny single-repo doc barely more than a local lockfile can use a lighter local script or defer the gate.
  - **The gate is only decidable if the doc TYPES each value** — otherwise it cannot tell intentional lag from staleness and will flag legitimate `stable` lag. A *verified-combination pin* (e.g. `stable`) MAY lag head by design — **not drift**; a *"current / latest / tracks-head" claim* MUST equal reality — staleness there **is** drift. Each value declares its authority target (which component `VERSION` / conformance pin it must match). Prefer **deriving** the "current/tracks" claims over hand-writing them; a hand-maintained current value without a declared type/authority is itself a finding.
  - **The check resolves each pin against its declared authority and emits explicit verdicts** — `match` / `drift` / `unresolvable` (deleted-or-moved ref, auth/network) / `non-immutable-pin` (a branch where a tag/SHA was required) / `circular-authority` (the "authority" is the same doc being checked). Only `drift` and `non-immutable-pin` block; `unresolvable` is a flake/triage signal, **not** auto-drift (transport failure must not block a good release); `circular-authority` **fails loudly**, never self-passes.

  This is the firing mechanism for the layered model: "must not copy the pin" removes copies; the typed drift check catches the remaining current-state layer mechanically instead of by memory.

## "When can the producer drop an old contract version?" (deprecation timing for consumers you don't control)

A consumer whose upgrade you do **not** control synchronously — a store-reviewed mobile app, an externally distributed SDK, a customer-deployed service — does not upgrade on the producer's deploy schedule, so the backward-compatibility hold for its pinned version must key off a **real adoption/telemetry signal** (observed traffic on the old pin, store-adoption metric, consumer ack), not a date the producer picked for convenience. A `stale-after <date>` field is only a **placeholder** until that signal exists: it flags "revisit by here," it does not authorize dropping the old version. Sunsetting on the placeholder date alone — before adoption data shows the lagging consumers have moved — breaks live clients you cannot hotfix. Hold the old version, instrument old-pin usage, and let the signal (not the calendar) close the window. But lack of a signal is **not** a license for an unowned indefinite hold either: if no reliable adoption signal can be obtained, sunset still proceeds through an explicit EOL decision — documented consumer notice/outreach, a minimum support window, owner risk acceptance, a rollback/kill-switch plan, and the best available proxy evidence (store-release/adoption, SDK version telemetry, customer ack, or a contractual deprecation policy). testing-strategy's "approved compatibility window" owns the contract-test side, this owns the rollout-timing decision.
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall