Tweak and update the transition guide #59
Conversation
|
This shouldn't be merged just yet until rust-lang/rust#52429 is merged and |
Centril
changed the title
src/editions/transitioning.md
Outdated
| @@ -1,47 +1,30 @@ | |||
| # Transitioning your code to a new edition | |||
|
|
|||
| Transitioning between editions is built around lints. Fundamentally, the | |||
| process works like this: | |||
| New editions might change the way you write Rust -- they add syntax, language, | |||
There was a problem hiding this comment.
"new" between "add" and "syntax"
src/editions/transitioning.md
Outdated
| Transitioning between editions is built around lints. Fundamentally, the | ||
| process works like this: | ||
| New editions might change the way you write Rust -- they add syntax, language, | ||
| and library features but also remove others. For example, `async`/`await` will |
There was a problem hiding this comment.
remove others -> remove features
src/editions/transitioning.md
Outdated
| process works like this: | ||
| New editions might change the way you write Rust -- they add syntax, language, | ||
| and library features but also remove others. For example, `async`/`await` will | ||
| be available in Rust 2018, but not Rust 2015. Despite this it's our intention |
There was a problem hiding this comment.
Saying that async await will be available in Rust 2018 is true; but not at the release date this year, which a user may reasonably construe from this wording without any info as to the contrary.
src/editions/transitioning.md
Outdated
| * Get your code compiling with no warnings. | ||
| * Opt in to the new edition. | ||
| * Fix any new warnings that may result. | ||
| * Opt in to the new edition, code should compile. |
src/editions/transitioning.md
Outdated
| ## Prepare for the next edition | ||
|
|
||
| Before we talk about how to move to the new edition, a reminder: | ||
| `cargo fix`. It can take suggestions from the compiler and automatically |
There was a problem hiding this comment.
it would be good to say here that the subcommand "fix" is shipped with cargo.
src/editions/transitioning.md
Outdated
|
|
||
| ## Fix new warnings | ||
| Your crate has now entered the 2018 edition of Rust, congrats! Recall though | ||
| that Editions in Rust signify a shift in idioms over time, and while much old |
There was a problem hiding this comment.
Break sentence between "time" and "and".
|
|
||
| ```rust | ||
| // Opt in to unstable features expected for Rust 2018 | ||
| #![feature(rust_2018_preview)] |
There was a problem hiding this comment.
This code snippet gave the user a crash-course into the new edition.
It is sorta useful if all the user wants to do is test it out but not migrate yet.
I think we should somehow retain the mention of #![feature(rust_2018_preview)] earlier than 1.1 for now.
There was a problem hiding this comment.
Unfortunately there's a few part of things I think are misleading:
- This is recommending turning on the
rust_2018_idiomslint without properly warning about how underbaked it currently is (huge numbers of warnings and warnings with no real actionable advice) - It's enabling the 2018 edition without going through
cargo fixwhich can give people the impression that their crates' hundreds of errors (due to paths) mean the edition is a huge hazard - It's jumping the gun a bit in terms of what this all is and how it all interacts with one another.
This is all explained in the transition guide (hopefully in a relatively "quick" fashion) though! I just wanted to make sure we're very careful in this regard as this is a very sensitive topic (migrating to the new edition) and one that I think is important to get right
src/editions/transitioning.md
Outdated
|
|
||
| ```shell | ||
| $ cargo +nightly fix --prepare-for 2018 | ||
| $ cargo +nightly fix --prepare-for 2018 --all-targets |
There was a problem hiding this comment.
Can we get a fix for #19 (comment) somewhere around here as well?
There was a problem hiding this comment.
The help message is pretty comprehensive, but I can add --all-features for good measure.
|
@alexcrichton Do you think you could respond to @Centril 's criticisms sometime in the first half of the day? I'm talking at a meetup tonight europe time and would like to use the latest stuff, which this includes. If you don't have time, I can make the edits myself and merge in too |
|
oh wait, a nightly hasn't been produced yet, darn |
* Reflect that `rustfix` is now just `cargo fix` and distributed directly with Cargo. * Update that enabling the 2018 edition doesn't enable any warnings, but mention the `rust_2018_idioms` lint which does indeed enable warnings. * Tweak some wording here and there with recent tweaks to the workflow
|
Updated! |
|
Looks all good to me now :) |
alexcrichton
changed the title
|
This is in nightly now, yay! |
rustfixis now justcargo fixand distributed directly withCargo.
the
rust_2018_idiomslint which does indeed enable warnings.