Auto merge of #8609 - ehuss:resolver-semver, r=Eh2406

Add chapters on dependency resolution and SemVer compatibility.

This adds two documentation chapters, one on the resolver and one on SemVer compatibility. These are intended to help guide users on how to version their package and how to use dependencies.

I did not document `[patch]` resolution. Perhaps someday in the future the the "Overriding dependencies" chapter can be expanded to include more details on how patch works, and how to properly use it. I have a bunch of notes on this, but I want to defer it till later.

The SemVer compatibility guidelines were guided by [RFC 1105](https://github.com/rust-lang/rfcs/blob/master/text/1105-api-evolution.md), but are edited and expanded based on my own personal observations. I tried to highlight when some rules do not appear to have consensus on behavior. I would be happy for any additions or modifications to the rule list. I have a list of additional things to add, but I wanted to get the ball rolling, and it might take a while finish them.

Each compatibility entry has an example, and there is a small script which tests all the examples to ensure they work like they are supposed to. This script checks against the compiler output, which can be fragile over time. If that becomes too troublesome, we can probably find some more relaxed checks. I think checking the error is important because I've run into cases in the past where using basic "compile_fail" annotations were misleading because the examples were failing for the wrong reason.

Closes #7301

.github/workflows/main.yml

@@ -92,6 +92,8 @@ jobs:
     - run: rustup update nightly && rustup default nightly
     - run: rustup component add rust-docs
     - run: ci/validate-man.sh
+    # This requires rustfmt, use stable.
+    - run: cd src/doc/semver-check && cargo +stable run
     - run: |
         mkdir mdbook
         curl -Lf https://github.com/rust-lang/mdBook/releases/download/v0.3.7/mdbook-v0.3.7-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook

src/doc/README.md

@@ -56,6 +56,12 @@ To rebuild the man pages, run the script `build-man.sh` in the `src/doc` directo
 $ ./build-man.sh
 ```
 
+### SemVer chapter tests
+
+There is a script to verify that the examples in the SemVer chapter work as
+intended. To run the tests, go into the `semver-check` directory and run
+`cargo run`.
+
 ## Contributing
 
 We'd love your help with improving the documentation! Please feel free to

src/doc/semver-check/Cargo.toml

@@ -0,0 +1,10 @@
+[package]
+name = "semver-check"
+version = "0.1.0"
+authors = ["Eric Huss"]
+edition = "2018"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+tempfile = "3.1.0"

src/doc/semver-check/src/main.rs

@@ -0,0 +1,217 @@
+//! Test runner for the semver compatibility doc chapter.
+//!
+//! This extracts all the "rust" annotated code blocks and tests that they
+//! either fail or succeed as expected. This also checks that the examples are
+//! formatted correctly.
+//!
+//! An example with the word "MINOR" at the top is expected to successfully
+//! build against the before and after. Otherwise it should fail. A comment of
+//! "// Error:" will check that the given message appears in the error output.
+
+use std::error::Error;
+use std::fs;
+use std::path::Path;
+use std::process::Command;
+
+fn main() {
+    if let Err(e) = doit() {
+        println!("error: {}", e);
+        std::process::exit(1);
+    }
+}
+
+const SEPARATOR: &str = "///////////////////////////////////////////////////////////";
+
+fn doit() -> Result<(), Box<dyn Error>> {
+    let filename = std::env::args()
+        .skip(1)
+        .next()
+        .unwrap_or_else(|| "../src/reference/semver.md".to_string());
+    let contents = fs::read_to_string(filename)?;
+    let mut lines = contents.lines().enumerate();
+
+    loop {
+        // Find a rust block.
+        let block_start = loop {
+            match lines.next() {
+                Some((lineno, line)) => {
+                    if line.trim().starts_with("```rust") && !line.contains("skip") {
+                        break lineno + 1;
+                    }
+                }
+                None => return Ok(()),
+            }
+        };
+        // Read in the code block.
+        let mut block = Vec::new();
+        loop {
+            match lines.next() {
+                Some((_, line)) => {
+                    if line.trim() == "```" {
+                        break;
+                    }
+                    block.push(line);
+                }
+                None => {
+                    return Err(format!(
+                        "rust block did not end for example starting on line {}",
+                        block_start
+                    )
+                    .into());
+                }
+            }
+        }
+        // Split it into the separate source files.
+        let parts: Vec<_> = block.split(|line| line.trim() == SEPARATOR).collect();
+        if parts.len() != 4 {
+            return Err(format!(
+                "expected 4 sections in example starting on line {}, got {}:\n{:?}",
+                block_start,
+                parts.len(),
+                parts
+            )
+            .into());
+        }
+        let join = |part: &[&str]| {
+            let mut result = String::new();
+            result.push_str("#![allow(unused)]\n#![deny(warnings)]\n");
+            result.push_str(&part.join("\n"));
+            if !result.ends_with('\n') {
+                result.push('\n');
+            }
+            result
+        };
+        let expect_success = parts[0][0].contains("MINOR");
+        println!("Running test from line {}", block_start);
+        if let Err(e) = run_test(
+            join(parts[1]),
+            join(parts[2]),
+            join(parts[3]),
+            expect_success,
+        ) {
+            return Err(format!(
+                "test failed for example starting on line {}: {}",
+                block_start, e
+            )
+            .into());
+        }
+    }
+}
+
+const CRATE_NAME: &str = "updated_crate";
+
+fn run_test(
+    before: String,
+    after: String,
+    example: String,
+    expect_success: bool,
+) -> Result<(), Box<dyn Error>> {
+    let tempdir = tempfile::TempDir::new()?;
+    let before_p = tempdir.path().join("before.rs");
+    let after_p = tempdir.path().join("after.rs");
+    let example_p = tempdir.path().join("example.rs");
+    compile(before, &before_p, CRATE_NAME, false, true)?;
+    compile(example.clone(), &example_p, "example", true, true)?;
+    compile(after, &after_p, CRATE_NAME, false, true)?;
+    compile(example, &example_p, "example", true, expect_success)?;
+    Ok(())
+}
+
+fn check_formatting(path: &Path) -> Result<(), Box<dyn Error>> {
+    match Command::new("rustfmt")
+        .args(&["--edition=2018", "--check"])
+        .arg(path)
+        .status()
+    {
+        Ok(status) => {
+            if !status.success() {
+                return Err(format!("failed to run rustfmt: {}", status).into());
+            }
+            return Ok(());
+        }
+        Err(e) => {
+            return Err(format!("failed to run rustfmt: {}", e).into());
+        }
+    }
+}
+
+fn compile(
+    mut contents: String,
+    path: &Path,
+    crate_name: &str,
+    extern_path: bool,
+    expect_success: bool,
+) -> Result<(), Box<dyn Error>> {
+    // If the example has an error message, remove it so that it can be
+    // compared with the actual output, and also to avoid issues with rustfmt
+    // moving it around.
+    let expected_error = match contents.find("// Error:") {
+        Some(index) => {
+            let start = contents[..index].rfind(|ch| ch != ' ').unwrap();
+            let end = contents[index..].find('\n').unwrap();
+            let error = contents[index + 9..index + end].trim().to_string();
+            contents.replace_range(start + 1..index + end, "");
+            Some(error)
+        }
+        None => None,
+    };
+    let crate_type = if contents.contains("fn main()") {
+        "bin"
+    } else {
+        "rlib"
+    };
+
+    fs::write(path, &contents)?;
+    check_formatting(path)?;
+    let out_dir = path.parent().unwrap();
+    let mut cmd = Command::new("rustc");
+    cmd.args(&[
+        "--edition=2018",
+        "--crate-type",
+        crate_type,
+        "--crate-name",
+        crate_name,
+        "--out-dir",
+    ]);
+    cmd.arg(&out_dir);
+    if extern_path {
+        let epath = out_dir.join(format!("lib{}.rlib", CRATE_NAME));
+        cmd.arg("--extern")
+            .arg(format!("{}={}", CRATE_NAME, epath.display()));
+    }
+    cmd.arg(path);
+    let output = cmd.output()?;
+    let stderr = std::str::from_utf8(&output.stderr).unwrap();
+    match (output.status.success(), expect_success) {
+        (true, true) => Ok(()),
+        (true, false) => Err(format!(
+            "expected failure, got success {}\n===== Contents:\n{}\n===== Output:\n{}\n",
+            path.display(),
+            contents,
+            stderr
+        )
+        .into()),
+        (false, true) => Err(format!(
+            "expected success, got error {}\n===== Contents:\n{}\n===== Output:\n{}\n",
+            path.display(),
+            contents,
+            stderr
+        )
+        .into()),
+        (false, false) => {
+            if expected_error.is_none() {
+                return Err("failing test should have an \"// Error:\" annotation ".into());
+            }
+            let expected_error = expected_error.unwrap();
+            if !stderr.contains(&expected_error) {
+                Err(format!(
+                    "expected error message not found in compiler output\nExpected: {}\nGot:\n{}\n",
+                    expected_error, stderr
+                )
+                .into())
+            } else {
+                Ok(())
+            }
+        }
+    }
+}

