Backfill contents since 1.0 #75

steveklabnik · 2018-08-06T22:37:34Z

This PR effectively re-writes the entire edition guide.

We now talk about every feature since rust 1.0; each is tagged with a minimum version. They're roughly ordered from oldest to newest.
The current contents are imported where it makes sense
- Some changes (crate visibility modifier, in-band lifetimes) have been dropped since they're also dropping from the edition probably

Most of this was taken from the various blog posts for various releases. It's not in as clean of a format as the new stuff is, but I'd like to land this first, and then look to doing that.

I'm pretty sure these tests will fail as I didn't really pay attention to code samples, but let's see!

Rust 1.4 didn't have anything of note

Rust 1.7 didn't have anything

Mark-Simulacrum

Generally speaking I quite like this. Some thoughts:

A diff of the standard library, probably just a snapshot of all release notes concatenated would be of interest to me, at least so we can see what it looks like.
I think a status page (ideally auto-generated, but I understand that's quite hard) with the minimum rust versions would I think be good, especially for things not yet stable. This might be removed with the release.

Mark-Simulacrum · 2018-08-06T22:44:31Z

src/rust-2018/a-non-null-raw-pointer.md

+same size as `*mut T`. It is allowed to dangle if it isn't dereferenced.
+
+If you’re building a data structure with unsafe code, `NonNull<T>` is often
+the right type for you!


Perhaps worth mentioning NonZero types here as well? Seem similar in concept

I felt like this type is more significant. They're similar, but I feel like this will get way more use.

I would mention it even if NonNull will get way more use.

Mark-Simulacrum · 2018-08-06T22:47:50Z

src/rust-2018/an-attribute-for-deprecation.md

+
+```
+
+Both `since` and `note` are optional.


Perhaps make a small note that since can be in the future?

Mark-Simulacrum · 2018-08-06T22:52:22Z

src/rust-2018/cargo-can-use-a-local-registry-replacement.md

+This has enabled tools like
+[`cargo-vendor`](https://github.com/alexcrichton/cargo-vendor) and
+[`cargo-local-registry`](https://github.com/alexcrichton/cargo-local-registry),
+which are often useful for "offline builds." They preparing the list of all


nit: They prepare

Mark-Simulacrum · 2018-08-06T22:53:40Z

src/rust-2018/cargo-check-for-faster-checking.md

+
+![Minimum Rust version: 1.16](https://img.shields.io/badge/Minimum%20Rust%20Version-1.16-brightgreen.svg) for being built-in
+
+![Minimum Rust version: various](https://img.shields.io/badge/Minimum%20Rust%20Version-various-brightgreen.svg) using [this package](https://github.com/rsolomo/cargo-check) for older versions


Hm, I'd maybe omit this. I'm not sure how I feel about it, but generally seems like sticking to 'core language' here would streamline things. We can maybe include a general note that some features were pulled into core from others libraries.

I'm willing to do that, sure

Mark-Simulacrum · 2018-08-06T22:53:52Z

src/rust-2018/cargo-check-for-faster-checking.md

+
+![Minimum Rust version: various](https://img.shields.io/badge/Minimum%20Rust%20Version-various-brightgreen.svg) using [this package](https://github.com/rsolomo/cargo-check) for older versions
+
+`cargo check`is a new subcommand should speed up the development


nit: space after cargo check

Mark-Simulacrum · 2018-08-06T23:20:11Z

src/rust-2018/global-allocators.md

@@ -0,0 +1,35 @@
+# Gobal allocators


nit: Global

Mark-Simulacrum · 2018-08-06T23:21:55Z

src/rust-2018/incremental-compilation-for-faster-compiles.md

@@ -0,0 +1 @@
+# Incremental Compilation for faster compiles


Looks like an accidental page? This is included in incremental-compilation.md

other way around; that one is accidental but yes

Mark-Simulacrum · 2018-08-06T23:25:03Z

src/rust-2018/new-editions-of-the-book.md

+![Minimum Rust version: 1.28](https://img.shields.io/badge/Minimum%20Rust%20Version-1.28-red.svg) for drafts of the 2018 edition
+
+We've distributed a copy of "The Rust Programming Language," affectionatly
+nicknamed "the book", whith every version of Rust since Rust 1.0.


Mark-Simulacrum · 2018-08-06T23:25:24Z

src/rust-2018/new-editions-of-the-book.md

+Press](https://nostarch.com/Rust). Now that the print version has shipped,
+the second edition is frozen.
+
+The names are a bit confusing though, becuase the "second edition" of the


nit: because

Mark-Simulacrum · 2018-08-06T23:27:20Z

src/rust-2018/rustdoc-uses-commonmark.md

+uses it by default.
+
+As of Rust 1.23, we still defaulted to `hoedown`, but you could enable
+Commonmark via a flag, `--enable-commonmark`.


"But we now only support the CommonMark markdown specification"

steveklabnik · 2018-08-07T15:53:13Z

A diff of the standard library, probably just a snapshot of all release notes concatenated would be of interest to me, at least so we can see what it looks like.

This is a ton of work, due to the way release notes are written. I'm not opposed to having this, but I really, really don't want to do it ;)

Mark-Simulacrum · 2018-08-07T15:54:58Z

Yeah, I think I might find some time to get a loose sketch going -- I agree the release notes don't lend themselves well to that today :)

steveklabnik · 2018-08-07T19:50:23Z

Tests are now passing; what do I need to do to get this merged? :)

Centril · 2018-08-07T19:51:29Z

I'd like to give this a review before merging :)

I'll give it some time today.

Centril

Here goes :)

Centril · 2018-08-08T17:57:48Z

src/rust-2018/union-for-an-unsafe-form-of-enum.md

+
+Since we can interpret the data held in the union using the wrong variant and
+Rust can’t check this for us, that means reading or writing a union’s field
+is unsafe:


Maybe take into account https://internals.rust-lang.org/t/pre-rfc-unions-drop-types-and-manuallydrop/8025

In general with docs, we focus on stable Rust; I don't want to speculate on things until they're actually tied down.

Centril · 2018-08-08T18:02:29Z

src/rust-2018/the-try-operator-for-easier-error-handling.md

@@ -0,0 +1,119 @@
+# The 'try' operator, ? for easier error handling


Should probably avoid calling this the "try operator" because of try { .. } blocks and rust-lang/rfcs#2388 (comment).

As a temporary alternative, I think "question mark operator" or "re-throw operator" works.

Isn't the reason to call this the try operator try blocks?

We do call it "the question mark operator" in the book, so I'm open to change it; I thought it was changing to try

That is what I argued on the try { .. } RFC; rust-lang/rfcs#2388 (comment), rust-lang/rfcs#2388 (comment). However, people, rust-lang/rfcs#2388 (comment), did not seem to agree :)

Centril · 2018-08-08T18:07:57Z

src/rust-2018/the-rust-bookshelf.md

@@ -0,0 +1,33 @@
+# The Rust Bookshelf


And it will get a new member too! This guide! 😆

Centril · 2018-08-08T18:09:27Z

src/rust-2018/the-anonymous-lifetime.md

@@ -1,4 +1,6 @@
-# `'_`, the anonymous lifetime
+# '_, the anonymous lifetime


Hmm; having this in backticks highlights that this is code which is useful.

an oversight! will fix

Centril · 2018-08-08T18:10:49Z

src/rust-2018/std-os-has-documentation-for-all-platforms.md

@@ -0,0 +1,11 @@
+# std::os has documentation for all platforms


backticks around std::os I'd say.

Centril · 2018-08-08T19:23:47Z

src/rust-2018/128-bit-integers.md

+
+These are twice the size of `u64`, and so can hold more values. More specifically,
+
+* `u128`: `0` - `340,282,366,920,938,463,463,374,607,431,768,211,455`


This kinda looks like an array; I'd use underscore instead as a separator.

we used this text in the release blog post and people were not generally confused

I suppose; however, 340_282_366_920_938_463_463_374_607_431_768_211_455 has the benefit of being legal Rust code :)

