From 86cd0fa570e4dc7f4dd312ef8b6359b6a38e94a3 Mon Sep 17 00:00:00 2001 From: Martin von Zweigbergk Date: Thu, 15 Dec 2022 22:51:58 -0800 Subject: [PATCH] docs: touch up contributor guide, mentioning `cargo nextest --workspace` It can be confusing that the lib crate is not tested when you run `cargo test` without `--workspace` from the root directory. Also, `nextest` is a non-obvious quality-of-life improvement, so let's suggest that. --- docs/contributing.md | 54 +++++++++++++++++++++++++++----------------- 1 file changed, 33 insertions(+), 21 deletions(-) diff --git a/docs/contributing.md b/docs/contributing.md index 0a43504da..d4c2a6e8e 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -59,10 +59,12 @@ Guidelines](https://opensource.google/conduct/). ## Setting up a development environment -To develop `jj`, the mandatory steps are simply to [install -Rust](https://www.rust-lang.org/tools/install) (the default installer options -are fine), clone the repository, and use `cargo build`, `cargo fmt`, -`cargo test`, etc. If you are preparing a PR, there are some additional +To develop `jj`, the mandatory steps are simply +to [install Rust](https://www.rust-lang.org/tools/install) (the default +installer options are fine), clone the repository, and use `cargo build` +, `cargo fmt`, +`cargo clippy --workspace --all-targets`, and +`cargo test --workspace`. If you are preparing a PR, there are some additional recommended steps. ### Summary @@ -73,12 +75,15 @@ One-time setup: rustup toolchain add 1.60 cargo install cargo-insta cargo install cargo-watch + cargo install cargo-nextest During development (adapt according to your preference): cargo watch --ignore '.jj/**' -s \ - 'cargo +nightly fmt && cargo clippy --all-targets && cargo +1.60 check --all-targets' - cargo insta test # Occasionally + 'cargo +nightly fmt && cargo clippy --workspace --all-targets \ + && cargo +1.60 check --workspace --all-targets' + cargo nextest run --workspace # Occasionally + cargo insta test --workspace # Occasionally WARNING: Build artifacts from debug builds and especially from repeated invocations of `cargo test` can quickly take up 10s of GB of disk space. @@ -89,23 +94,30 @@ Cargo will happily use up your entire hard drive. If this happens, run These are listed roughly in order of decreasing importance. -1. Nearly any change to `jj`'s interface will require writing or updating -golden tests that use the [`insta`](https://insta.rs/) crate. To make -this convenient, install the `cargo-insta` binary. Use `cargo insta tests` -to run tests, and `cargo insta review` to update the golden tests. +1. Nearly any change to `jj`'s CLI will require writing or updating snapshot + tests that use the [`insta`](https://insta.rs/) crate. To make this + convenient, install the `cargo-insta` binary. + Use `cargo insta test --workspace` to run tests, + and `cargo insta review --workspace` to update the snapshot tests. + The `--workspace` flag is needed to run the tests on all crates; by default, + only the crate in the current directory is tested. 2. Github CI checks require that the code is formatted with the *nightly* -version of `rustfmt`. To do this on your computer, install the nightly -toolchain and use `cargo +nightly fmt`. + version of `rustfmt`. To do this on your computer, install the nightly + toolchain and use `cargo +nightly fmt`. -3. Your code will be rejected if it cannot be compiled with the -minimal supported version of Rust. This version is listed as -`rust-version` in [`Cargo.toml`](../Cargo.toml); it is 1.60 as -of this writing. +3. Your code will be rejected if it cannot be compiled with the minimal + supported version of Rust. This version is listed as + `rust-version` in [`Cargo.toml`](../Cargo.toml); it is 1.60 as of this + writing. -4. Your code needs to pass `cargo clippy`. You can also use `cargo -+nightly clippy` if you wish to see more warnings. +4. Your code needs to pass `cargo clippy`. You can also + use `cargo +nightly clippy` if you wish to see more warnings. -5. You may also want to install and use `cargo-watch`. In this case, -you should exclude `.jj`. directory from the filesystem watcher, as -it gets updated on every `jj log`. +5. You may also want to install and use `cargo-watch`. In this case, you should + exclude `.jj`. directory from the filesystem watcher, as it gets updated on + every `jj log`. + +6. To run tests more quickly, use `cargo nextest run --workspace`. To + use `nextest` with `insta`, + use `cargo insta test --workspace --test-runner nextest`.