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

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 based on my experience and opinion and is not a set of best practices, simply practices I have developed from consuming and producing change logs in my work with software and open source in particular.

When you do a software projects, big or small, it is a good idea to write a change log. A change log is often manifested in a single text file accompanying the script, library or application, which is the center of the software development or project.

When communicating via written text there are a few important key point one have to keep in mind in order to succeed and get the intended message through.

• Who is the (intended) audience of the text?
• Why is the audience reading the text?

These are pretty basic questions and the answer seems pretty straight forward, but do you remember to ask yourself these two important questions when writing your text? and in particular your change log.

So lets try to set the setting for the writing a change log. We can actually to this with a Story format, describing this as a basic use-case.

A user of my software is reading my change log to see if a earlier
reported bug has been addressed

The reason why we want be so specific, is to understand the role of the change log and hence it's importance.

The change log place a specific role, which sets it aside from the other documentation. The main documentation describes the ideal use of the software, perhaps some limitations, perhaps it refers to a TODO list, a tutorial or something else, but the main use case of the software is described elsewhere and it is often updated with the software meaning it does not document the change, but the current state, perhaps a migration from a previous state or it communicates deprecation or introduction of existing and new features respectively. The change log plays a single, but very important role of communicating changes to the software.

Going into details of the structuring documentation and the communication task associated with this is beyond this blog post, perhaps it should be examined in the same way, I do have some experience and opinions on documentation, but lets stick to the topic.

The main documentation serves the following use-cases:

• Finding out what the software does, perhaps even how it does it
• How it is installed, configured, used and perhaps even troubleshooted
• How it is uninstalled
• Perhaps how to get support or contact the author

But everything is very much in regard to the current version of the software and as stated perhaps with migration and deprecation information.

Lets examine another use-case.

A user of my software observes a problem, which points to my software.
Instead of pouring over 1000s of lines of code, the change log is
skimmed to see if any listed changes could be the reason to the problem

This leads to yet another communication key point, which might be very relevant in software usage situation, but could also be relevant to other pieces of textual communication, being consumed under a state of urgency.

• When is the audience reading the text?

Somebody is working hard, perhaps overtime, with a software problem or similar they are under pressure and it is late. They run into an issue similar to the use-case we just described and have to figure out as fast as possible if an update involving your software is the reason for their problem, they have to decide om looking elsewhere, implementing a workaround or rolling back.

That is when the change log comes in handy.

The change log is a short, concise description of changes adhering to a certain standard layout for easy consumption.

Now lets get into how you should structure your change log, to accommodate these uses cases in a good way.

Add a Title

The filename is quite ambiguous, so add a title at the top of the file

Change log for ApplicationX

Entries should be organised as a heading with a list of sub-items

The entry should start with an indication of the release described, this example uses Semantic Versioning (semver), I will get back to that and then a list item per change.

1.0.1
- Fixed bug in parser

Sort entries in reverse chronology

The regular use case is to spot the most recent change, so historical changes becoming less and less significant over time, drift towards the end of the document.

1.0.1
- Fixed bug in parser

1.0.0
- Initial release

Structure a release entry

A release entry should be structured in a uniform matter.

It should at least include:

• version number
• timestamp

Whether you use semantic versioning is up to you. But a recognisable versioning scheme which enables unique identification of each release is required.

1.0.1 2018-09-27
- Fixed bug in parser

1.0.0 2018-09-27
- Initial release

I have seen timestamps with time zone and a resolution of hours, minutes and seconds, this might not be necessary, since the release might not have the same impact as the actual operation of deploying it etc. so this extra information is a bit overkill IMHO.

Be consistent with the date format, ISO-8601 date format is recommended.

Some extra meta data I have found quite beneficial are is a release type indication:

• Feature release
• Maintenance release
• Bug fix release

These does not map directly to the semantic versioning scheme, but they provide some information on how to approach the release.

1.0.2 2018-09-27 Maintenance release
- gitignore updated with tmp directory