Centril · 2018-08-08T19:23:57Z

src/rust-2018/128-bit-integers.md

+These are twice the size of `u64`, and so can hold more values. More specifically,
+
+* `u128`: `0` - `340,282,366,920,938,463,463,374,607,431,768,211,455`
+* `i128`: `−170,141,183,460,469,231,731,687,303,715,884,105,728` - `170,141,183,460,469,231,731,687,303,715,884,105,727`


Centril · 2018-08-08T19:25:39Z

src/introduction.md

+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 most absolutely major ones are, but there's tons of medium and small


most absolutely major ones? wow, they must be real special! 😜
I think "major ones" suffices :)

Centril · 2018-08-08T19:27:29Z

src/SUMMARY.md

+
+## Rust 2018
+
+- [Rust 2018](rust-2018/index.md)


We should probably organize this a bit into categories after this PR; The flat list is a bit chaotic.

I found the categories far more confusing, personally

I guess it doesn't work well with ordering also... let's not do it for now then :)

Centril · 2018-08-08T19:30:16Z

book.toml

@@ -1,5 +1,5 @@
 [book]
-authors = ["The Rust Project Developers"]
+authors = ["steveklabnik"]


Haha :P I guess you've earned this but I think it would be nice to keep this as is ;)

Centril · 2018-08-08T19:35:32Z

