# Release Checklist: [Product name] [vX.Y.Z]

> Release checklist for a software version: metadata, then task lists for
> planning, code freeze, QA, security, documentation, packaging and
> signing, the release itself, post-release checks and rollback readiness,
> followed by sign-offs and communication. Copy it once per release and
> tick items as they are done. Replace every `[bracketed]` value and every
> line marked *Example*.

<!--
Guidance: How to use this template
- Create a fresh copy for each release (for example as an issue or in
  docs/releases/vX.Y.Z.md) so the history of who checked what is kept.
- Every item needs evidence: a link to a CI run, a report or a ticket.
  A ticked box with no link is a claim, not a check.
- Remove items that never apply to your product once, in the master copy,
  instead of skipping them silently each time.
- If an item cannot be completed, do not tick it: record the exception in
  the waiver table with the approver's name.
-->

| Field | Value |
|---|---|
| Product / component | [Product name] |
| Version | [vX.Y.Z] |
| Release type | [Major / Minor / Patch / Hotfix] |
| Release manager | [@name] |
| Planned release date | YYYY-MM-DD |
| Code freeze date | YYYY-MM-DD |
| Release branch / tag | [release/X.Y] / [vX.Y.Z] |
| Tracking issue | [link] |
| Status | [Planning / Frozen / In QA / Released / Rolled back] |

## 1. Planning

<!-- Guidance: Agree scope, dates and owners before work is frozen. The main mistake is a release whose content nobody can list. -->

- [ ] Scope agreed: list of issues and PRs included, linked from the tracking issue.
- [ ] Version number chosen according to [Semantic Versioning]; breaking changes justify a major bump.
- [ ] Release dates confirmed with [product, support, operations].
- [ ] Owners assigned for QA, security, documentation and communication.
- [ ] Dependencies on other teams or services identified, with their release dates.
- [ ] Known risks recorded, for example: *Example:* database migration on a 40 GB table.

## 2. Code freeze

<!-- Guidance: After freeze only fixes for release blockers go in. Define who can approve an exception. -->

- [ ] Release branch `[release/X.Y]` created from `[main]` at commit `[sha]`.
- [ ] Branch protection applied; merges need [release manager] approval.
- [ ] All included PRs merged; nothing in review is labelled for this release.
- [ ] Feature flags for unfinished work are off by default.
- [ ] Version number updated in [package.json / pyproject.toml / build files].
- [ ] Dependency lockfile committed and unchanged since freeze, unless for a security fix.

## 3. Quality assurance

<!-- Guidance: Link each item to the run or report. State the exit criteria up front, for example "no open P1 bugs, at most 3 P2 with workarounds". -->

- [ ] CI green on the release branch: unit, integration and end-to-end suites ([CI run link]).
- [ ] Test coverage not below [80%] on changed modules.
- [ ] Regression test pass on supported platforms: [browsers / OS versions / devices].
- [ ] Upgrade test from the previous [two] versions, including data migration.
- [ ] Performance check against baseline: *Example:* p95 API latency within 10% of v2.3.
- [ ] Accessibility check of changed screens ([WCAG 2.2 AA]).
- [ ] Exit criteria met: [no open P1 or P2 defects / agreed exceptions listed below].

## 4. Security

<!-- Guidance: Security checks run on the exact artefacts that will ship. Record accepted risks with an owner and an expiry. -->

- [ ] Dependency audit clean or exceptions approved ([tool, report link]).
- [ ] Static analysis (SAST) findings triaged; no new high or critical issues.
- [ ] Secrets scan clean on the release branch.
- [ ] Container or OS image scan clean for high and critical CVEs.
- [ ] Security review completed for changes to authentication, authorization, data handling or cryptography.
- [ ] Software bill of materials (SBOM) generated in [CycloneDX / SPDX] format.

## 5. Documentation

<!-- Guidance: Users read docs before code. Breaking changes need a migration guide, not just a changelog line. -->

- [ ] CHANGELOG updated with Added, Changed, Deprecated, Removed, Fixed and Security entries.
- [ ] Release notes drafted for users, in plain language.
- [ ] Migration guide written for every breaking change, with before and after examples.
- [ ] API reference and configuration docs regenerated.
- [ ] Support and operations teams briefed on new behaviour and known issues.

## 6. Packaging and signing

<!-- Guidance: Build once, from a clean environment, and promote the same artefact through environments. Never rebuild for production. -->

- [ ] Artefacts built by CI from tag `[vX.Y.Z]`, not on a developer machine.
- [ ] Builds are reproducible or the build environment is recorded.
- [ ] Artefacts signed ([Sigstore cosign / GPG / platform code signing]) and signatures verified.
- [ ] Checksums (SHA-256) published alongside artefacts.
- [ ] Build provenance attestation generated, for example [SLSA level 2].
- [ ] Package metadata correct: version, licence, homepage, minimum runtime.

## 7. Release

<!-- Guidance: The steps in order, with the person running each. Use a staged rollout when the platform allows it. -->

- [ ] Go/no-go meeting held; decision recorded in the sign-off table.
- [ ] Database migrations applied and verified ([migration log link]).
- [ ] Tag `[vX.Y.Z]` pushed and GitHub release published with notes and checksums.
- [ ] Packages published to [npm / PyPI / container registry / app stores].
- [ ] Deployment rolled out in stages: [5%] then [25%] then [100%], with health checks between stages.
- [ ] Status page or maintenance notice updated, if applicable.

## 8. Post-release

<!-- Guidance: Watch the release for an agreed period. Define the signals and thresholds that would trigger a rollback. -->

- [ ] Monitoring watched for [24 hours]: error rate, latency, crash rate, key business metrics.
- [ ] Smoke tests pass in production ([run link]).
- [ ] Support queue reviewed for new issues linked to the release.
- [ ] Release branch merged back to `[main]` where needed.
- [ ] Milestone closed and unfinished items moved to the next release.
- [ ] Retrospective scheduled for releases that had incidents or waivers.

## 9. Rollback readiness

<!-- Guidance: Decide how to undo the release before you ship it. Test the rollback, not just the rollout. -->

Rollback trigger: *Example:* error rate above 2% for 10 minutes, or any
data-integrity defect. Decision owner: [@name].

- [ ] Previous version artefacts available and deployable.
- [ ] Rollback procedure documented in [runbook link] and tested in staging.
- [ ] Migrations are backward compatible, or a down migration is tested.
- [ ] Feature flags allow disabling new features without redeploying.
- [ ] Estimated rollback time: [minutes].

## 10. Waivers

<!-- Guidance: Any unticked item that does not block the release must appear here with a reason and an approver. -->

| Item | Reason | Risk | Approved by | Follow-up ticket |
|---|---|---|---|---|
| *Example:* 3.4 Performance check | Load environment unavailable | Low, patch touches no hot paths | @eng-lead | [OPS-412] |
| [Item] | [Reason] | [Risk] | [@name] | [link] |

## 11. Sign-offs

<!-- Guidance: One accountable person per area. Sign-off means "I checked the evidence", not "my team is done". -->

| Area | Name | Decision | Date |
|---|---|---|---|
| Engineering | [@name] | [Go / No-go] | YYYY-MM-DD |
| QA | [@name] | [Go / No-go] | YYYY-MM-DD |
| Security | [@name] | [Go / No-go] | YYYY-MM-DD |
| Product | [@name] | [Go / No-go] | YYYY-MM-DD |
| Operations / SRE | [@name] | [Go / No-go] | YYYY-MM-DD |

## 12. Communication

<!-- Guidance: Who hears what, when and through which channel. Internal teams hear before customers. -->

| Audience | Message | Channel | Owner | When |
|---|---|---|---|---|
| Internal teams | Release scope and timing | [#releases] | [@name] | T-2 days |
| Support | Known issues and FAQ | [Support wiki] | [@name] | T-1 day |
| Customers | Release notes | [Blog / email / in-app] | [@name] | Release day |
| Integrators | Breaking changes and migration guide | [Developer newsletter] | [@name] | T-14 days for majors |

## Standard and licence note

Based on common industry practice for software release management,
including Semantic Versioning, Keep a Changelog style entries and supply
chain practices such as SBOMs and signed artefacts. Original text written
for this collection. Template licence: MIT.