Rustaceans: Please Keep a Changelog!

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 usesSemantic
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!

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!