Release Notes and Checklists

The Documents That Bridge Development and Deployment

Release documentation serves two purposes: it guides the team through the deployment process, and it communicates what changed to everyone who needs to know. Bad release documentation leads to missed verification steps, customers surprised by changes, and support teams blindsided by new behavior. Good release documentation makes deployments routine and predictable, even when the changes are significant.

Writing Release Notes from a QA Perspective

QA engineers bring a unique perspective to release notes because they know what was actually tested, what edge cases exist, what is still risky, and what known issues remain. This information is invaluable to both internal teams and external users.

Release Notes for Internal Engineering Teams

Internal release notes focus on what changed, what was tested, and what to watch for.

Template:

# Release Notes: v2.4.1 -- 2026-02-14

## Summary
Brief one-paragraph summary of what this release contains.

## Changes
### New Features
- **Multi-currency checkout** (SHOP-1234): Users can now pay in EUR, GBP, and JPY
  in addition to USD. Exchange rates are fetched from the Forex API at checkout time.

### Bug Fixes
- **Cart total rounding error** (SHOP-1189): Fixed an issue where carts with 3+
  items and a percentage discount could show a total 1 cent off due to floating
  point rounding. Root cause: rounding was applied per-item instead of to the total.

### Improvements
- **Search indexing performance** (SHOP-1201): Reduced product search reindexing
  time from 45 minutes to 12 minutes by switching to batch processing.

## What Was Tested
- Full regression suite (487 tests, all passing)
- Manual testing of multi-currency checkout across 5 currencies, 3 browsers
- Performance testing: checkout p95 latency unchanged at 1.2s
- Security: no new vulnerabilities detected in OWASP ZAP scan

## Known Issues
- **SHOP-1245**: Currency selector does not render correctly on Safari 16.
  Impact: cosmetic only; functionality works. Fix scheduled for v2.4.2.
- **SHOP-1250**: Exchange rate cache TTL is 1 hour; customers may see stale
  rates during high-volatility periods. Monitoring in place.

## Upgrade Notes
- Database migration required: adds `currency` column to `orders` table
  (migration is backward-compatible, no downtime required)
- New environment variable: `FOREX_API_KEY` must be set before deployment
- Redis cache version must be 7.0+ (was 6.x compatible previously)

## Rollback Plan
- If critical issues are discovered, revert to v2.4.0 using the standard
  rollback procedure. The database migration is backward-compatible.
- Rollback does not require downtime.

Release Notes for Customer-Facing Communication

Customer-facing release notes are shorter, non-technical, and focused on benefits.

Template:

# What's New in Version 2.4

## Pay in Your Currency
You can now check out in EUR, GBP, and JPY in addition to USD.
We display the converted total before you confirm your purchase.

## Bug Fixes
- Fixed an issue where cart totals could be off by 1 cent on
  discounted orders

## Known Issues
- The currency selector may not display correctly on Safari 16.
  We are working on a fix.

Key differences from internal notes:

Deployment Checklists

Deployment checklists prevent the "I forgot to..." moments that cause outages. They transform a complex, error-prone process into a repeatable sequence of verifiable steps.

Pre-Deployment Checklist

## Pre-Deployment: v2.4.1

### Code Readiness
- [ ] All PRs merged to release branch
- [ ] Release branch passes CI (link to build: ___)
- [ ] No open Sev-1 or Sev-2 bugs against this release
- [ ] Code freeze confirmed with dev team

### Environment Readiness
- [ ] Staging environment updated to match production config
- [ ] Database migration tested on staging
- [ ] New environment variables set in production config (not yet active)
- [ ] Feature flags configured (new features off by default)

### Testing Readiness
- [ ] Full regression suite passed on staging (link to report: ___)
- [ ] Performance tests passed (link to report: ___)
- [ ] Security scan completed (link to report: ___)
- [ ] Smoke test suite ready for post-deployment

### Stakeholder Readiness
- [ ] Release notes shared with support team
- [ ] Customer communication scheduled (if applicable)
- [ ] Go/no-go meeting scheduled for [date/time]
- [ ] On-call engineer confirmed for deployment window

Deployment Checklist

## Deployment: v2.4.1

### Deployment Steps
- [ ] Announce deployment start in #engineering channel
- [ ] Set status page to "Maintenance" (if required)
- [ ] Run database migration (estimated time: 5 minutes)
- [ ] Deploy application servers (rolling deployment, zero downtime)
- [ ] Verify deployment version: curl api.example.com/health
- [ ] Enable feature flags for internal users only
- [ ] Run smoke test suite (link: ___)
- [ ] Monitor error rates for 15 minutes (dashboard: ___)
- [ ] Enable feature flags for all users
- [ ] Update status page to "Operational"
- [ ] Announce deployment complete in #engineering channel

### Deployment Contacts
| Role | Person | Contact |
|---|---|---|
| Deploy lead | Alice | @alice (Slack) |
| On-call engineer | Bob | @bob (Slack), +1-555-0123 |
| QA verification | Carol | @carol (Slack) |
| Rollback decision | Dave (Engineering Manager) | @dave (Slack) |

