From e6ab811972ce8d6d6d07b98d16ec1ce4c43bb156 Mon Sep 17 00:00:00 2001 From: Alex Crichton Date: Tue, 17 Jul 2018 12:10:19 -0700 Subject: [PATCH] Tweak and update the transition guide * 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 --- src/editions/index.md | 27 +------- src/editions/transitioning.md | 114 ++++++++++++++++++---------------- 2 files changed, 65 insertions(+), 76 deletions(-) diff --git a/src/editions/index.md b/src/editions/index.md index e5390332..da28931d 100644 --- a/src/editions/index.md +++ b/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). diff --git a/src/editions/transitioning.md b/src/editions/transitioning.md index ac3e5521..7a6f82ef 100644 --- a/src/editions/transitioning.md +++ b/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! \ No newline at end of file +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!