Document how to transition between editions #4

steveklabnik · 2018-05-09T20:41:16Z

alexcrichton · 2018-05-09T21:09:05Z

src/editions/transitioning.md

+```
+
+And that's it! Note that you do need a nightly Cargo to use `rustfix` at the


Technically you don't actually need a nightly Cargo for rustfix, it's just a nightly rustc currently. As an implementation detail though cargo-fix purely delegates to cargo check, which does end up transitively and effectively requiring nightly.

In any case though the +nightly on the cargo install in theory shouldn't be necessary even today!

killercup

LGTM. Maybe you can also remind people to commit their changes before running cargo-fix so they easily roll back?

killercup · 2018-05-09T20:57:51Z

src/editions/transitioning.md

+
+```shell
+$ cargo +nightly install cargo-fix --git https://github.com/killercup/rustfix.git


the official repo is https://github.com/rust-lang-nursery/rustfix

killercup · 2018-05-09T20:58:45Z

src/editions/transitioning.md

+
+And that's it! Note that you do need a nightly Cargo to use `rustfix` at the
+moment; in fact, all of the edition stuff is nightly only for now. Eventually


"nightly-only" or "nightly only"?

alexcrichton · 2018-05-09T21:12:03Z

src/editions/transitioning.md

+## Prepare for the next edition
+
+There are some lints that can help you prepare for the next edition, but


It may be worth re-emphasizing a few points here as well:

The 2018 edition has some features that are exclusive to it, aka not available in the 2015 edition. For example async/await.

It's our intention that the migration to the 2018 is as smooth an experience as possible. It's a technical breaking change so it must be opt-in, but we want to make it as easy as possible for you to opt in so you can get access to the new features. (hence cargo fix)

It's considered a bug if it's difficult to upgrade your crate to the 2018 edition. If you have a difficult time then a bug should be filed with either rustfix or rust-lang/rust

Also, as we've just seen, for the preview you'll need to opt into some unstable features that will become stable in both 2015 and 2018 soon to actually get something that cargo-fix will fix (#![feature(crate_in_paths)], for example).

(Correct me if I'm wrong, @Manishearth)

Yes, I mentioned this in gitter. We should ask people to use #![feature(crate_in_paths)] before they trigger rustfix

We can also change https://github.com/rust-lang/rust/blob/master/src/librustc_resolve/lib.rs#L3354-L3355 to no longer require crate_in_paths, but they need to add it anyway so it's not that useful? I'm less fond of the idea of lints that suggest broken code (which is what it is until crate_in_paths stabilizes)

After some gitter discussion I've added a new step to the cheat sheet where for the preview only users will be required to list #![feature(rust_2018_preview)] in their crates they wish to migrate.

steveklabnik · 2018-05-14T19:18:53Z

I've updated this a bit. r? anyone?

killercup

Commented on some stuff I'd clarify

killercup · 2018-05-14T19:25:25Z

src/editions/transitioning.md

+## Installing rustfix
+
+You can get `rustfix` from crates.io. Given that you're probably using Cargo,


from crates.io

well, we're actually getting it from github.com right now

killercup · 2018-05-14T19:27:06Z

src/editions/transitioning.md

+
+
+* New editions may have features that are only available in the new edition.


New editions may have features that are only available in the new edition.

That sounds… obvious. How about

New editions may introduce features that are available in that form in previous editions.

This is what @alexcrichton suggested above; the opposite is also true, idk 😆

Lol, true. Okay, how about this: "New editions might change the way you write Rust -- the add syntax, language, and library features but also remove others."

killercup · 2018-05-14T19:30:23Z

src/editions/transitioning.md

+  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


difficult

That is a super opaque and undefined metric. It's cool if you don't want to be more specific, but I'd add something like

What do we mean by "difficult"? Migration code in macros for example: The compiler often can't directly determine how the code might be used and thus can't provide a way to upgrade in a straightforward way.

I personally like this sort of being opaque and undefined in the sense that if you feel it's difficult that's a bug we want to know about and fix. It'll definitely be a lot of work for us to bottom out "what makes it difficult" in some situations, but no one should ever get the impression that an edition upgrade is difficult ideally

Yes, I think for now I'd like to leave this vague. As we get closer to shipping, we'll know better what those pain points are.

killercup · 2018-05-14T19:31:13Z

src/editions/transitioning.md

+```
+
+This will ensure that you're enabling all of the relevant features.


This is currently relevant and I'd add

Note that during the time the preview is available, we may continue to add/enable new features with this flag!

killercup · 2018-05-14T19:32:11Z

src/editions/transitioning.md

+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 warning will be printed; you'll need to fix those manually. Do so


the [usual compiler] warning will be printed

killercup · 2018-05-14T19:33:08Z

src/editions/transitioning.md

+
+```shell
+$ cargo +nightly fix --prepare-for 2018


Assumes people use rustup -- fine but should be mentioned

killercup · 2018-05-14T19:34:21Z

src/editions/transitioning.md

+```
+
+This will fix up all of the new warnings. Congrats! You're done!


This will [try to] fix

Same drill as above regarding manual fixes (can be downplayed)

alexcrichton · 2018-05-14T21:53:15Z

src/editions/transitioning.md

+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 build`.


s/cargo build/cargo +nightly build/

alexcrichton · 2018-05-14T21:53:46Z

Looks great, thanks @steveklabnik!

steveklabnik · 2018-05-16T20:07:33Z

Thanks for the review yinz <3

Circle CIの有効化 -- その2

alexcrichton reviewed May 9, 2018

View reviewed changes

killercup approved these changes May 9, 2018

View reviewed changes

alexcrichton reviewed May 9, 2018

View reviewed changes

killercup reviewed May 14, 2018

View reviewed changes

alexcrichton reviewed May 14, 2018

View reviewed changes

steveklabnik added 3 commits May 16, 2018 15:57

Document how to transition between editions

ea6fb58

fixes from feedback

5d2baf0

moar review feedback

325d3df

steveklabnik force-pushed the upgrade-docs branch from bf90471 to 325d3df Compare May 16, 2018 20:02

steveklabnik merged commit b1b997b into master May 16, 2018

steveklabnik deleted the upgrade-docs branch May 16, 2018 20:07

tsraom pushed a commit to tsraom/edition-guide that referenced this pull request Aug 19, 2018

Merge pull request rust-lang#4 from tatsuya6502/circleci-2.0

89fecb8

Circle CIの有効化 -- その2

		```

		And that's it! Note that you do need a nightly Cargo to use `rustfix` at the


		```shell
		$ cargo +nightly install cargo-fix --git https://github.com/killercup/rustfix.git


		And that's it! Note that you do need a nightly Cargo to use `rustfix` at the
		moment; in fact, all of the edition stuff is nightly only for now. Eventually

		## Prepare for the next edition

		There are some lints that can help you prepare for the next edition, but

		## Installing rustfix

		You can get `rustfix` from crates.io. Given that you're probably using Cargo,



		* New editions may have features that are only available in the new edition.

		```

		This will ensure that you're enabling all of the relevant features.

		```

		This will fix up all of the new warnings. Congrats! You're done!

		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 build`.

Document how to transition between editions #4

Document how to transition between editions #4

Uh oh!

Conversation

steveklabnik commented May 9, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

killercup left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

steveklabnik commented May 14, 2018

Uh oh!

killercup left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

killercup May 14, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alexcrichton commented May 14, 2018

Uh oh!

steveklabnik commented May 16, 2018

Uh oh!

Uh oh!

killercup May 14, 2018 •

edited

Loading