I've been coding Rust during my free time for a few months now (mostly on the spaceapi server, the telegram groups bot and rpsrtsrs). Something I noticed lately is that very rarely projects keep a changelog or provide release notes.
Is that perception true?
Here is the list of the 10 most downloaded crates on crates.io (as of December 2015), and whether or not they provide a changelog in their code repository or in their README:
| Crate | Changelog |
|---|---|
| libc | ✗ |
| winapi | ✗ |
| rustc-serialize | ✗ |
| rand | ✗ |
| log | ✗ |
| bitflags | ✗ |
| winapi-build | ✗ |
| gcc | ✗ |
| time | ✗ |
| advapi32-sys | ✗ |
Now most of these projects are "official" crates by the Rust project developers. Maybe these are somehow different? So as another comparison, let's list some of the recent "notable crates" from the This Week In Rust newsletter, as well as some other random crates I frequently use:
| Crate | Changelog |
|---|---|
| piston | ✗ |
| glium | ✓ |
| httparse | ✗ |
| leaf | ✗ |
| nom | ✓ |
| barcoders | ✗ |
| diesel | ✓ |
| chomp | ✗ |
| hyper | ✓ |
| iron | ✗ |
| rust-postgres | ✗ |
| redis-rs | ✗ |
| r2d2 | ✗ |
The result is still sobering. Almost no Rust projects provide a changelog.
What is a changelog?
According to Wikipedia:
A changelog is a log or record of all the changes made to a project, such as a website or software project, usually including such records as bug fixes, new features, etc. Some open source projects include a changelog as one of the top level files in their distribution.
A changelog is usually kept in a file called ChangeLog, CHANGELOG.md, CHANGES.md or HISTORY.txt. The format varies. But the essence is: It keeps the users of the codebase up to date regarding the changes between different releases.
But we have SemVer!
By default, Cargo uses Semantic Versioning for resolving dependencies and their available versions. That's a fantastic thing. SemVer provides a simple way to check whether a version update contains breaking changes or not, without having to look at any release notes or changelogs. This is definitely something I'm really happy about.
But the versioning scheme only helps with knowing that something breaks, but not what breaks. The first thing you should do whenever a crate that you depend on upgrades the major version, is to head to the project changelog to see whether you need to take any action regarding incompatibilities or deprecations.
Incompatible changes are a small detail when using binary projects, but not when dealing with libraries. Libraries are meant to be used directly and indirectly by other people. Changing code in a way that is reverse incompatible will break people's code. So please let them know what changed and what they need to do about it.
But we have the Git log!
The git log is not meant for a quick overview regarding important changes. It contains a lot of noise that isn't relevant to your library users. As an outsider, it's hard to learn about important changes from the git log. It is definitely no replacement for a proper changelog.
Recommendations
Here are a few recommendations regarding release and change management of libraries:
- If you have a project on crates.io that doesn't yet have a changelog, please add one, in a file called CHANGELOG.md.
- In the changelog, explicitly state that you follow semantic versioning (if you do, and you should).
- Write your changelog in an easy to read format. You can find one possible format here, or another one here.
- Every time you release a new version, tag the corresponding commit in your git repository with git tag vX.Y.Z. Don't forget to push the tags upstream with git push --tags!
You'll find more details about why and how to keep changelogs on http://keepachangelog.com/.
Further Recommendations
Right now there's no way to specify the changelog in your Cargo.toml. That's a pity. So if there are any Cargo developers around: Please add an option to specify the changelog link in Cargo.toml and display the link on crates.io below the links to the repository and the documentation!
Discuss on HackerNews and Reddit.