1.0.1 2018-09-27 Bug fix release
- Fixed bug in parser

1.0.0 2018-09-02 Feature release
- Initial release

The user can look at the release notes and judge, whether the feature included in the feature release is useful for them at this point in time or it can be skipped for now.

If it just a maintenance release, which addresses minor hick-ups in the meta-data or release information (believe me I have made quite a few of these over the years), it can perhaps be skipped for now.

And finally the bug fix release indicating, nothing new has been added, backwards compability is intact bugs have been addressed and for the audience looking to see if their issue has been resolved this information is worth gold.

Some bug fixes mighe be significant and therefore it can be important to hint to what the users stance should be on the release.

I use these two:

• Update recommended
• Update not required

1.0.2 2018-09-27 Maintenance release, Update not required
- gitignore updated with tmp directory

1.0.1 2018-09-27 Bug fix release, Update recommended
- Fixed bug in parser

1.0.0 2018-09-02 Feature release
- Initial release

Structure change item entries

Now we have our release entry structure in place, now lets have a look at the change item entries.

A single item in the release should be described for human consumption and each change set should be described with a single entry.

I have seen grouping of entries into:

• Feature additions
• Bug fixes

Yes, this should be a part of the overall change entry structure, but since I aim to keep my releases small and either categorised as bug fix or feature releases, I try not to mix these is a release.

If you make larger releases with several changes, for example major releases, this separation can be quite useful, for example if you run with regular scheduled releases..

2.0.0 2018-09-27 Feature release, Update recommended

Feature additions:
- Added color selector
- Added color profile exporter

Bug fixes:
- Addressed issue with start up time

In order to not have to rewrite everything in your change log, add links and references.

1.09 2018-05-30 Bug fix release, update not required

- Based on issue #21 several issues with the test suite was spotted
  and corrected, at the same time there was created issues for
  implementation of adapters for SK and NZ. An issue with ES was also
  created since this distribution seems to rely on Date::Holidays,
  which does not seem to make sense.

  Ref: https://github.com/jonasbn/Date-Holidays/issues/21

Please write in passive voice and not active voice. I have seen this plenty of times, where people copy directly from TODO lists or issues trackers etc. This can also often be observed in commit logs - and if you ask me it is just plain sloppy.

Example:

In your issue tracker you have the assignment:

"Add color selector"

This indicates something has to be completed.

And in your change log you add:

"Added color selector"

This indicates something has been completed.

These are my recommendations for a basic change log, now let me touch some related information.

Auto-generating Change Log

I have seen several attempts to auto-generate change logs from commit logs or similar. I do not recommend this.

The change log has plays an important role, it is a medium of communication, not just a list of changes. If you where to do this I think the following criteria should be considered.

• Are you commit messages sufficient
• Are you squashing merges or handling change sets as transactions
• Can you extract meta-data from your version control system (VCS)

This can be accomplished and all of the two above criteria are sane advice for normal commit discipline, but I have never seen/worked on a project mature or disciplined enough to do this - not that I do not strive to do this, but it is hard.

One of the pitfalls is that I do not think the generation of a change log artefact should dictate who you should work or you proces. But if you are in a situation where it would be possible to auto-generate the change log, please let me know I would love to hear about it.

Bonus Tip: Write in Markdown

That was quite a mouthful and the write-up become longer than expected, but I have to squeeze in this bonus information.

Consider writing your change log in Markdown.

• This makes links shorter, which these are rendered as hypertext instead of text and yes hyperlinks are just cool - thanks Mr. Berners-Lee.
• You can use bold, italics and code fences if required

And finally, you can organise your release entries using different headers, Minor releases can be included in major releases.

## 2.0.0 2018-09-27 Feature release, Update recommended
- Added colour selector

### 1.0.1 2018-09-03 Bug fix release, Update recommended
- Fixed bug in parser

## 1.0.0 2018-09-02 Feature release
- Initial release

Thanks for reading to the end, please comment with your reflections/questions etc.