This is a ton of work, due to the way release notes are written. I'm not opposed to having this, but I really, really don't want to do it ;)

I can take one for the team :)

goodmanjonathan · 2018-08-10T18:04:09Z

src/rust-2018/improved-error-messages.md

+
+![Minimum Rust version: 1.12](https://img.shields.io/badge/Minimum%20Rust%20Version-1.12-brightgreen.svg)
+
+We're always working on erorr improvements, and there are little improvements


typo: error

@goodmanjonathan

thanks @goodmanjonathan

steveklabnik · 2018-08-10T18:14:03Z

Thanks for the reviews everyone! I'm merging this in; if we want to tweak it further, please open issues/send PRs! :D <3

steveklabnik added 30 commits August 3, 2018 11:24

wipe out the old book

1a90605

skeleton

56a19bc

get ready to add stuff

92900b0

Rust 1.1

a38104b

Rust 1.2

feb51f6

Rust 1.3

1034c77

point out that we're missing lots of std stuff

737544f

bugfix for nomicon version

f1ce7be

Rust 1.5

ecbc680

Rust 1.4 didn't have anything of note

Rust 1.6

3314372

Rust 1.8

89a085a

Rust 1.7 didn't have anything

Rust 1.9

cc212a5

fix to nomicon badge

06911fb

Rust 1.10 and 1.11

0180bf7

Rust 1.12

a02d094

Rust 1.13

5a80f73

Rust 1.14

1879957

Rust 1.15

526fb29

Rust 1.16

201bdaa

Rust 1.17

0d2551c

Rust 1.18

1e8531f

Rust 1.19

757c6da

Rust 1.20

a3d858f

fix up some markdown

deb5b21

Rust 1.21

0f8214b

Rust 1.22

89c03e5

Rust 1.24

73648f1

Rust 1.25

76f29e1

Rust 1.26

b22406c

Rust 1.27

e7dd330

steveklabnik added 3 commits August 6, 2018 18:15

Rust 1.28

c2a6f85

Rust master

9c1f326

remove full features page

cc19f79

Mark-Simulacrum reviewed Aug 6, 2018

View reviewed changes

steveklabnik added 2 commits August 7, 2018 11:50

fix @simulacrum nits

142e8f8

re-add the status page

daa9ccc

fix mdbook test

93f196b

Centril self-requested a review August 7, 2018 19:51

Centril reviewed Aug 8, 2018

View reviewed changes

@Centril review comments addressed

d322813

goodmanjonathan reviewed Aug 10, 2018

View reviewed changes

typo fix

fcc1b17

thanks @goodmanjonathan

steveklabnik merged commit b98d273 into master Aug 10, 2018

steveklabnik deleted the backfill-contents branch August 10, 2018 18:14


		![Minimum Rust version: 1.16](https://img.shields.io/badge/Minimum%20Rust%20Version-1.16-brightgreen.svg) for being built-in

		![Minimum Rust version: various](https://img.shields.io/badge/Minimum%20Rust%20Version-various-brightgreen.svg) using [this package](https://github.com/rsolomo/cargo-check) for older versions


		![Minimum Rust version: various](https://img.shields.io/badge/Minimum%20Rust%20Version-various-brightgreen.svg) using [this package](https://github.com/rsolomo/cargo-check) for older versions

		`cargo check`is a new subcommand should speed up the development

		@@ -0,0 +1,119 @@
		# The 'try' operator, ? for easier error handling

		@@ -1,4 +1,6 @@
		# `'_`, the anonymous lifetime
		# '_, the anonymous lifetime

		@@ -0,0 +1,11 @@
		# std::os has documentation for all platforms


		These are twice the size of `u64`, and so can hold more values. More specifically,

		* `u128`: `0` - `340,282,366,920,938,463,463,374,607,431,768,211,455`


		![Minimum Rust version: 1.12](https://img.shields.io/badge/Minimum%20Rust%20Version-1.12-brightgreen.svg)

		We're always working on erorr improvements, and there are little improvements

Backfill contents since 1.0 #75

Backfill contents since 1.0 #75

Conversation

steveklabnik commented Aug 6, 2018 • edited Loading

Mark-Simulacrum left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

steveklabnik commented Aug 7, 2018

Mark-Simulacrum commented Aug 7, 2018

steveklabnik commented Aug 7, 2018

Centril commented Aug 7, 2018

Centril left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Centril commented Aug 8, 2018

Choose a reason for hiding this comment

steveklabnik commented Aug 10, 2018

steveklabnik commented Aug 6, 2018 •

edited

Loading