apply various edits from the PR thread

Author: nikomatsakis

text/0000-edition-2021.md

@@ -13,7 +13,7 @@ Key points include:
 * Editions are used to introduce changes into the language that would otherwise have the potential to break existing code, such as the introduction of a new keyword.
 * Editions are never allowed to split the ecosystem. We only permit changes that still allow crates in different editions to interoperate.
 * Editions are named after the year in which they occur (e.g., Rust 2015, Rust 2018, Rust 2021).
-* When we release a new edition, we also release tooling to automate the migration of crates. Some manual work may be required but that should be the rare case.
+* When we release a new edition, we also release tooling to automate the migration of crates. Some manual work may be required but that should be uncommon.
 * The nightly toolchain offers "preview" access to upcoming editions, so that we can land work that targets future editions at any time.
 * We maintain an Edition Migration Guide that offers guidance on how to migrate to the next edition.
 * Whenever possible, new features should be made to work across all editions.
@@ -25,26 +25,26 @@ This RFC is meant to establish the high-level purpose of an edition and to descr
 # Motivation
 [motivation]: #motivation
 
-The plan for editions was laid out in [RFC 2052] and Rust had its first edition in 2018. This effort was in many ways a success but also resulted in some difficult lessons. This RFC proposes a different model for the 2021 Edition. Depending on our experience, we may opt to continue with this model in the future, or we may wish to make changes for future editions.
+The plan for editions was laid out in [RFC 2052] and Rust had its first edition in 2018. This effort was in many ways a success but also resulted in a lot of stress on the Rust organization as a whole. This RFC proposes a different model for the 2021 Edition. Depending on our experience, we may opt to continue with this model in the future, or we may wish to make changes for future editions.
 
 ## Editions enable "stability without stagnation"
 
 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 in the surface syntax of Rust that would not otherwise be backwards compatible. The most obvious example is introducing a new keyword, which would invalidate existing names for variables and so forth. Even when such changes do not "feel" backwards incompatible, they still have the potential to break existing code. If we were to make such changes, people would quickly find that existing programs stopped compiling.
 
-**Editions** are the mechanism we use to square this circle. When we wish 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. 
+**Editions** are the mechanism we use to square this circle. When we wish 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. New creates created by cargo always default to the most recent edition.
 
 # Guide-level explanation
 [guide-level-explanation]: #guide-level-explanation
 
-The follow sections define the goals and design principles that we will use for the 2021 edition, and potentially for future editions. The ordering is significant, with earlier sections taking precedence in the case of a conflict. (For example, it's more important that users are able to control when they adopt the new edition than it is for the edition to be rapidly adopted.)
+The following sections define the goals and design principles that we will use for the 2021 edition, and potentially for future editions. The ordering is significant, with earlier sections taking precedence in the case of a conflict. (For example, it's more important that users are able to control when they adopt the new edition than it is for the edition to be rapidly adopted.)
 
 ## 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, apart from the fact that it affects the version of rustc that is required, akin to making use of any new feature.
 
-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 a edition tend to be "skin deep". All Rust code, regardless of edition, is ultimately compiled to the same internal IR within the compiler.
+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
 
@@ -85,27 +85,31 @@ This RFC explicitly does not attempt to specify the cadence for releasing editio
 
 There are various constraints on the timing of editions that have been identified over time:
 
-* Even if it's automated, migrating to a new edition can require a significant investment of time, particularly for production users with many crates. We don't wish to release Editions at a rate that makes it hard for such users to keep up.
+* Even if it's automated, migrating to a new edition can require a significant investment of time, particularly for production users with many crates. We don't wish to release editions at a rate that makes it hard for such users to keep up.
 * At the same time, we don't wish to wait too long in between editions. We want to maintain the spirit of Rust's train model, so that folks don't feel a "rush" to get work done by any particular deadline.
 * Having a generally known time when editions will be released is helpful in planning feature development.
 * We do not wish to release an empty edition. Sometimes there simply won't be any backwards incompatible changes and thus no reason to issue an edition.
 
 ## Definition: migration
 
-**Migrations** are the "breaking changes" introduced by the edition, except of course that since editions are opt-in, no code actually breaks. 
+**Migrations** are the "breaking changes" introduced by the edition; of course, since editions are opt-in, existing code does not actually break.
 
 ## Definition: migration lint
 
 Migrations typically come with one or more **migration lints**. Each lint warns about code that will need to change in order to move to the new edition. The lints typically contain "suggestions", which is a diff that can be applied to make the code work in the new edition. In some cases, the rewrite may be too complex for the lint to make a suggestion. In addition, some suggestions are marked as "not machine applicable", if they are not known to be semantics preserving.
 
+## Default edition for new projects
+
+The default edition for new projects will be 2021.
+
 ## Tooling workflow
 
 The expected workflow for upgrading to a new edition is as follows:
 
 * **Prepare to upgrade:** Run `cargo fix --edition`: This will automatically prepare your code to be upgraded to next edition by applying any suggestions from the migration lints.
     * For example, if your code is in Rust 2018, this will prepare you to move to the 2021 edition.
     * Note that `cargo fix` does not actually move your code to the new edition. Instead, it produces code that works in both the old and the new edition.
-        * This allows people to upgrade and fix things in a "piecemeal" fashion. Because of this, however, the code produces by these suggestions is not always the most idiomatic, as it is not able to take advantage of features from the new edition.
+        * This allows people to upgrade and fix things in a "piecemeal" fashion. Because of this, however, the code produced by these suggestions is not always the most idiomatic, as it is not able to take advantage of features from the new edition.
     * The expectation is that `cargo fix` should be able to fix the majority of crates out there, but it is not required that the tooling is able to handle every case. As long as code does not occur frequently in the wild, it is acceptable for the automated suggestions to be inapplicable to edge cases. The metrics section in this RFC includes some guidelines for how to measure this.
 * **Upgrade:** Edit your cargo.toml to include `edition = "2021"` instead of the older edition.
     * The code should still build, but it may be necessary to make some fixes or other changes.
@@ -122,7 +126,7 @@ Some examples of changes the editions can make:
 * Introducing a new keyword, as with `async-await`.
     * This change comes with automated tooling that rewrites identifiers using that keyword to use `r#` form.
 * Changing closures so that they capture precise paths, rather than entire variables, as in [RFC 2229].
-    * This change comes with automated tooling that modifies closures to capture 
+    * This change comes with automated tooling that modifies closures to capture entire variables when necessary.
     * In MIR, closures are desugared into structs with fields, so all editions can still target the same internal representation.
 * Changing the prelude for Rust code.
 * Changing type inference rules.
@@ -172,7 +176,7 @@ The following metrics are an attempt to quantify some of the goals we have for e
 # Drawbacks
 [drawbacks]: #drawbacks
 
-Executing an edition requires coordination. There has also been some concern that Rust is making too many changes and moving too quickly, and releasing a new edition could feed those narratives. On the other hand, the fact that this edition is relatively limited in scope and that it will be marketed less aggressively also helps here. Further, continuing the regular cadence for editions has its own advantages, and helps us to make some changes (such as closure capture or format printing) that are very valuable.
+Executing an edition requires coordination. There has also been some concern that Rust is making too many changes and moving too quickly, and releasing a new edition could feed those fears. On the other hand, the fact that this edition is relatively limited in scope and that it will be marketed less aggressively also helps here. Further, continuing the regular cadence for editions has its own advantages, and helps us to make some changes (such as closure capture or format printing) that are very valuable.
 
 # Rationale and alternatives
 [rationale-and-alternatives]: #rationale-and-alternatives