Release Engineering

Release Engineering

This pack's native-safe metadata marks it as surface: planned-adjacent, primary-route: false, and support-tier: planned.

Use this pack as a bounded planned adjacent, non-primary surface after ../../reference/routing-matrix.md points here for versioned delivery work: SemVer policy, changelog and release-note flow, package or artifact publication, prerelease versus stable boundaries, promotion decisions, and rollback framing around shipped changes.

This pack covers the versioned artifact and release communication surface once the dominant route is already chosen, not runtime orchestration. It is not the first-pass place to discover adjacent-pack routing, helper fit, or support posture, so send that work back to ../../reference/routing-matrix.md. Use the overlays in reference/versioning-changelog-publishing.md and reference/rollback-promotion-feature-flags.md when version policy, publication flow, promotion stages, kill switches, or release-safety framing dominates the task, and keep live deploy mechanics in devops-platform.

Core focus

• Define versioning policy and compatibility expectations before the release train starts moving.
• Make changelog and release-note flow user-impact oriented instead of commit-log oriented.
• Treat artifact publication and channel promotion as controlled release surfaces with explicit states.
• Plan rollback, staged promotion, and feature-flag behavior before declaring a release stable.
• Keep release evidence, docs, and QA handoff aligned around the same versioned unit.

Shared release standards

• Keep one clear source of truth for version numbers, tags, release metadata, and published artifact identity.
• Use immutable release units and explicit channels for draft, prerelease, and stable states instead of mutating one moving target.
• Apply SemVer or the repo's declared variant consistently so compatibility promises stay readable to downstream users.
• Make changelog and release-note entries explain user-visible impact, required actions, and rollback-relevant constraints.
• Treat promotion, rollback, and feature-flag decisions as part of release design, not as after-the-fact operational improvisation.

Default workflow

1. Read ../../reference/routing-matrix.md first so planned-adjacent routing, helper discovery, and non-primary positioning come from the matrix instead of this pack.
2. Inspect the release unit, version source of truth, publication targets, compatibility window, and rollback constraints.
3. Choose the relevant overlay: reference/versioning-changelog-publishing.md for version policy and artifact publication, or reference/rollback-promotion-feature-flags.md for staged exposure and recovery framing.
4. Define the version change, changelog shape, publication plan, and release channel before automation starts cutting artifacts.
5. Align promotion criteria, rollback paths, and flag behavior with QA evidence and documentation updates.
6. Run review-work after substantial release-engineering changes.

Collaboration in this repo

• Use Explore before editing so version files, changelog structure, release notes, and publication scripts match local conventions.
• Use Librarian or Context7 when registry, packaging, or versioning-tool details need a source-of-truth check.
• Treat this pack as planned, adjacent, and non-primary for routing discovery, and defer helper selection or adjacent-pack choice back to ../../reference/routing-matrix.md.
• Pair with documentation-sdk when release notes, upgrade guides, or API reference updates must ship with the cut.
• Pair with qa-validation when promotion or rollback thresholds depend on explicit release-readiness evidence.
• Pair with devops-platform when publication feeds deployment handoff or environment promotion, while keeping runtime operations outside this pack.

Overlays

• reference/versioning-changelog-publishing.md for SemVer policy, changelog shape, immutable artifacts, and publication channels.
• reference/rollback-promotion-feature-flags.md for release stages, rollback criteria, feature-flag exposure, and kill-switch framing.

Guardrails

• Do not let this pack become general deployment or runtime-operations authority.
• Do not blur draft, prerelease, and stable states or hide rollback assumptions behind automation.
• Do not let this planned adjacent pack read like the primary routing or support surface for release work.
• Do not publish mutable or undocumented release units.