Document yanked releases

[joshlf]

Document releases which have been yanked (and possibly subsequently un-yanked) along with an explanation for why each release was yanked/un-yanked. Per #238 (comment), a good place for this would be a CHANGELOG.md file. This would also have the advantage of being a default location that users might look expecting to find release notes, and so we could include a reference to our GitHub Releases in that file.

Old text

Keep a changelog (e.g. in a CHANGELOG.md file). It would be easy for it to become stale, so it'd be good if there were some way of ensuring it is kept up-to-date. My current thinking:

• In CI, enforce that the most recent commit alters the changelog
• Allow an annotation in the commit message to opt out of this for changes that don't warrant a changelog update

Combined, these ought to ensure that the author has considered updating the changelog and either done it or consciously decided not to.

UPDATE: Consider using this GitHub Action, which does all of the above for us.

Open question: How does this play with the fact that we keep 0.6.x releases on a separate branch? When we make a new change we expect to backport to 0.6.x, what do we put in the changelog? What about when we cherry-pick that commit on the v0.6.x branch? Do we expect to keep the same changelog file on both branches, or have that file reflect what's on the branch in question?

[joshlf]

Having a changelog would have improved the user experience in #679 (emphasis added):

My project at work was affected by the yanking of 0.7.28 yesterday. I was curious about the reason (which wasn't trivial to find, since there don't seem to be any release notes) and ran into your new policy from #677:

[jswrenn]

I'm a changelog skeptic. Maintaining a CHANGELOG.md can be a significant maintenance burden for underwhelming benefits. When changelog updates are made by individual feature PRs, those PRs will nearly always have a merge conflict that must be resolved. When the changes are made in batch by the maintainer, new releases are blocked on keeping the changelog updated. Frictionless merges and releases are a productivity multiplier, and we should be extremely wary of compromising these aspects of our workflow. I mostly regret keeping changelogs of the crates for which I maintain changelogs.

And, whatever virtues changelogs have for summarizing releases, they're inadequate for summarizing un-releases. I'd argue that the user experience in #679 would have been better satisfied by a yank (or more general bug) log. I'd recommend that we maintain CHANGELOG.md that looks something like this:

Changelog

Releases

To priortize frictionless development and releases, we do not currently
provide hand-curated release notes for all zerocopy releases. To learn what
has changed between minor releases, run changelog.sh.

Regressions and Yanks

0.7.27, 0.7.28

These versions were briefly yanked due to a non-soundness regression reported
in #672. After reconsidering our yanking policy in #679, we un-yanked these
versions.

[djc]

One method that I've seen used with substantial success is using GitHub releases, which has a feature to auto-generate a "changelog" of sorts based on PRs merged since the last release -- this should also cope with maintenance branches. You can then add any high-level remarks above the generated summary. Using GitHub releases is also nice because it makes it easier for tooling like Dependabot to automatically link to the release notes in its pull requests.

[joshlf]

GitHub releases do look pretty appealing. Have you found them to be discoverable in practice? In other words, have you found that folks know to look there for release notes?

[djc]

A few people complain about discoverability, but that's easily solved by adding a CHANGELOG.md that just points at /releases. It's been a minor problem at best.

[richardpringle]

A changelog would be nice, even if it's just what @jswrenn described. It would also be nice to have summaries for minor versions (both pre and post 1.0).

[joshlf]

A changelog would be nice, even if it's just what @jswrenn described. It would also be nice to have summaries for minor versions (both pre and post 1.0).

I've added GitHub releases for all of our Cargo versions. Does that address what you're hoping for?

As for the changelog itself (in particular, to document yanked/un-yanked versions), I've updated the issue description to track that.