src/doc/src/SUMMARY.md

@@ -35,6 +35,8 @@
     * [Source Replacement](reference/source-replacement.md)
     * [External Tools](reference/external-tools.md)
     * [Registries](reference/registries.md)
+    * [Dependency Resolution](reference/resolver.md)
+    * [SemVer Compatibility](reference/semver.md)
     * [Unstable Features](reference/unstable.md)
 
 * [Cargo Commands](commands/index.md)

src/doc/src/reference/index.md

@@ -18,4 +18,6 @@ The reference covers the details of various areas of Cargo.
 * [Source Replacement](source-replacement.md)
 * [External Tools](external-tools.md)
 * [Registries](registries.md)
+* [Dependency Resolution](resolver.md)
+* [SemVer Compatibility](semver.md)
 * [Unstable Features](unstable.md)

src/doc/src/reference/manifest.md

@@ -95,6 +95,14 @@ Versioning](https://semver.org/), so make sure you follow some basic rules:
   traits, fields, types, functions, methods or anything else.
 * Use version numbers with three numeric parts such as 1.0.0 rather than 1.0.
 
+See the [Resolver] chapter for more information on how Cargo uses versions to
+resolve dependencies, and for guidelines on setting your own version. See the
+[Semver compatibility] chapter for more details on exactly what constitutes a
+breaking change.
+
+[Resolver]: resolver.md
+[Semver compatibility]: semver.md
+
 <a id="the-authors-field-optional"></a>
 #### The `authors` field