9 min read • Guide 730 of 877
Release Notes Best Practices
Good release notes inform and excite users. GitScrum helps track changes and generate release notes from completed tasks, ensuring nothing is missed and communication is clear.
Release Notes Structure
Anatomy
RELEASE NOTES STRUCTURE:
┌─────────────────────────────────────────────────────────────┐
│ │
│ VERSION 2.5.0 - January 15, 2024 │
│ │
│ ═══════════════════════════════════════════════════════════ │
│ │
│ HIGHLIGHTS (Top 1-3 changes): │
│ The most important thing users should know │
│ │
│ ✨ NEW FEATURES: │
│ Things users can now do that they couldn't before │
│ │
│ 🔧 IMPROVEMENTS: │
│ Existing features that got better │
│ │
│ 🐛 BUG FIXES: │
│ Things that were broken and are now fixed │
│ │
│ ⚠️ BREAKING CHANGES: │
│ Changes that require user action │
│ │
│ 📝 DEPRECATIONS: │
│ Features being removed in future versions │
│ │
│ 🔍 KNOWN ISSUES: │
│ Problems we're aware of │
│ │
│ ═══════════════════════════════════════════════════════════ │
│ │
│ ORDERING: │
│ Most important first within each section │
│ User-facing before internal changes │
└─────────────────────────────────────────────────────────────┘
Example Release Notes
WELL-WRITTEN RELEASE NOTES:
┌─────────────────────────────────────────────────────────────┐
│ │
│ ## v2.5.0 - January 15, 2024 │
│ │
│ ### Highlights │
│ │
│ 📱 **Mobile App Launch** - Manage your projects on the go │
│ with our new iOS and Android apps. Track tasks, update │
│ status, and stay connected with your team anywhere. │
│ │
│ ### New Features │
│ │
│ - **Mobile apps** - Native iOS and Android applications │
│ with full task management capabilities │
│ - **Dark mode** - Easy on the eyes with system-wide dark │
│ mode support │
│ - **Keyboard shortcuts** - Power users can now use Cmd+K │
│ for quick navigation │
│ │
│ ### Improvements │
│ │
│ - Dashboard loads 40% faster with optimized queries │
│ - Task search now includes comments and attachments │
│ - Notification preferences are more granular │
│ │
│ ### Bug Fixes │
│ │
│ - Fixed: Due dates showing in wrong timezone for some │
│ users │
│ - Fixed: Drag-and-drop not working on Firefox │
│ - Fixed: Email notifications delayed by up to 1 hour │
│ │
│ ### Breaking Changes │
│ │
│ - API v1 is now deprecated. Please migrate to v2 by │
│ March 1, 2024. [Migration guide] │
│ │
│ [Download] [Documentation] [Feedback] │
└─────────────────────────────────────────────────────────────┘
Writing Guidelines
User-Focused Language
WRITING FOR USERS:
┌─────────────────────────────────────────────────────────────┐
│ │
│ ❌ DEVELOPER-SPEAK: │
│ │
│ "Refactored authentication middleware to use │
│ JWT tokens with RS256 encryption" │
│ │
│ ✅ USER-SPEAK: │
│ │
│ "Improved security: Login sessions are now more │
│ secure and stay active across browser tabs" │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ ❌ DEVELOPER-SPEAK: │
│ │
│ "Fixed N+1 query issue in projects controller │
│ causing slow page loads" │
│ │
│ ✅ USER-SPEAK: │
│ │
│ "Project dashboard now loads 40% faster" │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ ❌ DEVELOPER-SPEAK: │
│ │
│ "Migrated from Moment.js to date-fns for │
│ better tree-shaking and bundle size" │
│ │
│ ✅ USER-SPEAK: │
│ │
│ [Don't mention - internal change with no user impact] │
│ │
│ RULE: If users don't notice it, it doesn't need to be │
│ in user-facing release notes │
└─────────────────────────────────────────────────────────────┘
Clear Formatting
FORMATTING BEST PRACTICES:
┌─────────────────────────────────────────────────────────────┐
│ │
│ USE ACTION-ORIENTED LANGUAGE: │
│ ❌ "The ability to export has been added" │
│ ✅ "Export your data to CSV or PDF" │
│ │
│ LEAD WITH THE BENEFIT: │
│ ❌ "Added a new keyboard shortcut Cmd+K" │
│ ✅ "Navigate faster with Cmd+K quick search" │
│ │
│ BE SPECIFIC: │
│ ❌ "Performance improvements" │
│ ✅ "Dashboard loads 40% faster" │
│ │
│ USE VISUALS: │
│ • Screenshots for UI changes │
│ • GIFs for interactions │
│ • Before/after comparisons │
│ │
│ MAKE IT SCANNABLE: │
│ • Bold the key point │
│ • Use bullets and short paragraphs │
│ • Group related items │
│ • Most important first │
│ │
│ INCLUDE LINKS: │
│ • Documentation for new features │
│ • Migration guides for breaking changes │
│ • Feedback channels │
│ │
│ KEEP IT CONCISE: │
│ • One line per item when possible │
│ • Expand only for major features │
│ • Remove filler words │
└─────────────────────────────────────────────────────────────┘
Content Sources
From GitScrum Tasks
GENERATING NOTES FROM GITSCRUM:
┌─────────────────────────────────────────────────────────────┐
│ │
│ TASK TRACKING FOR RELEASE NOTES: │
│ │
│ For each completed task, capture: │
│ • User-facing summary (separate from technical desc) │
│ • Category (feature/improvement/fix) │
│ • Release target │
│ │
│ EXAMPLE TASK: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ TITLE: Implement dark mode toggle ││
│ │ ││
│ │ DESCRIPTION: [Technical implementation details] ││
│ │ ││
│ │ RELEASE NOTE: "Dark mode - Easy on the eyes with ││
│ │ system-wide dark mode support. Toggle in Settings." ││
│ │ ││
│ │ CATEGORY: Feature ││
│ │ RELEASE: v2.5.0 ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ AUTOMATED CHANGELOG: │
│ │
│ Query: All tasks completed in v2.5.0 │
│ Group by: Category │
│ Sort by: Priority │
│ Output: Formatted release notes │
│ │
│ Then: Human review and polish │
│ Add: Highlights, screenshots, links │
└─────────────────────────────────────────────────────────────┘
Changelog Standards
CONVENTIONAL CHANGELOG:
┌─────────────────────────────────────────────────────────────┐
│ │
│ FORMAT (Keep a Changelog): │
│ │
│ # Changelog │
│ │
│ ## [Unreleased] │
│ ### Added │
│ - Dark mode support │
│ │
│ ## [2.5.0] - 2024-01-15 │
│ ### Added │
│ - Mobile apps for iOS and Android │
│ - Keyboard shortcuts (Cmd+K) │
│ │
│ ### Changed │
│ - Dashboard performance improved 40% │
│ │
│ ### Fixed │
│ - Timezone issue with due dates │
│ │
│ ### Deprecated │
│ - API v1 (use v2 by March 2024) │
│ │
│ ### Removed │
│ - Legacy export format │
│ │
│ ### Security │
│ - Fixed XSS vulnerability in comments │
│ │
│ PRINCIPLES: │
│ • Most recent first │
│ • Human readable │
│ • Linked to releases │
│ • Semantic versioning │
└─────────────────────────────────────────────────────────────┘
Audience Variations
Different Audiences
RELEASE NOTES BY AUDIENCE:
┌─────────────────────────────────────────────────────────────┐
│ │
│ END USERS: │
│ • Focus on what they can do now │
│ • Screenshots and visuals │
│ • No technical jargon │
│ • "How to" links │
│ │
│ Example: │
│ "📱 New: Manage tasks from your phone! Download our │
│ new mobile app from the App Store or Play Store." │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ DEVELOPERS/API USERS: │
│ • Breaking changes prominently │
│ • Migration guides │
│ • New endpoints and parameters │
│ • Code examples │
│ │
│ Example: │
│ "⚠️ Breaking: `GET /tasks` now requires pagination. │
│ Add `?page=1&per_page=50` to your requests. │
│ [Migration guide]" │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ ENTERPRISE ADMINS: │
│ • Security updates prominently │
│ • Compliance features │
│ • Admin control changes │
│ • SSO/SAML updates │
│ │
│ Example: │
│ "🔒 Security: Added SCIM provisioning for automatic │
│ user sync with your identity provider." │
└─────────────────────────────────────────────────────────────┘
Distribution
Communication Channels
RELEASE NOTES DISTRIBUTION:
┌─────────────────────────────────────────────────────────────┐
│ │
│ IN-APP: │
│ • What's new modal on first visit after update │
│ • Changelog link in help menu │
│ • Feature spotlights for major additions │
│ │
│ EMAIL: │
│ • Major releases to all users │
│ • Digest of changes for regular updates │
│ • Targeted emails for feature-specific updates │
│ │
│ WEBSITE: │
│ • Changelog page │
│ • Blog post for major releases │
│ • Documentation updates │
│ │
│ SOCIAL: │
│ • Twitter/X for major features │
│ • LinkedIn for enterprise features │
│ • Dev-focused platforms for API changes │
│ │
│ DEVELOPER CHANNELS: │
│ • GitHub releases │
│ • API changelog │
│ • SDK update notes │
│ │
│ TIMING: │
│ • Release notes ready at launch │
│ • Email within 24 hours │
│ • Blog post within 48 hours │
│ • Social ongoing │
└─────────────────────────────────────────────────────────────┘