From 7150d3cd9e011367f3c6fb6ff8d1e4c0f7a26e95 Mon Sep 17 00:00:00 2001 From: Ben Gesoff Date: Thu, 7 May 2015 14:23:05 +0100 Subject: [PATCH 1/3] Change rand version to '*' Following paragraph says "we've used `*` which..." but code says "rand=\"0.3.0\"" --- src/doc/trpl/guessing-game.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/trpl/guessing-game.md b/src/doc/trpl/guessing-game.md index 6b58f7dfde817..6f8798adaca13 100644 --- a/src/doc/trpl/guessing-game.md +++ b/src/doc/trpl/guessing-game.md @@ -352,7 +352,7 @@ add these few lines at the bottom: ```toml [dependencies] -rand="0.3.0" +rand="*" ``` The `[dependencies]` section of `Cargo.toml` is like the `[package]` section: From 0bc6fe5ea0b4e4fcbc98145855a1c416d08dfab0 Mon Sep 17 00:00:00 2001 From: Ben Gesoff Date: Thu, 7 May 2015 14:48:44 +0100 Subject: [PATCH 2/3] Refactor to keep rand version 0.3.0 changed paragraphs with discussion of Cargo.lock file to agree with rand version 0.3.0 in the Cargo.tom file. --- src/doc/trpl/guessing-game.md | 32 +++++++++++++++----------------- 1 file changed, 15 insertions(+), 17 deletions(-) diff --git a/src/doc/trpl/guessing-game.md b/src/doc/trpl/guessing-game.md index 6f8798adaca13..1e35dd6e8182d 100644 --- a/src/doc/trpl/guessing-game.md +++ b/src/doc/trpl/guessing-game.md @@ -352,17 +352,16 @@ add these few lines at the bottom: ```toml [dependencies] -rand="*" +rand="0.3.0" ``` The `[dependencies]` section of `Cargo.toml` is like the `[package]` section: everything that follows it is part of it, until the next section starts. Cargo uses the dependencies section to know what dependencies on external -crates you have, and what versions you require. In this case, we’ve used `*`, -which means that we’ll use the latest version of `rand`. Cargo understands -[Semantic Versioning][semver], which is a standard for writing version -numbers. If we wanted a specific version or range of versions, we could be -more specific here. [Cargo’s documentation][cargodoc] contains more details. +crates you have, and what versions you require. In this case, we’ve used version `0.3.0`. +Cargo understands [Semantic Versioning][semver], which is a standard for writing version +numbers. If we wanted to use the latest version we could use `*` or we could use a range +of versions. [Cargo’s documentation][cargodoc] contains more details. [semver]: http://semver.org [cargodoc]: http://doc.crates.io/crates-io.html @@ -372,15 +371,13 @@ Now, without changing any of our code, let’s build our project: ```bash $ cargo build Updating registry `https://github.com/rust-lang/crates.io-index` - Downloading rand v0.3.8 + Downloading rand v0.3.0 Downloading libc v0.1.6 Compiling libc v0.1.6 - Compiling rand v0.3.8 + Compiling rand v0.3.0 Compiling guessing_game v0.1.0 (file:///home/you/projects/guessing_game) ``` -(You may see different versions, of course.) - Lots of new output! Now that we have an external dependency, Cargo fetches the latest versions of everything from the registry, which is a copy of data from [Crates.io][cratesio]. Crates.io is where people in the Rust ecosystem @@ -410,11 +407,11 @@ $ cargo build Compiling guessing_game v0.1.0 (file:///home/you/projects/guessing_game) ``` -So, we told Cargo we wanted any version of `rand`, and so it fetched the latest -version at the time this was written, `v0.3.8`. But what happens when next -week, version `v0.3.9` comes out, with an important bugfix? While getting -bugfixes is important, what if `0.3.9` contains a regression that breaks our -code? +Let's pretend that we told Cargo we wanted the latest version of `rand` (using `*`) +for a bit. It would have fetched `v0.3.8` (at the time this was written). +But what happens when next week, version `v0.3.9` comes out, with an important +bugfix? While getting bugfixes is important, what if `0.3.9` contains a regression +that breaks our code? The answer to this problem is the `Cargo.lock` file you’ll now find in your project directory. When you build your project for the first time, Cargo @@ -422,7 +419,7 @@ figures out all of the versions that fit your criteria, and then writes them to the `Cargo.lock` file. When you build your project in the future, Cargo will see that the `Cargo.lock` file exists, and then use that specific version rather than do all the work of figuring out versions again. This lets you -have a repeatable build automatically. In other words, we’ll stay at `0.3.8` +have a repeatable build automatically. In other words, we’ll stay at `0.3.0` until we explicitly upgrade, and so will anyone who we share our code with, thanks to the lock file. @@ -442,7 +439,8 @@ projects which are assembled out of a number of sub-packages. [doccargo]: http://doc.crates.io [doccratesio]: http://doc.crates.io/crates-io.html -Let’s get on to actually _using_ `rand`. Here’s our next step: +Let’s get on to actually _using_ `rand`. Keep the version as `0.3.0` for this +project. Here’s our next step: ```rust,ignore extern crate rand; From 888086d959e7d1b840b0d7644e4e49b6941ecf73 Mon Sep 17 00:00:00 2001 From: Ben Gesoff Date: Thu, 7 May 2015 15:36:47 +0100 Subject: [PATCH 3/3] Undid changes involving misunderstanding of 0.3.x Didn't realise 0.3.0 referred to all 0.3.x versions! Fixed my mistakes. Should have just updated the Cargo.toml now. --- src/doc/trpl/guessing-game.md | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/src/doc/trpl/guessing-game.md b/src/doc/trpl/guessing-game.md index 1e35dd6e8182d..57479a21e47a8 100644 --- a/src/doc/trpl/guessing-game.md +++ b/src/doc/trpl/guessing-game.md @@ -371,13 +371,15 @@ Now, without changing any of our code, let’s build our project: ```bash $ cargo build Updating registry `https://github.com/rust-lang/crates.io-index` - Downloading rand v0.3.0 + Downloading rand v0.3.8 Downloading libc v0.1.6 Compiling libc v0.1.6 - Compiling rand v0.3.0 + Compiling rand v0.3.8 Compiling guessing_game v0.1.0 (file:///home/you/projects/guessing_game) ``` +(You may see different versions, of course.) + Lots of new output! Now that we have an external dependency, Cargo fetches the latest versions of everything from the registry, which is a copy of data from [Crates.io][cratesio]. Crates.io is where people in the Rust ecosystem @@ -407,11 +409,11 @@ $ cargo build Compiling guessing_game v0.1.0 (file:///home/you/projects/guessing_game) ``` -Let's pretend that we told Cargo we wanted the latest version of `rand` (using `*`) -for a bit. It would have fetched `v0.3.8` (at the time this was written). -But what happens when next week, version `v0.3.9` comes out, with an important -bugfix? While getting bugfixes is important, what if `0.3.9` contains a regression -that breaks our code? +So, we told Cargo we wanted any `0.3.x` version of `rand`, and so it fetched the latest +version at the time this was written, `v0.3.8`. But what happens when next +week, version `v0.3.9` comes out, with an important bugfix? While getting +bugfixes is important, what if `0.3.9` contains a regression that breaks our +code? The answer to this problem is the `Cargo.lock` file you’ll now find in your project directory. When you build your project for the first time, Cargo @@ -419,7 +421,7 @@ figures out all of the versions that fit your criteria, and then writes them to the `Cargo.lock` file. When you build your project in the future, Cargo will see that the `Cargo.lock` file exists, and then use that specific version rather than do all the work of figuring out versions again. This lets you -have a repeatable build automatically. In other words, we’ll stay at `0.3.0` +have a repeatable build automatically. In other words, we’ll stay at `0.3.8` until we explicitly upgrade, and so will anyone who we share our code with, thanks to the lock file. @@ -439,8 +441,7 @@ projects which are assembled out of a number of sub-packages. [doccargo]: http://doc.crates.io [doccratesio]: http://doc.crates.io/crates-io.html -Let’s get on to actually _using_ `rand`. Keep the version as `0.3.0` for this -project. Here’s our next step: +Let’s get on to actually _using_ `rand`. Here’s our next step: ```rust,ignore extern crate rand;