Blog post: Why and How Should You Write a Good Change Log

jonasbn on September 27, 2018

In this blog post I will give an overview of how I regard change logs, how and why they should be written and structured. Do note that this is ba... [Read Full]
markdown guide

You also need to highlight any breaking changes that come with a major release.

If you release a new major version (first number in semantic versioning), users wishing to upgrade will be viewing the change log to find out if there was a breaking change that affects them.

I generally split change logs into these headings:

  • New features
  • Breaking changes
  • Bug fixes

Good suggestion, I wanted to mention this, but forgot to get around to it when attempting to avoid a discussion on version numbering and especially semantic versioning, so it is clearly missing from the blog post.

I have observed a lot of different versioning schemes so you cannot necessarily rely on semantic versioning, where this is implicit in the usage pattern. This does however underline the importance of emphasising breaking changes in your change log, no matter the versioning scheme used.

Thanks for the comment and feedback


If you are using GitHub as your repository host, I would recommend authoring release notes rather than maintaining a change log. Autoprefixer has a pretty good releases page as an example.

The benefits of GitHub releases:

  • adds a link to the exact commit the release was made on
  • automatically adds a time stamp
  • adds download links so users can download a copy of the repository in the state it was in at the time of release
  • displays the text as rendered rich text when reading it rather than as markdown.
  • it has an easy to access consistent link on the home page of the repo (The "releases" button)
  • people can send a link to a specific release to a work colegue
  • it takes significantly less time to write
  • it looks pretty

Hi Daniel,

That is good advice, my goal with the article was however not to promote or require any special tools or platforms. The change log accompanies the release and your consumer might not have online access.

Anyway I do use the GitHub release facility in conjunction with the change log file accompanying my software myself. The software is distributed via other channels, I just copy my entry from the change log file into the text field for the GitHub release (see example Perl distribution example).

This would work for a lot of software, like Perl distributions or Visual Studio Code extensions etc. where the change log is being made available for consumption by the toolchain or similar. Other distribution channels do seem to approach this differently where nuget for .NET seem to lean on linking to facilities like the one you mention.


Great read! I've implemented a few of these in my recommendation for an updated change log! Thanks.


Thank you Ross

If your change log is public available please let me know I would love to see it :-)



Today I fell over the following article: "Apply Changelog Best Practices to Development", which references (among other things) this "Keep a Changelog" tool, which might be of interest to you.

Have a nice day



Hi, good post!
These are great good practices for developers, but how about end users? We partnered internally with the Product Marketing team and implemented a tool called Beamer (getbeamer.com), which is helping them a lot in the process of communicating new features, bug fixes, and other updates.


Well the audience of the Change Log I talk about aim primarily at developers or in some cases perhaps even super users. I will have a look at the link you provided - thank you very much.

code of conduct - report abuse