Skip to content

Add introductory text for editions #393

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

Add introductory text for editions #393

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions src/SUMMARY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@

- [Notation](notation.md)

- [Editions](editions.md)

- [Lexical structure](lexical-structure.md)
- [Input format](input-format.md)
- [Keywords](keywords.md)
Expand Down
39 changes: 39 additions & 0 deletions src/editions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
# Editions

Before we get into the details of the language itself, we need to cover the
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

concept of an "edition."

An "edition" of Rust consists of a particular year. There are two editions of
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: "of Rust" is redundant in both places.

Rust, currently:

* Rust 2015
* Rust 2018

Conforming compilers are expected to:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


* Provide a flag allowing users to select an edition.
* 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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This seems like a good policy for now, given how small the actual "made into an error" class of things is.


## What editions can change
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)


There are only two things a new edition can do:

* Change an existing deprecation into a hard error.
* Change an existing deprecation to deny by default, and leverage the
corresponding lint setting to produce error messages as if the feature were
removed entirely.

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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: Parenthesis are not needed.

be added, a previous edition must deprecate using that keyword as an
identifier. The new edition may then turn that into an error, freeing space
for the addition of the keyword.

Restricting what editions can do is important for both users and compiler
authors; if Rust were to change drastically between editions, it would be
difficult for users, who would need to switch between editions while using
Rust, and compilers would be much harder to implement.