I am looking for somebody to take over maintenance of the release
notes.
Is anybody interested in compiling the 1.18 release notes and updating
the milestone predictions? Creating good release notes and
telegraphing what is in the pipeline is an important part of the Rust
process.
Ideally the notes for the next release are compiled at the beginning
of the beta cycle, 6 weeks ahead of the release. That means the time
to make the 1.18 notes and update predictions is now.
Below is how I do it. It usually takes several hours of effort, which
typically occupies a full day, with other interruptions considered.
How to prepare Rust release notes
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.:
https://github.com/rust-lang/rust/pulls?q=is%3Apr+is%3Amerged+merged%3A2017-02-02..2017-03-16
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
-
release: 2017-04-27
-
on master: 2017-02-02 - 2017-03-16
-
all commits: git log git merge-base origin/stable 1.16.0
…origin/stable
-
just backports: git log git merge-base origin/stable origin/beta
…origin/stable
-
checklist
- [ ] rust prs
- [ ] rust backports
- [ ] libs stabilization pr
- [ ] cargo prs
- [ ] cargo backports
- [ ] check on GitHub release milestone
- [ ] compare to on-thread milestone predictions
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:
- go through the existing predictions and re-estimate them
- look for final-comment-period tags on rust-lang/rust and rust-lang/rfcs and
try to divine new estimates from that
- look for B-unstable tags on rust-lang/rust and see if there’s any
notable activity
When I post updates to the predictions I also post a message
indicating what was updated.