Add introductory text for editions #393
Conversation
| @@ -0,0 +1,39 @@ | |||
| # Editions | |||
|
|
|||
| Before we get into the details of the language itself, we need to cover the | |||
There was a problem hiding this comment.
The general flow of the reference, as it stands today, is that you can jump in on any page. Unlike The Book, the reference assumes you know Rust well enough that you should be able to jump to any page and then link around to concepts you don't know. This paragraph seems to imply that the reference should be read from front to end, which is a change to that concept. If we don't want to change that, it'd be best to just remove this paragraph.
| * Default to the 2015 edition if no edition is selected. | ||
|
|
||
| The reference follows this guideline; everything stated in this document is | ||
| part of the 2015 edition unless specifically marked otherwise. |
There was a problem hiding this comment.
This seems like a good policy for now, given how small the actual "made into an error" class of things is.
| Before we get into the details of the language itself, we need to cover the | ||
| concept of an "edition." | ||
|
|
||
| An "edition" of Rust consists of a particular year. There are two editions of |
There was a problem hiding this comment.
Nit: Change "edition" to *edition*.
Not nit: Although really, we want the defining sentence to summarize the feature even if its gets expanded on later. See the comment on the core definition below for more on that.
| Before we get into the details of the language itself, we need to cover the | ||
| concept of an "edition." | ||
|
|
||
| An "edition" of Rust consists of a particular year. There are two editions of |
There was a problem hiding this comment.
Nit: "of Rust" is redundant in both places.
| * Rust 2015 | ||
| * Rust 2018 | ||
|
|
||
| Conforming compilers are expected to: |
There was a problem hiding this comment.
The reference isn't a specification (even if it's the closest to a specification we have), so we can't say what a conforming compiler is from that perspective and we don't have a specification. So we don't really have a definition of what a conforming compiler can be outside the reference and we don't want to define that here either. We can talk about "The compiler" referring to rustc. We're pretty much pretending no other compiler exists at this time.
| The reference follows this guideline; everything stated in this document is | ||
| part of the 2015 edition unless specifically marked otherwise. | ||
|
|
||
| ## What editions can change |
There was a problem hiding this comment.
This feels like the core definition of an edition, and IMO, should be before the list of years. We're also missing that it's a per-crate setting. And we want to talk about them today, and not just new ones. Perhaps something like (if not exactly)
*Editions* are a per-crate setting that can only do the following two things:
* Change a deprecation from the prior edition into a hard error
* Change a deprecation from the prior edition to deny by default, and ...
Hmm, I just realized that this means that the deprecatedness of a feature and in which edition it was deprecated in are now part of the language proper (and in-scope for the reference) and not just a part of linting (which is currently out-of-scope for the reference)
|
|
||
| As a corollary to this, these changes can free up space for new features, | ||
| that would then require being tied to a particular edition. For example, | ||
| consider the desire to add a new (non-contextual) keyword. For a keyword to |
There was a problem hiding this comment.
Nit: Parenthesis are not needed.
|
Update: @Havvy and I talked today and I'm going to close this PR for now; we'll use this |
We can't merge this until editions stabilize, but @Havvy asked me to work something up.
What do you all think of this as an intro text? Obviously, we have to also write stuff in other sections; for example, https://doc.rust-lang.org/reference/linkage.html will need to talk about how editions can link to each other, the keywords thing will need to be updated, etc.