QA’s Role in Release Notes
Release notes are not just a developer task. QA plays a critical role by providing the quality perspective: what was tested, what bugs were fixed and verified, what known issues remain, and what workarounds exist.
Release Note Sections
New Features and Changes
QA verifies that new features work as described. Flag any discrepancies between the described feature and actual behavior.
Bug Fixes
List bugs fixed in this release. QA should verify every listed fix and confirm the resolution.
Format:
- Fixed: Login timeout increased from 30s to 60s for slow connections [BUG-234]
- Fixed: Cart total calculation error when applying percentage-based coupons [BUG-256]
- Fixed: Profile image upload failing for PNG files larger than 5MB [BUG-278]
Known Issues
Bugs that are shipping with this release intentionally. QA documents these with workarounds.
Known Issues:
- Search results may take up to 10 seconds on first query after deployment.
Workaround: Subsequent searches perform normally.
Target fix: v3.6.0
- PDF export may show incorrect fonts on Windows when custom fonts are not installed.
Workaround: Install the "Inter" font family from Google Fonts.
Target fix: v3.6.0
Breaking Changes
Changes that may break existing integrations or workflows. QA helps identify these through regression testing.
Testing Scope
Internal section documenting what was tested for this release:
- Test execution summary (pass rate, coverage)
- Areas with focused testing
- Areas with limited testing (and why)
Internal vs External Release Notes
| Aspect | Internal | External |
|---|---|---|
| Audience | Dev, QA, support, PM | End users, customers |
| Technical detail | High (API changes, configs) | Low (user-facing changes) |
| Known issues | Full list with root causes | User-affecting issues with workarounds |
| Bug references | Jira IDs included | No internal references |
| Testing scope | Included | Not included |
Exercise: Write Release Notes
Write both internal and external release notes for an e-commerce platform release v3.5.0 that includes: new wishlist feature, redesigned checkout flow, 15 bug fixes (3 critical), 4 known issues, and a breaking API change in the product search endpoint.
Solution
External Release Notes — v3.5.0: New Features: Wishlists (save products for later, share with friends). Redesigned checkout (faster, fewer steps, saved payment methods). Bug Fixes: Fixed payment declined errors for certain Visa cards. Fixed cart losing items on page refresh. Fixed incorrect tax calculation for international orders. Known Issues: Wishlist sharing via email may be delayed up to 5 minutes. Checkout “Back” button does not restore the previous step on Safari (use browser back button as workaround).
Internal Release Notes — v3.5.0:
Testing: 450 tests executed, 95.3% pass rate. Checkout flow received intensive testing (120 test cases). Wishlist tested across 8 browser/device combinations.
Bug Fixes: 15 total (3 critical, 5 major, 4 minor, 3 trivial). All verified in staging.
Known Issues: 4 total — 2 user-facing documented above, plus: Admin bulk export times out for >10K products (BUG-445, deferred to v3.6). Search indexing delay up to 30 minutes after product updates (BUG-451, performance team investigating).
Breaking Change: GET /api/v2/products/search now requires page_size parameter (default removed). All API consumers must update by v3.6.0.
Key Takeaways
- QA provides known issues, bug fix verifications, and testing scope for release notes
- Always include workarounds for known issues to reduce support tickets
- Write separate internal (detailed) and external (user-friendly) versions
- Verify every bug fix listed before including it in release notes
- Document breaking changes clearly with migration instructions