Post-Deployment Verification Checklist

## Post-Deployment Verification: v2.4.1

### Smoke Tests (automated)
- [ ] Homepage loads (< 2s)
- [ ] User can log in
- [ ] User can search products
- [ ] User can add to cart
- [ ] User can check out (test account)
- [ ] API health endpoint returns 200

### Manual Verification
- [ ] New multi-currency feature works in production
  - [ ] EUR checkout (test account)
  - [ ] GBP checkout (test account)
  - [ ] JPY checkout (test account)
- [ ] Cart total rounding fix verified with discount codes
- [ ] Existing functionality spot-check: [list critical paths]

### Monitoring
- [ ] Error rate below threshold (< 0.5%)
- [ ] p95 latency below threshold (< 2s)
- [ ] No new error types in logs
- [ ] Database connection pool stable
- [ ] Memory and CPU within normal range
- [ ] Monitor for 1 hour after deployment

Go/No-Go Documentation

The go/no-go meeting is the final checkpoint before deployment. The documentation for this meeting must give decision-makers everything they need to make a confident decision in 15 minutes.

Go/No-Go Template

# Go/No-Go: v2.4.1 Release
Date: 2026-02-14
Decision-makers: [Engineering Manager], [Product Manager], [QA Lead]

## Release Summary
One sentence describing what this release contains.

## Quality Status

| Category | Status | Details |
|---|---|---|
| Automated tests | PASS | 487/487 passed, 0 flaky |
| Manual testing | PASS | 34 test cases, all passed |
| Performance | PASS | p95 latency: 1.2s (target: < 2s) |
| Security | PASS | No new vulnerabilities |
| Open Sev-1 bugs | 0 | -- |
| Open Sev-2 bugs | 0 | -- |
| Known issues | 2 | See below |

## Known Issues

| Issue | Severity | Impact | Mitigation |
|---|---|---|---|
| SHOP-1245: Safari 16 CSS | Low | Cosmetic only | Fix in v2.4.2 |
| SHOP-1250: Cache TTL | Low | Stale rates possible | Monitoring in place |

## Risk Assessment

| Risk | Likelihood | Impact | Mitigation |
|---|---|---|---|
| Forex API downtime | Low | Checkout fails for non-USD | Fallback to USD with warning |
| Database migration failure | Very Low | Deployment blocked | Migration tested on staging; rollback script ready |

## Rollback Plan
How to roll back, estimated time, and who is responsible.

## Recommendation
GO / NO-GO with rationale.

Rollback Plans

Every release should have a documented rollback plan before deployment begins. The worst time to figure out how to roll back is during an incident.

Rollback Plan Template

# Rollback Plan: v2.4.1

## Rollback Trigger
Conditions that trigger a rollback:
- Error rate exceeds 2% for more than 5 minutes
- p95 latency exceeds 5s for more than 5 minutes
- Any data corruption detected
- Critical functionality broken (login, checkout, payment)

## Rollback Decision
Who can authorize a rollback: [Engineering Manager] or [On-call Lead]

## Rollback Steps
1. Announce rollback in #engineering channel
2. Set status page to "Investigating"
3. Revert application to v2.4.0: [command or procedure]
4. Verify rollback: run smoke test suite
5. Assess database migration:
   - v2.4.1 migration IS backward-compatible: no database rollback needed
   - If database rollback IS needed: [procedure]
6. Update status page
7. Notify stakeholders

## Rollback Timeline
- Estimated time to rollback: 10 minutes
- Estimated time to verify: 15 minutes
- Total estimated downtime: 0 (rolling deployment)

## Post-Rollback Actions
- [ ] File incident report
- [ ] Schedule post-mortem
- [ ] Assess fix and re-release timeline

Change Logs and Version Histories

A change log tracks every release over time. It serves as a historical record for debugging ("when did this behavior change?"), customer support ("which version introduced this feature?"), and auditing.

Change Log Format (Keep a Changelog)

# Changelog

## [2.4.1] -- 2026-02-14
### Added
- Multi-currency checkout (EUR, GBP, JPY)
### Fixed
- Cart total rounding error on discounted orders (SHOP-1189)
### Changed
- Search reindexing performance improved (45min → 12min)

## [2.4.0] -- 2026-01-31
### Added
- Wishlist sharing via link
### Fixed
- Password reset email not sent for accounts with + in email address
### Removed
- Legacy v1 API endpoints (deprecated since v2.0)

Conventions (from keepachangelog.com):

• Added for new features
• Changed for changes to existing functionality
• Deprecated for features that will be removed
• Removed for features that were removed
• Fixed for bug fixes
• Security for vulnerability fixes

Writing for Different Audiences

The same release produces different documentation for different audiences.

Hands-On Exercise

1. Write release notes for your most recent deployment using both the internal and customer-facing templates
2. Create a deployment checklist for your team's deployment process (pre-deployment, deployment, post-deployment)
3. Write a go/no-go template and populate it with data from a recent release
4. Document a rollback plan for your next release, including specific commands and verification steps
5. Audit your team's change log. Is it up to date? Does it follow a consistent format? Propose improvements.