Changelog

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:

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:

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

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:

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

Apply this and many other checklists to your project