Changelog Style Guide
How we write release notes that users actually read — structure, tone, and the Meridian voice.
Keep the first line punchy
Every changelog entry starts with a one-line summary in bold. Users scan — give them the headline immediately. Example: “Auto-update now resumes after sleep without a restart.”
Group by impact
Three sections, always in this order: New, Fixed, Improved. If a section is empty, omit it — never write “Nothing this week.”
Write like a human
No “resolved an issue where” — say what broke and what we did. Use contractions. Address the user directly: “You can now” beats “Users are now able to.”
Link to docs when it helps
If a change needs a longer explanation, drop a docs link instead of bloating the changelog. One link per entry max.
Version format
Semantic: MAJOR.MINOR.PATCH. Prefix with v. Date in ISO format below the version heading. Example: v2.4.1 — 2026-01-17.
Emoji with restraint
One emoji per entry, at the start of the bold summary line. Use the standard set: ✨ new, 🐛 fixed, ⚡ improved. No emoji in section headers.
This guide is part of the Meridian docs. Follow it for every release — consistency builds trust.