Makin' an Amazin' Changelog!

We here at Bearmint know a developer’s job is never truly done, and while a certain application may do what it’s supposed to, there’s almost always ways to make it run a little more efficiently or get rid of any bugs you might find. In this way, yer application’s likely to go through many iterations over time as you find ways to add to its functionality and improve on existin’ processes. But what happens if somebody wants to learn more about what you’ve been up to but happens to show up several versions down the line?

This is exactly why you’ll need to keep a real good record of all yer major changes, additions, deletions and other alterations you make to yer application over time. And how is this done? Why, via a changelog of course! Now you certainly don’t want to include every little detail and change you make over time, but you sure need to do yer best to keep track of things that have a significant on the way yer application functions. Moreover, anyone who is followin’ yer progress and wants to use a certain version will need to know what they need to do in order to get up and runnin’. That means they’ll need to review yer changelog and extract the information they require so that they can do whatever it is they intend to do!

Now you may figure keepin’ a changelog is real simple and that you can just set up a nice, easy system to keep a record of everythin’, but if you actually want people to use yer application and contribute, it’s a little bit more complicated than that. That’s why today’s post focuses on the importance of a good changelog, what it’s made up of and how to make sure you maintain a high standard at all times. Yer free to disregard this information, but by followin’ a few simple rules, you should find that keepin’ a reliable, accurate changelog is much easier and that others will feel more inclined to join in and contribute!

Now Why Should I Bother With This, Pilgrim?

A well-maintained and easy-to-navigate changelog is important for several reasons:

  • First and foremost, it provides a full history of any major amendments, deletions or additions a particular application received at various points along its development path
  • It allows developers and new contributors to review the various upgrades the application in question received over time
  • It enhances the experience for developers and cuts out any unnecessary information (which is commonly referred to as noise)
  • It allows anyone viewing the logs (and without any context) to obtain a better understanding of where the application currently stands in terms of its roadmap, and
  • It communicates all important information in an effective and human-readable format which makes contributing much easier for anyone looking to invest time and effort into the project

What a Good Changelog Looks Like

While there’s no standard format or widely adopted approach for changelogs, it’s advisable to keep the following aspects in mind when creating them:

  • Human beings use changelogs, not machines
  • Every single version should contain an entry of some kind
  • It’s best to group changes according to their type
  • Having versions and sections linked is best practice
  • The latest version should appear first
  • Clearly display the release date of each version in the appropriate format - for example, using the ISO format 2022-09-23 which clearly indicates September 23rd, 2022
  • Keep entries as brief as possible and only include additional information where necessary
  • Focus on readability and stick to a specific format at all times, and
  • Specify whether you follow Semantic Versioning or some other convention

Types of Changes

  • Added for any and all new features added to the application
  • Changed for any modifications to existing functionality
  • Deprecated for features that you intend to remove in the near future
  • Fixed for any bug fixes you or other contributors carried out
  • Performance for any performance-related enhancements made to the application
  • Removed for any and all features removed from the application
  • Security should any security vulnerabilities exist, and
  • Other in the event that the change in question doesn’t actually fall under any of the aforementioned categories

What a Good Changelog Ain’t

In order to keep a changelog free of unnecessary information and noise, it’s important to list several items that we don’t need to include:

  • A fix for a regression introduced and then addressed within the same release (such as fixing a bug that arose during a monthly release candidate) should not appear as a changelog entry
  • Any experimental or unfinalized changes should not appear as a changelog entry
  • A maintenance release that only features documentation changes should not appear as a changelog entry
  • Do not use commit log diffs as a way to maintain your changelog as these tend to contain merge commits, oddly titled commits and documentation changes - in accordance with avoiding noise, you should not adopt this approach for your changelog
  • Do not ignore deprecations - you must make it entirely obvious when something will break in your application. If nothing else, you must include deprecations, removals and any breaking changes in your changelog
  • Avoid confusing date formats as these tend to vary from region to region. Again, we recommend following the ISO format as it’s nice and clear and records dates from the largest to the smallest unit, namely year, month and finally, the day

So How Do I Make Maintenance Nice and Easy?

It’s best to keep an Unreleased section at the top of your changelog so that anyone viewing it can keep track of any upcoming changes. This is necessary for several reasons:

  • People can view the current listed changes and anticipate what the next release will consist of
  • When a release takes place, you can simply transfer the Unreleased section changes into a new release version section
  • This also helps anyone working on the project to keep track of progress and prepare for upcoming releases more easily

A Few More Points to Keep in Mind…

Other ways to improve your own changelog and points to bear in mind include the following:

  • Remember that a changelog should only document those changes that affect the public API. Also, if an introduced change makes little to no real difference for your end users, it’s best to leave it out of your changelog
  • It’s useful to include references to actual pull requests or commits, but please ensure that you create links using the PR number or shortened hash as the text for your link - do not simply dump a git hash into the text!
  • While it isn’t obligatory by any means, many changelogs provide acknowledgements to individual contributors for the work they have done. While this may add a little more “noise” to your changelog, it’s justifiable since it shows that a project actually cares about its individual contributors and that open source code doesn’t just appear out of nowhere!

And That’s the Long and Short of It!

There ain’t no hard and fast rules when it comes to changelogs, partners, but as long as you observe most of the recommendations outlined in this blog, you oughtta be just fine. Whatever you do, always remember that people with zero understandin’ of yer application should be able to review yer changelog and get an idea of what it is yer doin’ within a few minutes. If this ain’t the case, then we reckon you still got yer work cut out fer you!

If you have any further questions about changelogs or anythin’ else relevant to the world of Web3 and blockchain, then feel free to drop us a line and let us know what it is we can do fer you. There’s always plenty to learn and many great ideas to try out, so don’t hesitate to ask if you ever need a helpin’ hand!