Tweak and update the transition guide

src/editions/index.md

@@ -42,27 +42,6 @@ You only need to upgrade if you want to take advantage of such features.
 ## Trying out the 2018 edition
 
 At the time of writing, there are two editions: 2015 and 2018. 2015 is today's
-Rust; Rust 2018 will ship later this year. To give Rust 2018 a try, you can
-add this feature to your crate root:
-
-```rust
-// Opt in to unstable features expected for Rust 2018
-#![feature(rust_2018_preview)]
-
-// Opt in to warnings about new 2018 idioms
-#![warn(rust_2018_idioms)]
-```
-
-and opt in to the new edition in your `Cargo.toml`:
-
-```toml
-cargo-features = ["edition"]
-
-[package]
-edition = '2018'
-```
-
-Like all `#![feature(..)]` flags, this will only work on nightly Rust.
-When nightly compilers are released, more functionality is enabled,
-so you may experience new warnings, features, and other things.
-This is something to keep in mind and is exactly why nightly is unstable!
+Rust; Rust 2018 will ship later this year. To transition to the 2018 edition
+from the 2015 edition, you'll want to get started with the [transition
+guide](editions/transitioning.html).

src/editions/transitioning.md

@@ -1,47 +1,32 @@
 # 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 new syntax,
+language, and library features but also remove features. For example,
+`async`/`await` are keywords in Rust 2018, but not Rust 2015. Despite this
+it's our intention that the migration to new editions is as smooth an experience
+as possible. It's considered a bug if it's difficult to upgrade your crate to a
+new edition. If you have a difficult time then a bug should be filed with Rust
+itself.
+
+Transitioning between editions is built around compiler lints. Fundamentally,
+the process works like this:
+
+* Turn on lints to indicate where code is incompatible with a new edition
 * Get your code compiling with no warnings.
-* Opt in to the new edition.
-* Fix any new warnings that may result.
-
-Luckily, we've been working on a tool to help assist with this process,
-`rustfix`. It can take suggestions from the compiler and automatically
-re-write your code to comply with new features and idioms.
-
-> `rustfix` is still quite young, and very much a work in development. But it works
-> for the basics! We're working hard on making it better and more robust, but
-> please bear with us for now.
-
-## Installing rustfix
-
-You can get `rustfix` from GitHub, and eventually, `crates.io`. Given that you're probably using Cargo,
-you'll want to run this:
-
-```shell
-$ cargo install cargo-fix
-```
-
-And that's it!
-
-## Prepare for the next edition
-
-Before we talk about how to move to the new edition, a reminder:
-
+* Opt in to the new edition, the code should compile.
+* Optionally, enable lints about *idiomatic* code in the new edition.
 
-* New editions might change the way you write Rust -- they add syntax,
-  language, and library features but also remove others. For example,
-  `async`/`await` is available in Rust 2018, but not Rust 2015.
-* It's our intention that the migration to new editions is as smooth an experience
-  as possible. It's considered a bug if it's difficult to upgrade your crate to
-  a new edition. If you have a difficult time then a bug should be filed
-  with either rustfix or Rust itself.
+Luckily, we've been working on Cargo to help assist with this process,
+culminating in a new built-in subcommand `cargo fix`. It can take suggestions
+from the compiler and automatically re-write your code to comply with new
+features and idioms, drastically reducing the number of warnings you need to fix
+manually!
 
-With that out of the way, let's get into it!
+> `cargo fix` is still quite young, and very much a work in development. But it
+> works for the basics! We're working hard on making it better and more robust,
+> but please bear with us for now.
 
-### The preview period
+## The preview period
 
 First, editions have a "preview" phase. This lets you try out the new edition
 in nightly Rust. During the preview, there's an extra step you need to take
@@ -57,20 +42,29 @@ This will ensure that you're enabling all of the relevant features. Note that
 during the time the preview is available, we may continue to add/enable new
 features with this flag!
 
-### Running rustfix
+## Fix edition compatibility warnings
 
-There are some lints that can help you prepare for the next edition, but
-they're not currently turned on by default. `rustfix` has your back though!
-To turn them on and have `rustfix` fix up your code, run this:
+Next up is to enable compiler warnings about code which is incompatible with the
+new 2018 edition. This is where the handy `cargo fix` tool comes into the
+picture. To enable the compatibility lints for your project you run:
 
 ```shell
-$ cargo +nightly fix --prepare-for 2018
+$ cargo +nightly fix --prepare-for 2018 --all-targets --all-features
 ```
 
-This would turn on those lints, and fix up the project for the 2018 edition.
-If there's something that `rustfix` doesn't know how to fix automatically yet,
-the usual compiler warning will be printed; you'll need to fix those
-manually. Do so until you get a run with no warnings.
+This will instruct Cargo to compile all targets in your project (libraries,
+binaries, tests, etc.) while enabling all Cargo features and prepare them for
+the 2018 edition. Cargo will likely automatically fix a number of files,
+informing you as it goes along.
+
+If Cargo can't automatically fix everything it'll print out the remaining
+warnings. Continue to run the above command until all warnings have been solved.
+
+You can explore more about the `cargo fix` command with:
+
+```shell
+$ cargo +nightly fix --help
+```
 
 ## Commit to the next edition
 
@@ -89,15 +83,31 @@ the `[package]` section. As mentioned above, right now this is a nightly-only
 feature of Cargo, so you need to enable it for things to work.
 
 At this point, your project should compile with a regular old `cargo +nightly
-build`. However, since you've said you're using the new edition, you may get
-more warnings! Time to bust out `rustfix` again.
+build`. If it does not, this is a bug! Please [file an issue][issue].
+
+[issue]: https://github.com/rust-lang/rust/issues/new
 
-## Fix new warnings
+## Writing idiomatic code in a new edition
+
+Your crate has now entered the 2018 edition of Rust, congrats! Recall though
+that Editions in Rust signify a shift in idioms over time. While much old
+code will continue to compile it might be written with different idioms today.
+
+An optional next step you can take is to update your code to be idiomatic within
+the new edition. This is done with a different set of "idiom lints". To enable
+these lints add this to your `lib.rs` or `main.rs`:
+
+```rust
+#![warn(rust_2018_idioms)]
+```
 
-To fix up these warnings, we can use `rustfix`:
+and then execute:
 
 ```shell
 $ cargo +nightly fix
 ```
 
-This will try to fix up all of the new warnings. Congrats! You're done!
+As before Cargo will automatically fix as much as it can, but you may also need
+to fix some warnings manually. Once all warnings have been solved you're not
+only compiling with the 2018 edition but you're also already writing idiomatic
+2018 code!