Changelog

nicolaw 16th February 2022 at 12:46am
Git rant TechnicalNotes

If you're writing software that is delivered to customers and ever receives updates, then you will want to maintain a changelog. Your customers will want to know what has changed in the software they are paying for and installing.

If you're struggling to persuade your software developers and engineers that this is actually necessary, try explaining it in terms they will understand:

Imagine you're self-employed and you just bought Adobe Photoshop at great personal expense because you need it for your job and hobby. When you install Photoshop it takes you several days to install it and a few more to get it working just how you like it. Now imagine that a new version is available and it is at least as expensive as before. Given the great expense and the time taken to get it working, how likely would you be to purchase the newest version if the only information you know about it was that it was newer?

I find that the same kind of basic argument is useful when trying to get your developers to emphasise with your customers who probably would like some documentation with their software, and for log, messages to be comprehensible (and for there not to be "okay error messages" that convey nothing useful other than to strike fear into the end-user).

Anyway, mini-rant and soap-boxing aside, GitLab have a really excellent summary of how they compile their changelogs and what constitutes a good change message.

Additionally, these may be useful: