mirrors/jj
1
0
Fork 1
mirror of https://github.com/martinvonz/jj.git synced 2025-01-18 02:04:19 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 5

docs: touch up contributor guide, mentioning cargo nextest --workspace

Browse source 
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.
This commit is contained in:
Martin von Zweigbergk 2022-12-15 22:51:58 -08:00 committed by Martin von Zweigbergk
parent e9bd6fbeae
commit 86cd0fa570
1 changed files with 33 additions and 21 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

54
docs/contributing.md
View file

@ -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`.