In this short blog post, we will see some benefits of maintaining a changelog in a software project and making it available to its users. We will also introduce a small open source library that we developed internally at ActiveViam to convert a changelog written in Markdown to a static web page with permalinks.
Why a changelog?
As explained by Keep a Changelog:
A changelog is a file which contains a curated and chronologically ordered list of notable changes for each version of a project. Keeping a changelog makes it easier for users to see precisely which changes will impact them and thus to estimate the cost of migration for each version of the project.
Until now, for our ActiveUI project, we were maintaining one release/migration wiki page for each released version. Moving to a single changelog and making it available to our users brings several improvements:
- It’s easier to keep up to date as it’s versioned with the rest of the repository files. When making a pull request on GitHub to add a feature or to fix an existing bug, the developer can directly add the relevant line in the changelog as part of the suggested changes. It’s harder to forget than editing a wiki page and it’s also simple to review.
- It’s quicker for anybody to find the version in which a feature has been introduced since there is only one file to search in.
Some projects even decide to generate their changelog automatically from commit messages. It surely makes the changelog maintenance very cheap but it can also make its content irrelevant to the project users.
Indeed, commit messages often contains names and concepts too technical to be helpful for the project users. Some commits, such as merge or internal refactoring commits, can even be completely useless in the context of a changelog.
The important thing to keep in mind is that changelogs are for humans, not machines.
Thus, they must be maintained manually and written in simple prose.
Choosing a convention
The changelog structure is, by nature, repetitive. For each released version, it repeats the same sections: Added, Changed, Deprecated, etc. The readers of the changelog will find what they need quicker if the order of these sections never changes. That’s why it’s a good idea to pick an existing changelog convention and to stick to it.
At ActiveViam, we went with the CHANGELOG.md convention proposed by Keep a Changelog.
Converting a CHANGELOG.md file to a static web page
Once your changelog has been written in Markdown and committed to version control, the last step is to make it available to the users of your project.
If your project is hosted on GitHub you could simply give your users a link pointing to the CHANGELOG.md file in the repository and GitHub will render it nicely. If you don’t want to grant your users access to your repository, you could also leverage the GitHub API to convert Markdown to HTML. The problem with both techniques is that the links generated by GitHub for each title of the changelog are unstable. Let’s take a changelog example:
## [0.3.0] - 2003-03-03
* A bullet.
## [0.2.0] - 2002-02-02
* Another bullet.
## [0.1.0] - 2001-01-01
* Last bullet.
GitHub will generate these URLs:
This makes the
added anchors ephemeral. Indeed, as soon as a new version is added to the changelog, all the existing anchors will change because GitHub will increment their trailing number:
- added-1 (used to be added)
- added-2 (used to be added-1)
- added-3 (used to be added-2)
We believe it’s important to have durable links to any section of any released version, so, for our ActiveUI project, we searched for a simple open source Node.js library to do the conversion from Markdown to a static web page with permalinks. We found some npm packages such as markdown-it-github-headings, generate_release_notes, and github-markdown but none of them supported permalinks. We thus decided to fill the gap by writing a small conversion library and making it open source!
Here is a screenshot of its output:
Feel free to use our library!