Rust stats on keeping a CHANGELOG.md look worrying, as @dbrgn’s pointed out in his recent post. That our own project Leaf showed up under ‘notable crates’, made us proud at first, but it was just another example that didn’t had a change log. We felt bad and added a CHANGELOG.md to all of our projects and in the process realized, that Rust has the tooling for Auto-Changelogs and is in a sweet place to improve the crate ecosystem in a way that other languages didn’t manage to.

What is a change log and is it important?

A change log is a file (conventionally named CHANGELOG.md), which contains a curated, chronologically ordered list of notable changes for each release of a project. This makes it easier for users to understand what has changed between releases, what will be introduced in the next release, which features became deprecated and which were entirely removed. With a change log, users will feel substantially more relaxed about continuously updating to the latest available release.

Examples for change logs in Rust can be found here, here or at Rust’s RELEASE.md file, which is something like a high-level CHANGELOG.md.

Advantages of Auto-Changelog in Rust

Although we comprehend the benefits that a CHANGELOG file adds to a project, as a maintainer we will constantly cope to keep the discipline of manually maintaining the CHANGELOG.md. A great solution to these kinds of problems is automation. It helps us to keep our good resolutions even in times our motivation reaches a local minimum, as it doesn’t cost much energy.

With automating the maintenance of the CHANGELOG.md, we also lay the foundation for another advantage. Standardization. Sadly, there doesn’t exist an explicit standard for a practical change log format, yet, but we can make a start with implicitly agreeing on the same Auto-Changelog tool. This also ensures, that we, as the clumsy homo sapiens that we are, don’t accidently deviate from the standard.

And if there would be a standard Rust tool for Auto-Changelog (spoiler alert: there is), Rusts ecosystem could improve, as change logs become not only automatically generatable but also automatically parsable. Something that other languages tried to do (e.g. Vandamme/Ruby) but struggled with as the ecosystem was already too far ahead to introduce a standard. Rust is a unique position to establish a CHANGELOG.md standard, that could advance the entire Cargo ecosystem and open source collaboration.

Commit Message Format

Unfortunately, Auto-Changelog can’t come up with sound descriptions for the committed code all by its own, yet. (Which would be an interesting application for Machine Intelligence, though, taking the data available on Github). For now, Auto-Changelog works, because of a Commit Message Format, that the Auto-Changelog software can parse and bring into a structured, information dense format. Which means contributors agree on a Commit Message Format, such as the conventional one, derived from Google’s Angular project.

Using a Commit Message Format, turned out to be very beneficial in terms of overall clarity and quality of commit messages, which definitely expands the value of commit messages. Before the example of such a commit message (which is pretty close to the usual commit message) a quick list of some best practices of working with a commit message format.

explicitly specify the Commit Message Format in the CONTRIBUTING.md, something like this and

use GitCop to automatically notify contributors at the pull request about the Commit Message Format if their commit messages are not valid.

Following, an example of a commit message for a typo fix in the README.md, in the conventional commit message standard:

docs/readme: fix curtailment typo [Optional:

Some description on how this change was done] [Optional:

CLOSE: #99 | REFERENCE: #101, #105]

An Auto-Changelog tool takes the git commit history and parses the commit messages. As the commit messages have high-level structural elements, the Auto-Changelog tool can derive a change log (not just a list of commits). It leaves out documentation and build-related commit messages, structures the important ones e.g. into features, fixes and depreciation parts, links to related or closing issues for a commit and gives credit to the author. With Auto-Changelog, you get the change log for free. (An Auto-Changelog tool is of course ‘smart’ enough to not override changes that you made manually to the change log.)

Auto-Changelog in practice

Now that we know, that the foundation of Auto-Changelog is a set of standardized commit messages, we can move on to share practical experiences with it.

clog-tool/clog-cli:

(174 commits, 9 Contributors, 159 Stars, 0.9.1, active)

Clog is an already mature Rust project to auto generate a CHANGELOG.md file for you and I would propose that this project should be the official change log standard, where the Rust community could, at least implicitly, agree on a standardized, parseable change log format.

Initialize a CHANGELOG.md

If you already agreed on a commit message format, you can generate a CHANGELOG.md file with a few simple commands for each of your previous releases.

> clog --setversion 0.1.0 --from 0.0.0 --to 0.1.0 -C CHANGELOG.md

> clog --setversion 0.2.0 --from 0.1.0 --to 0.2.0 -C CHANGELOG.md

> clog --setversion 0.2.1 --from 0.2.0 --to 0.2.1 -C CHANGELOG.md

> # and so on

If you didn’t agree on a commit message format, you can either copy the example CHANGELOG.md from clog and fill it out manually or use a temporary git rebase.

Git rebase has the advantage of making no structural mistakes, as you just temporarily rename your commit messages to support a commit message format and can then use the clog from above. It works like this:

> git checkout -b tmp/changelog

> git rebase -i [initial commit id]

> [rename the commit messages with setting 'r']

> [now, we have commit messages in the commit message format]

> clog --setversion 0.1.0 --from 0.0.0 --to 0.1.0 -C CHANGELOG.md

> clog --setversion 0.2.0 --from 0.1.0 --to 0.2.0 -C CHANGELOG.md

> # and so on

> git checkout master

> git add .

> git branch -D tmp/changelog

Continuously maintaining the CHANGELOG.md

Now, that we have a change log of what previously happened, we want to maintain the change log file for all changes that will come in the future. But note, unlike the initialization, this requires that the crate agreed on a commit message format.

Continuously maintaining the CHANGELOG.md is super easy with Clog as the Auto-Changelog tool. All you need to do is run the following command before a new, important commit.

clog --setversion 'x.x.x Unreleased'

and the following command with a new release.

clog --setversion 'x.x.x'

Future of Clog and Auto-Changelog in Rust

As I mentioned earlier, I think that Rust is in a unique position to enhance the crate ecosystem in a way that, no other language was able to do, yet. Clog moved in the right direction and has already an impressive set of features e.g. config, CLI, and JSON support. But it seems that Clog stalled recently. Clog needs improvements and fixes, which would reflect the best practices of the change log community as well as the consent of the Rust community.

A list of things that we think needs to be fixed and agreed on by the community, can be found on the Clog Github repository.

@cmr did recently the MIT/Apache-2 campaign, where he raised awareness for the licensing model in the Rust ecosystem, by creating auto-PRs for the easy transitioning to a dual MIT/Apache-2 license. Maybe he would like to use his knowledge and infrastructure to help raise awareness for Changelogs as well?

Cargo could help by expanding the Cargo.toml with a changelog attribute, related to those of readme and documentation, to put more emphasis on the importance of keeping a CHANGELOG.md. #2188