Published on 2017-01-19

What is a changelog and why is it good to have? I mean - you have your commit comments and they should cover all the details about changes to the code, right?

This is not true - the changes made to the code and the description of those aren't necessarily the best description of what have actually changed.

The needs

It is very easy to see the work we do as changes to some code but in fact it is changes to a product that a user is actually using.

If we run a (pretty normal) setup where we have issues and commit logs bundled with milestones etc. in a place like GitHub we have the code part fully covered. The issues describe the problems with the code and the milestones group together those problems into logical groups, deadlines eg.. The commits describe (in code) the solution to the problems (described in the issues) and the comments for the commits describe the hard-to-see details about the code in the commit.

All of this is in place and helps - but it really only helps the development process and the understanding of the code. The users of the software know nothing of this - and they quite possibly gain close to nothing from reading any of this!

What should a changelog contain

The changelog is a solution to this problem.

A changelog should contain bullets of changes arranged by each release of the product. Each point should describe one change relevant to the user - like the addition/removal of a single feature or a bug eg. being fixed.

Put in a bit broader terms a changelog is a marketing write-up of the changes (from commit logs, planning etc.) that goes into a release.

A few things can be derived from this:

  • You can write the changelog only when you know what the release contains
  • The wording in the changelog should fit the user
  • The material for the changelog is already at your disposal

Learn more

The site Keep a CHANGELOG have way more information about how to construct a useful changelog including what elements to include and general guidelines.