From b33126e1b0bbb0e0622b19d39ffa3f7b5cb86baa Mon Sep 17 00:00:00 2001 From: Ilya Grigoriev Date: Thu, 24 Nov 2022 20:42:30 -0800 Subject: [PATCH] Document suggestions for a `jj` development environment I worte up some things I wish I knew when I wrote my first PR. --- docs/contributing.md | 59 +++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 56 insertions(+), 3 deletions(-) diff --git a/docs/contributing.md b/docs/contributing.md index 654a07164..aa725f39e 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -1,9 +1,11 @@ # How to Contribute +## Policies + We'd love to accept your patches and contributions to this project. There are just a few small guidelines you need to follow. -## Contributor License Agreement +### Contributor License Agreement Contributions to this project must be accompanied by a Contributor License Agreement. You (or your employer) retain the copyright to your contribution; @@ -15,14 +17,65 @@ You generally only need to submit a CLA once, so if you've already submitted one (even if it was for a different project), you probably don't need to do it again. -## Code reviews +### Code reviews All submissions, including submissions by project members, require review. We use GitHub pull requests for this purpose. Consult [GitHub Help](https://help.github.com/articles/about-pull-requests/) for more information on using pull requests. -## Community Guidelines +### Community Guidelines This project follows [Google's Open Source Community 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), clone the repository, +and use `cargo build`, `cargo fmt`, `cargo test`, etc. If you are +preparing a PR, there are some additional recommended steps. + +### Summary + +One-time setup: + + rustup toolchain add nightly # If this is not your default + rustup toolchain add 1.60 + cargo install cargo-insta + cargo install cargo-watch + +During development (adapt according to your preference): + + cargo watch --ignore '.jj/**' -s 'cargo +nightly fmt && cargo clippy && cargo +1.60 check' + cargo insta test # 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. +Cargo will happily use up your entire hard drive. If this happens, run +`cargo clean`. + +### Explanation + +These are ordered 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. + +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`. + +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. + +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`.