Lately I realized a thing which made me sad: changelog formats are far from standardized.
I stumbled upon this thought while thinking about a way to have bundle outdated to print out a kind of changelog excerpt to help me get an idea on whether I had to update a gem or skip the latest version for this time.
The first step to achieve this would be to have a kind of changelog parser to extract machine readable data. So I started to look around for a changelog parser. I hardly found something, which somehow surprised me.
The official CHANGELOG format
I wasn’t able to find an official spec for changelogs. I found instead a page hosted on gnu.org
which lists a few advice on how to create a changelog file. It’s venerable. It describes few rules especially suited for programs written it C language.
It lacks of several directions I was expecting to find. For instance it doesn’t say anything about version numbers. It’s all about dates of changes.
Different formats and conventions
I decided to have a deeper look at several popular OSS projects to see how they behave. I was expecting to find a changelog of any format in the root directory of the project. I was almost never the case.
The Linux Kernel
Linux kernel does not have a changelog file in the root directory. There’s a Documentation folder, with a “Changes” file inside. It’s a documentation file, not a changelog strictly speaking, so it does not track changes in specific versions. Other changelog files are present in specific component folders.
Ruby on Rails
There’s not a changelog in the main folder, but several “CHANGELOG.md” files inside each component folder. It’s a markdown file, with no version numbers and no dates.
An History.txt file with version numbers and no dates.
What about libraries?
Since I’m a Ruby guy, let’s have a look at some popular Rubygem:
Sidekiq has a Changes.md file which has version number and a bullet list item for each change. No dates. It has code examples.
Has a Changelog.rdoc file with version and dates as headings, and bullet lists for features and bugfixes.
Has a CHANGELOG.md
with version numbers and changes in a bullet list, just like Sidekiq.
Do I need a changelog?
There are times in which it doesn’t make sense to write a changelog. A small team working on a private project may not find any benefit
in writing a changelog. But if you work on a opensource project, especially on a library, you should definitely have one.
Dependencies on a project tend to become difficult to manage also because you don’t have a clear view of what changed.
Semantic versioning helps us a lot to quickly understand if it’s safe update a component or not.
Is it a bugfix? You should update ASAP. Is it a minor change? It’s safe to update and you should, because you want to stay close to the edge, right? Is it a major change? You should take the risk to update because the world is moving on. But it’s not always that easy.
Even if it’s a bugfix, I want to know what changed. And because every time I run a
bundle outdated it’s always a long list showing up, I would have a quick summary.
Many times, even minor version changes are too easily applied. If a change is backward compatible you should still ask yourself if that change is something you would benefit of. Most of the times it’s a new feature introduced, which you may not need. Moreover a backward compatible change may introduce a bug.
Developers are often caught by a kind of up-to-date fever. I think part of it is due to the fact that it’s hard to have a clear view of your outofdateness.
Why a shared format is important
Going back to the initial thought which led to all this typing, a shared standard for changelogs would make it possible to have machines do something interesting with those files.
Bundler is one of the many dependency management which may benefit of a parsable format. Even an online service would be possible with little effort, to send you a weekly digest of the changelogs of your project’s dependencies.
Modern requirements for a changelog
Let’s have a look at what the specs for a modern changelog should be.
The most important thing a changelog should tell is the version number the changes refer to. Listing dates is much less important.
Having a look at what most projects are doing, I think any kind of text friendly markup language is a desirable feature. TXT is great, but the world is on the web and with a tiny markdown effort we can make web pages much more pleasant to read.
Markdown would also make possible to have automated syntax highlight for code samples and all the stuff we already know and appreciate. This should be optional though.
List of changes
Those should be listed from the most recent to the oldest. Each item should start with an item list marker (this may change depending on the makrup language adopted). Each item should be composed of at least a short summary.
Optionally, a change may have a longer description of the change, links, code example or any other thing a developer may want to add.
This is far less important than the previous three. I would hardly make a decision on whether a change is something I would apply or not based on who did that. That should be something you dig into the CVS when interested in. This one too should be optional.
I don’t know what to do with dates in a changelog. Again, they may have a meaning, but what I’m trying to come up with is a format which includes the basic facts a developer may need to decide if a change is worth upgrading or not. I don’t think anybody would take this decision based on a date. I consider the date to be optional too.
It’s worth nothing that if you like to put dates in a changelog, you may want to put the dates on change items and on version numbers. If you are a date maniac, you’d probably want to know how much time passed since the last change and the version release.
I think something like this would go as a standard changelog:
# Acme Products ## 2.1.2 (2002-03-10) * Added a button to fire missiles You should use this only if in danger. Don't fire for offense. Ever. Author: Fabrizio Regini <firstname.lastname@example.org> * Added breaks * Fix a bug in cosmic ray controller
Which in markdown translates into this:
I think that having a shared format for changelogs is a bit of an utopia. But the possibility to have your changes show up nicely into one of the many dependency management softwares out there may be a huge stimulus for developers to agree on something.
What do you think?