Release notes template that doubles as a changelog

When to use it

• Shipping a new version of an app or a library and telling users what changed
• A changelog page or CHANGELOG.md that gets a new entry with every release
• Update emails and in-app announcements for a product release
• Internal releases where support and sales need to know what is new and what is still broken

How to use this template

1. Collect every change

   Start from the diff between the last release and this one, or from the tickets closed since. Put every merged change on a scratch list, however small. Most lines will be cut or combined later; nothing should be forgotten now.

2. Sort by what the user notices

   Move each change into New, Improved or Fixed. Anything that shipped broken goes under Known issues, with a workaround. Anything the user must do goes under Upgrade notes. Delete a section rather than leave it empty.

3. Write the highlights last

   Pick the two or three changes most people will notice and describe what they can now do. The highlights are the part that gets read; the lists below are for the people who need the detail.

4. Publish in the format the audience reads

   Download the .md to add to a CHANGELOG.md or a docs site, or the .docx for an email or a PDF. The structure is the same either way, so one draft serves both.

Write for the user

A diff records what changed in the code. Release notes record what changed for the person using it. That translation is the whole job, and it is the part most release notes skip. Here are four lines from a made-up release, each rewritten as what the user can now do or what no longer goes wrong, and where to find it:

• One line per change. If a line needs two sentences, it is two changes, or it belongs in the highlights.
• Name things as the interface names them. The user looks for "Export", not "the export pipeline".
• Keep the tense consistent. Present tense for what the product does now; past tense only for what was broken.
• Leave out what the user cannot see. Refactors, dependency updates and build changes stay in the commit log, where they belong.
• Be plain in Known issues. A listed bug with a workaround costs less trust than a surprise.

Changelog or release notes?

A changelog is the complete record: one entry per version, usually a Markdown file in the repository that grows at the top. Release notes are the version of that entry written for people: shorter, with highlights, published where users will see it. Keep both from the same list of changes. Write the release notes first, then paste the New, Improved and Fixed sections into the changelog, so the two never disagree.