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?