@chriskrycho I had no idea you were working on the reference, what sort of progress have you made? This seems like the perfect sort of thing to advertise around to get a bunch of eyes on it, but I’d rather only do that once you think it’s ready.
Depending on person’s background there is a long list of RFC that need the documentation status evaluated. I am happy to merge changes from forks of the gist.
I’ve recently made the following changes:
I’ve added sections to each version in the op for “compatibility notes”.
I hear of minor, intentional regressions often, and am very worried that they are not being tagged on the issue tracker. The op here is a simple place to list these regressions when you come across them, letting us sort the details out for the release notes later. Please keep it in mind.
Someone motivated might watch the beta regressions for those that are closed wontfix and add them to the op with links, or better yet, find the PRs that introduced the changes and tag them ‘relnotes’.
Rust 1.17 release status
I updated 1.17 to match what’s actually being released. All these things didn’t make it:
deprecate rustc-serialize in 1.18?
I don’t think that’s tied to rustc releases, really.
Seems like rustc-serialize is deprecated right now, for 1.17.
Edit: well, actually there’s no patch to the compiler to deprecate the attribute yet. It’s kinda half-deprecated.
…The linked tracking issue was closed by bors when 40870 was merged. That was three weeks ago. I don’t know exactly how the process works, but shouldn’t that mean that this did make it?
It was merged into
master. Then it has to wait for the next
beta branch (every 6 weeks), and then it’s 6 more weeks to reach
stable. So it can be 6-12 weeks total from merge to stable release, unless someone actively backports it to beta sooner.
Okay, so since the 1.18 beta has been branched, I assume this means it’s on track for 1.18?
I believe so, yes.
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.:
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
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
- [ ] 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.
Looks like a lot of work if it takes you a full day to complete ! That’s only an idea but would it be possible to split the relnotes between 2 people (for instance one takes care of Cargo and the other of Rust itself) so that the workload is split in two as well ?
Personally I’d love to help, but I feel like I would be more a burden than anything given my low knowledge of Rust’s release process. However if I can help just a little bit or even take half of the workload that the new maintainer is going to have, then count me in, I would love to !
Hey, so I gave it a shot. The preliminary relnotes for 1.18. Please let know if there was anything I missed. The only PRs I uncertain as to if they would after the next stable was platform specific stuff like NetBSD cross compiler stuff.
@Cobrand it’s possible. The cargo notes are a small part of the overall release though. It would be good for somebody more in tune with cargo to put them together certainly. For 1.17 I did cargo last and basically just copied PR titles directly into the notes without understanding what they even did.
It is true that having strong familiarity with what is going on in Rust helps a lot. Every time though I solicit reviews of the relnotes PR to get feedback about things I missed or don’t understand, and that helps.
@Aaronepower thank you!
I don’t see a “Stabilized APIs” section. Maybe that PR hasn’t been made yet and needs to be backported to beta.
Seems like there are a number of things in the OP’s 1.18 predictions that aren’t on the list (e.g. numeric field names, custom crt linkage). Can you hunt down the status of those and update the predictions to match the relnote?
The NetBSD patch looks to me like it mostly affects the CI for Rust and its own build system. I’d probably not include it.
That said, sometimes it’s worth including PRs about things just to indicate that something is happening. Last notes for instance had lines about ‘preliminary support for X platform’, even though those didn’t affect anything on stable.
I updated the OP to archive the 1.17 predictions. Also added a header for 1.20, August 31. Also bumped cargo 1.0 to 1.19. Don’t think there’s any movement on that. Also added more text to my description of the release notes process, indicating to check the GitHub release milestone, and to bring the milestone predictions into agreement with the release notes.
I submitted the process to the forge: https://github.com/rust-lang-nursery/rust-forge/pull/58