-
Notifications
You must be signed in to change notification settings - Fork 90
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Document yanked releases #238
Comments
Having a changelog would have improved the user experience in #679 (emphasis added):
|
I'm a changelog skeptic. Maintaining a 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
|
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. |
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? |
A few people complain about discoverability, but that's easily solved by adding a |
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. |
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: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?
The text was updated successfully, but these errors were encountered: