Release Notes и чек-листы

Updated Jul 2026

Документы, связывающие разработку и развёртывание

Документация релиза служит двум целям: она направляет команду через процесс развёртывания и сообщает всем, кому нужно знать, что изменилось. Плохая документация релиза приводит к пропущенным шагам верификации, клиентам, удивлённым изменениями, и командам поддержки, застигнутым врасплох новым поведением. Хорошая документация релиза делает развёртывания рутинными и предсказуемыми, даже когда изменения значительны.

Написание Release Notes с позиции QA

QA-инженеры привносят уникальную перспективу в release notes, потому что знают, что было реально протестировано, какие граничные случаи существуют, что всё ещё рискованно и какие известные проблемы остаются. Эта информация бесценна как для внутренних команд, так и для внешних пользователей.

Release Notes для внутренних инженерных команд

Внутренние release notes фокусируются на том, что изменилось, что было протестировано и на что обращать внимание.

Шаблон:

# 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 для клиентской коммуникации

Клиентские release notes короче, нетехничны и фокусируются на выгодах.

Шаблон:

# 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.

Ключевые отличия от внутренних заметок:

Чек-листы развёртывания

Чек-листы развёртывания предотвращают моменты «я забыл...», которые вызывают сбои. Они превращают сложный, подверженный ошибкам процесс в повторяемую последовательность проверяемых шагов.

Чек-лист перед развёртыванием

## 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: 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: 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

Совещание go/no-go — это финальная контрольная точка перед развёртыванием. Документация для этого совещания должна дать лицам, принимающим решения, всё необходимое для принятия уверенного решения за 15 минут.

Шаблон Go/No-Go

# 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 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

Журналы изменений и истории версий

Журнал изменений отслеживает каждый релиз со временем. Он служит историческим справочником для отладки («когда изменилось это поведение?»), поддержки клиентов («в какой версии появилась эта функция?») и аудита.

Формат журнала изменений (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)

Соглашения (из keepachangelog.com):

• Added для новых функций
• Changed для изменений существующей функциональности
• Deprecated для функций, которые будут удалены
• Removed для удалённых функций
• Fixed для исправлений багов
• Security для исправлений уязвимостей

Написание для различных аудиторий

Один и тот же релиз порождает различную документацию для различных аудиторий.

Практическое упражнение

1. Напишите release notes для вашего последнего развёртывания, используя оба шаблона — внутренний и клиентский
2. Создайте чек-лист развёртывания для процесса развёртывания вашей команды (перед развёртыванием, развёртывание, после развёртывания)
3. Напишите шаблон go/no-go и заполните его данными из недавнего релиза
4. Задокументируйте план отката для вашего следующего релиза, включая конкретные команды и шаги верификации
5. Проведите аудит журнала изменений вашей команды. Актуален ли он? Следует ли он единому формату? Предложите улучшения.