Originally posted to the “milestone predictions” thread on internals.rlo.

Ideally the notes for the next release are compiled at the beginning of the beta cycle, 6 weeks ahead of the release.

Copy the previous version’s section in README.md to a new section and strip out all the items. Reuse the existing section structure, but look out for themes in the release that might warrant other sections. e.g. sometimes there’s a lot of interesting perf commits, or rustdoc commits.

Before I start I find the date ranges the release was on master, for making GitHub queries, and the commit ranges for the entire release, as well as commit ranges for just the releases backports.

I only pick out PRs that impact stable features. Currently, nightly development does not have a place in the release notes. Generally, more exciting items go toward the top of sections. Most items are simply links to the PR that landed them; some that need more explanation have additional, unlinked text; anything supported by an RFC has an additional RFC link. I reuse the PR titles or write my own descriptions as needed for clarity.

The main query I do is against GitHub merges for rust-lang/rust for the correct date range, e.g.:


Pick out interesting PRs, especially those tagged ‘relnotes’. Because the date ranges are imprecise, I’ll verify commits at the edges of the dates against git, using a command like:

git log `git merge-base origin/stable 1.16.0`..origin/stable | grep $commit

Note that the branches might be different depending on when you compile the notes.

Then I look for the “libs stabilization” PR, which contains a bunch of newly-stable APIs.

Then I check git for the range of backports. Sometimes there are things there worth mentioning that don’t show up in the GitHub query, but most backports are to fix regressions that never hit stable, so aren’t worth mentioning. The query is something like

git log `git merge-base origin/stable origin/beta`..origin/stable

Again the branch names may be different.

Then I do the same with rust-lang/cargo. When RLS is in-tree we’ll do the same with rust-lang/rls.

There may be a GitHub milestone for the release. Check that to see if there’s anything worth talking about.

Finally, compare the results to this milestone prediction thread and make sure they agree, updating the predictions as necessary.

Example data for relnotes prep

How to prepare milestone predictions

Maintaining the milestone predictions is a less exact process. It’s best to always be on the lookout for new information about what’s in the pipeline, and update the thread incrementally.

Once a release though I do sit down and look for upcoming features. Generally what I do is:

When I post updates to the predictions I also post a message indicating what was updated.