Release Notes Convention
Purpose
A release note is the QA execution contract for one production release.
Every production release must ship with one release note that tells QA:
- what changed,
- what to sanity test,
- what critical flows are still expected to work,
- and who owns final signoff.
When Release Notes Are Required
- Required for every production deployment.
- Required for hotfixes and rollback-forward releases.
- Optional for non-production deployments.
If multiple deploy steps are part of one release window, publish one note and update it as scope changes.
File Location and Naming
Location: docs/core/testing-and-qa/releases/notes/
File name: YYYY-MM-DD-prod-<short-slug>.md
One release note file per production release.
Examples:
2026-05-20-prod-auth-session-fix.md2026-05-22-prod-content-publish-hotfix.md
Required Metadata
Each release note must include these fields at the top:
| Field | Required | Description |
|---|---|---|
| Release Date | Yes | Date of production release |
| Release Window | Yes | Planned time window (with timezone) |
| Environment | Yes | Always Production |
| Engineering Owner | Yes | Accountable engineer for release content |
| QA Owner | Yes | Accountable QA reviewer |
| Status | Yes | Draft, In QA, Passed, or Blocked |
Severity Model
Use these severity levels for QA execution priority.
| Severity | Meaning | QA Execution Order |
|---|---|---|
| Critical | Core journeys or high-risk changes that can block release | First |
| High | Important flows with user impact but not immediate release blockers | Second |
| Medium | Lower-risk checks that still need confidence coverage | Third |
Required Sections (In Order)
- Release Summary
- Risk Snapshot
- Change-Specific Manual Sanity Checks
- Unaffected Critical Flows to Re-Validate
- Known Risks and Deferrals
- QA Signoff
- Engineering Signoff
⚠️ Warning
Do not remove any required section.
Check Item Contract
Each manual check item must include:
- Severity (Critical, High, or Medium)
- Area or feature
- Preconditions (if any)
- Steps (short and actionable)
- Expected result
- Evidence to capture
- Result (Pass, Fail, or Blocked)
Target detail level: 3 to 5 steps per impacted area.
Writing Rules (QA Point of View)
- Use user-facing language, not code-level implementation details.
- Focus on what QA should do and what must happen.
- Keep checks concise and executable without extra tribal context.
- Include changed behavior plus unaffected critical flows that should be re-validated.
- Avoid file paths, function names, and internal refactor details.
- Keep one line per bullet where possible.
Signoff Rules
- QA signoff is mandatory before release is considered complete.
- Any failed Critical check sets release status to Blocked until resolved or explicitly waived.
- Engineering signoff must include rollback notes when risk is non-trivial.
Related
- Template: Release Note Template
- Workflow: Releases Overview
- Storage rules: Release Notes Folder Guide