Changelog Have a suggestion?

Changelog (or release notes) helps developers to stay up to date with project changes and helps migrating to new versions.

CHANGELOG.md
How to
Best practices

How to

1. Create a changelog

  • Create a changelog file (such as CHANGELOG.md) or use GitHub releases. File is recommended if users can interact with your project without visiting GitHub (e.g. npm packages).
  • Introduce a section for each release. Include version, release date, and a list of grouped changes: new features, bug fixes, breaking changes.

Resources:  Keep a changelog,  Why and How Should You Write a Good Change Log

1. Create a changelog

2. Separate large releases

  • When some release includes too many changes you can highlight the key changes in the changelog and link to a separate document, describing everything in details (say a blog post)
  • When most releases are large consider splitting the changelog into multiple files

Examples:  Babel,  Django

3. Automate changelog generation

  • Unless you have a large project or a strict format of commit messages, automation may not be a good idea
  • Changelogs are created for humans and communicating important changes well is a manual work, not a dump of commit messages
  • However, with some effort and discipline you can produce great changelogs

Resources:  List of alternatives to github-changelog-generator,  Keep a changelog tools,  How we solved GitLab's CHANGELOG conflict crisis

3. Automate changelog generation

Best practices

1. Keep changelog up to date

Create a changelog entry for every version. The latest version should come first.

2. Show version and date in release heading

  • Include a link to the list of code changes.
  • Show release date next to each version.
  • Don't use regional date formats, prefer the standard ISO format YYYY-MM-DD or use month names to avoid confusion.

Examples:  keep a changelog

2. Show version and date in release heading

3. Group similar changes by category

This improves changelog readability and makes it easy to find relevant changes. There are multiple ways to categorize changes - choose whatever suits your project best. Here are the most common categories:

  • Change types - bug fixes (aka fixed), new features (aka added, new), improvements (aka changed, updated), deprecations (aka deprecated), removed
  • Breaking changes (aka Migration)
  • Documentation (aka Docs)
  • Important system components (e.g. Core, Plugins, individual packages)
  • Significant new features
  • Internal (aka Development) - for project developers
  • Security

When grouping changes doesn't make sense you can label them a prefix, for example '[docs] ...'

Examples:  Chart.js,  React,  Bootstrap

4. Highlight breaking changes and deprecations

  • Major releases that require user actions in order to upgrade must be clearly stated in the changelog
  • Describe breaking changes and migration steps in a separate section at the beginning or the end of release notes
  • List deprecated features, that will be removed in future releases

Examples:  Chart.js

5. Communicate relevant changes

  • Focus on changes that impact users, don't list internal changes without a reason (such as dependencies update)
  • Include relevant links to issues/pull requests/commits, documentation or elsewhere inside changelog items
  • Credit external contributors

Resources:  What makes a good changelog?,  Autolinked references and URLs on GitHub

6. Show unreleased changes

  • Use "Unreleased" section to help users and project developers to stay informed on the upcoming changes. It also helps you at release time - just move changes from this section into the new version section.
  • Provide link to the list of commits since the last release

Examples:  Bulma

6. Show unreleased changes