Minimize the edition guide

src/SUMMARY.md

@@ -15,92 +15,20 @@
 ## Rust 2018
 
 - [Rust 2018](rust-2018/index.md)
-    - [2018-Specific Changes](rust-2018/edition-changes.md)
-    - [Module system](rust-2018/module-system/index.md)
-      - [Raw identifiers](rust-2018/module-system/raw-identifiers.md)
-      - [Path clarity](rust-2018/module-system/path-clarity.md)
-      - [More visibility modifiers](rust-2018/module-system/more-visibility-modifiers.md)
-      - [Nested imports with `use`](rust-2018/module-system/nested-imports-with-use.md)
-    - [Error handling and panics](rust-2018/error-handling-and-panics/index.md)
-      - [The `?` operator for easier error handling](rust-2018/error-handling-and-panics/the-question-mark-operator-for-easier-error-handling.md)
-      - [`?` in `main` and tests](rust-2018/error-handling-and-panics/question-mark-in-main-and-tests.md)
-      - [Controlling panics with `std::panic`](rust-2018/error-handling-and-panics/controlling-panics-with-std-panic.md)
-      - [Aborting on panic](rust-2018/error-handling-and-panics/aborting-on-panic.md)
-    - [Control flow](rust-2018/control-flow/index.md)
-      - [Loops can `break` with a value](rust-2018/control-flow/loops-can-break-with-a-value.md)
-      - [`async`/`await` for easier concurrency](rust-2018/control-flow/async-await-for-easier-concurrency.md)
-    - [Trait system](rust-2018/trait-system/index.md)
-      - [`impl Trait` for returning complex types with ease](rust-2018/trait-system/impl-trait-for-returning-complex-types-with-ease.md)
-      - [`dyn Trait` for trait objects](rust-2018/trait-system/dyn-trait-for-trait-objects.md)
-      - [More container types support trait objects](rust-2018/trait-system/more-container-types-support-trait-objects.md)
-      - [Associated constants](rust-2018/trait-system/associated-constants.md)
-      - [No more anonymous parameters](rust-2018/trait-system/no-anon-params.md)
-    - [Slice patterns](rust-2018/slice-patterns.md)
-    - [Ownership and lifetimes](rust-2018/ownership-and-lifetimes/index.md)
-      - [Non-lexical lifetimes](rust-2018/ownership-and-lifetimes/non-lexical-lifetimes.md)
-      - [Default `match` bindings](rust-2018/ownership-and-lifetimes/default-match-bindings.md)
-      - [`'_`, the anonymous lifetime](rust-2018/ownership-and-lifetimes/the-anonymous-lifetime.md)
-      - [Lifetime elision in `impl`](rust-2018/ownership-and-lifetimes/lifetime-elision-in-impl.md)
-      - [`T: 'a` inference in structs](rust-2018/ownership-and-lifetimes/inference-in-structs.md)
-      - [Simpler lifetimes in `static` and `const`](rust-2018/ownership-and-lifetimes/simpler-lifetimes-in-static-and-const.md)
-    - [Data types](rust-2018/data-types/index.md)
-      - [Field init shorthand](rust-2018/data-types/field-init-shorthand.md)
-      - [`..=` for inclusive ranges](rust-2018/data-types/inclusive-ranges.md)
-      - [128 bit integers](rust-2018/data-types/128-bit-integers.md)
-      - ["Operator-equals" are now implementable](rust-2018/data-types/operator-equals-are-now-implementable.md)
-      - [`union` for an unsafe form of `enum`](rust-2018/data-types/union-for-an-unsafe-form-of-enum.md)
-      - [Choosing alignment with the `repr` attribute](rust-2018/data-types/choosing-alignment-with-the-repr-attribute.md)
-    - [SIMD for faster computing](rust-2018/simd-for-faster-computing.md)
-    - [Macros](rust-2018/macros/index.md)
-      - [Custom Derive](rust-2018/macros/custom-derive.md)
-      - [Macro changes](rust-2018/macros/macro-changes.md)
-      - [At most one repetition](rust-2018/macros/at-most-once.md)
-    - [The compiler](rust-2018/the-compiler/index.md)
-      - [Improved error messages](rust-2018/the-compiler/improved-error-messages.md)
-      - [Incremental Compilation for faster compiles](rust-2018/the-compiler/incremental-compilation-for-faster-compiles.md)
-      - [An attribute for deprecation](rust-2018/the-compiler/an-attribute-for-deprecation.md)
-    - [Rustup for managing Rust versions](rust-2018/rustup-for-managing-rust-versions.md)
-    - [Cargo and crates.io](rust-2018/cargo-and-crates-io/index.md)
-      - [`cargo check` for faster checking](rust-2018/cargo-and-crates-io/cargo-check-for-faster-checking.md)
-      - [`cargo install` for easy installation of tools](rust-2018/cargo-and-crates-io/cargo-install-for-easy-installation-of-tools.md)
-      - [`cargo new` defaults to a binary project](rust-2018/cargo-and-crates-io/cargo-new-defaults-to-a-binary-project.md)
-      - [`cargo rustc` for passing arbitrary flags to `rustc`](rust-2018/cargo-and-crates-io/cargo-rustc-for-passing-arbitrary-flags-to-rustc.md)
-      - [Cargo workspaces for multi-package projects](rust-2018/cargo-and-crates-io/cargo-workspaces-for-multi-package-projects.md)
-      - [Multi-file `examples`](rust-2018/cargo-and-crates-io/multi-file-examples.md)
-      - [Replacing dependencies with `patch`](rust-2018/cargo-and-crates-io/replacing-dependencies-with-patch.md)
-      - [Cargo can use a local registry replacement](rust-2018/cargo-and-crates-io/cargo-can-use-a-local-registry-replacement.md)
-      - [Crates.io disallows wildcard dependencies](rust-2018/cargo-and-crates-io/crates-io-disallows-wildcard-dependencies.md)
-    - [Documentation](rust-2018/documentation/index.md)
-      - [New editions of the "the book"](rust-2018/documentation/new-editions-of-the-book.md)
-      - [The Rust Bookshelf](rust-2018/documentation/the-rust-bookshelf.md)
-      - [The Rustonomicon](rust-2018/documentation/the-rustonomicon.md)
-      - [Full documentation for `std::os`](rust-2018/documentation/std-os-has-documentation-for-all-platforms.md)
-    - [`rustdoc`](rust-2018/rustdoc/index.md)
-      - [Documentation tests can now `compile-fail`](rust-2018/rustdoc/documentation-tests-can-now-compile-fail.md)
-      - [Rustdoc uses CommonMark](rust-2018/rustdoc/rustdoc-uses-commonmark.md)
-    - [Platform and target support](rust-2018/platform-and-target-support/index.md)
-      - [`libcore` for low-level Rust](rust-2018/platform-and-target-support/libcore-for-low-level-rust.md)
-      - [WebAssembly support](rust-2018/platform-and-target-support/webassembly-support.md)
-      - [Global allocators](rust-2018/platform-and-target-support/global-allocators.md)
-      - [MSVC toolchain support](rust-2018/platform-and-target-support/msvc-toolchain-support.md)
-      - [MUSL support for fully static binaries](rust-2018/platform-and-target-support/musl-support-for-fully-static-binaries.md)
-      - [`cdylib` crates for C interoperability](rust-2018/platform-and-target-support/cdylib-crates-for-c-interoperability.md)
-
-## The Next Edition
-
-- [The Next Edition](rust-next/index.md)
-    - [Next-Specific Changes](rust-next/edition-changes.md)
-    - [The dbg! macro](rust-next/dbg-macro.md)
-    - [No jemalloc by default](rust-next/no-jemalloc.md)
-    - [Uniform Paths](rust-next/uniform-paths.md)
-    - [`literal` macro matcher](rust-next/literal-macro-matcher.md)
-    - [`?` operator in macros](rust-next/qustion-mark-operator-in-macros.md)
-    - [const fn](rust-next/const-fn.md)
-    - [Pinning](rust-next/pin.md)
-    - [No more FnBox](rust-next/no-more-fnbox.md)
-    - [Alternative Cargo Registries](rust-next/alternative-cargo-registries.md)
-    - [TryFrom and TryInto](rust-next/tryfrom-and-tryinto.md)
-    - [The Future trait](rust-next/future.md)
-    - [The alloc crate](rust-next/alloc.md)
-    - [MaybeUninit<T>](rust-next/maybe-uninit.md)
-    - [cargo vendor](rust-next/cargo-vendor.md)
+  - [Path and module system changes](rust-2018/path-changes.md)
+  - [Anonymous trait function parameters deprecated](rust-2018/trait_fn_parameters.md)
+  - [New keywords](rust-2018/new_keywords.md)
+  - [Method dispatch for raw pointers to inference variables](rust-2018/tyvar_behind_raw_pointer.md)
+  - [Cargo changes](rust-2018/cargo.md)
+
+## Rust 2021
+
+- [Rust 2021 🚧](rust-2021/index.md)
+  - [Additions to the prelude](rust-2021/prelude.md)
+  - [Default Cargo feature resolver](rust-2021/default_cargo_resolver.md)
+  - [IntoIterator for arrays](rust-2021/IntoIterator_for_arrays.md)
+  - [Disjoint capture in closures](rust-2021/disjoint_capture_in_closures.md)
+  - [Panic macro consistency](rust-2021/panic_macro_consistency.md)
+  - [Reserving syntax](rust-2021/reserving_syntax.md)
+  - [Warnings promoted to errors](rust-2021/warnings_promoted_to_error.md)
+  - [Or patterns in macro-rules](rust-2021/or_patterns_macro_rules.md)

