jj/docs/contributing.md

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

Contributions to this project must be accompanied by a Contributor License Agreement. You (or your employer) retain the copyright to your contribution; this simply gives us permission to use and redistribute your contributions as part of the project. Head over to https://cla.developers.google.com/ to see your current agreements on file or to sign a new one.

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

All submissions, including submissions by project members, require review. We use GitHub pull requests for this purpose. Consult GitHub Help for more information on using pull requests.

Community Guidelines

This project follows Google's Open Source Community Guidelines.

Setting up a development environment

To develop jj, the mandatory steps are simply to install Rust (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 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 --all-targets && cargo +1.60 check --all-targets'
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 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 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; 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.