src/editions/index.md

@@ -1,43 +1,61 @@
 # What are Editions?
 
-Rust ships releases on a six-week cycle. This means that users get a constant
-stream of new features. This is much faster than updates for other languages,
-but this also means that each update is smaller.  After a while, all of those
-tiny changes add up. But, from release to release, it can be hard to look back
-and say *"Wow, between Rust 1.10 and Rust 1.20, Rust has changed a lot!"*
-
-Every two or three years, we'll be producing a new *edition* of Rust. Each
-edition brings together the features that have landed into a clear package, with
-fully updated documentation and tooling. New editions ship through the usual
-release process.
-
-This serves different purposes for different people:
-
-- For active Rust users, it brings together incremental changes into an
-  easy-to-understand package.
-
-- For non-users, it signals that some major advancements have landed, which
-  might make Rust worth another look.
-
-- For those developing Rust itself, it provides a rallying point for the project as a
-  whole.
-
-## Compatibility
-
-When a new edition becomes available in the compiler, crates must explicitly opt
-in to it to take full advantage. This opt in enables editions to contain
-incompatible changes, like adding a new keyword that might conflict with
-identifiers in code, or turning warnings into errors. A Rust compiler will
-support all editions that existed prior to the compiler's release, and can link
-crates of any supported editions together.
-Edition changes only affect the way the compiler initially parses the code.
-Therefore, if you're using Rust 2015, and
-one of your dependencies uses Rust 2018, it all works just fine. The opposite
-situation works as well.
-
-Just to be clear: most features will be available on all editions.
-People using any edition of Rust will continue to see improvements as new
-stable releases are made.  In some cases however, mainly when new keywords are
-added, but sometimes for other reasons, there may be new features that are only
-available in later editions.  You only need to upgrade if you want to take
-advantage of such features.
+The release of Rust 1.0 established
+["stability without stagnation"](https://blog.rust-lang.org/2014/10/30/Stability.html)
+as a core Rust deliverable.
+Ever since the 1.0 release,
+the rule for Rust has been that once a feature has been released on stable,
+we are committed to supporting that feature for all future releases.
+
+There are times, however, when it is useful to be able to make small changes
+to the language that are not backwards compatible.
+The most obvious example is introducing a new keyword,
+which would invalidate variables with the same name.
+For example, the first version of Rust did not have the `async` and `await` keywords.
+Suddenly changing those words to keywords in a later version would've broken code like `let async = 1;`.
+
+**Editions** are the mechanism we use to solve this problem.
+When we want to release a feature that would otherwise be backwards incompatible,
+we do so as part of a new Rust *edition*.
+Editions are opt-in, and so existing crates do
+not see these changes until they explicitly migrate over to the new edition.
+This means that even the latest version of Rust will still *not* treat `async` as a keyword,
+unless edition 2018 or later is chosen.
+This choice is made *per crate* [as part of its `Cargo.toml`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-edition-field).
+New crates created by `cargo new` are always configured to use the latest stable edition.
+
+### Editions do not split the ecosystem
+
+The most important rule for editions is that crates in one edition can
+interoperate seamlessly with crates compiled in other editions. This ensures
+that the decision to migrate to a newer edition is a "private one" that the
+crate can make without affecting others.
+
+The requirement for crate interoperability implies some limits on the kinds of
+changes that we can make in an edition.
+In general, changes that occur in an edition tend to be "skin deep".
+All Rust code, regardless of edition,
+is ultimately compiled to the same internal representation within the compiler.
+
+### Edition migration is easy and largely automated
+
+Our goal is to make it easy for crates to upgrade to a new edition.
+When we release a new edition,
+we also provide [tooling to automate the migration](https://doc.rust-lang.org/cargo/commands/cargo-fix.html).
+It makes minor changes to your code necessary to make it compatible with the new edition.
+For example, when migrating to Rust 2018, it changes anything named `async` to use the equivalent
+[raw identifier syntax](https://doc.rust-lang.org/rust-by-example/compatibility/raw_identifiers.html): `r#async`.
+
+The automated migrations are not necessarily perfect:
+there might be some corner cases where manual changes are still required.
+The tooling tries hard to avoid changes
+to semantics that could affect the correctness or performance of the code.
+
+In addition to tooling, we also maintain this Edition Migration Guide that covers
+the changes that are part of an edition.
+This guide describes each change and gives pointers to where you can learn more about it.
+It also covers any corner cases or details you should be aware of.
+This guide serves both as an overview of the edition
+and as a quick troubleshooting reference
+if you encounter problems with the automated tooling.
+

src/editions/transitioning-an-existing-project-to-a-new-edition.md

@@ -7,7 +7,7 @@ have a project that's using Rust 2015, and you'd like to use Rust 2018 for it
 instead, there's a few steps that you need to take.
 
 > It's our intention that the migration to new editions is as smooth an
-> experience as possible. If it's difficult for you to upgrade to Rust 2018,
+> experience as possible. If it's difficult for you to upgrade to the latest edition,
 > we consider that a bug. If you run into problems with this process, please
 > [file a bug](https://github.com/rust-lang/rust/issues/new). Thank you!
 

src/introduction.md

@@ -1,16 +1,11 @@
 # Introduction
 
-Welcome to the Rust Edition Guide! "Editions" are Rust's way of communicating
-large changes in the way that it feels to write Rust code.
+Welcome to the Rust Edition Guide! "Editions" are Rust's way of introducing
+changes into the language that would not otherwise be backwards
+compatible.
 
 In this guide, we'll discuss:
 
 * What editions are
-* What each edition is about
+* Which changes are contained in each edition
 * How to migrate your code from one edition to another
-
-Note that the standard library grows with each Rust release; there are *many*
-additions to the standard library that are not called out in this guide. Only
-the major ones are, but there's tons of medium and small things that are
-great too. You may want to check out [the standard library
-documentation](https://doc.rust-lang.org/std/) as well.