This is written for anyone who wants to contribute to the Rerun repository.
ARCHITECTURE.md
BUILD.md
rerun_py/README.md
- build instructions for Python SDKCODE_OF_CONDUCT.md
CODE_STYLE.md
RELEASES.md
-
Examples: We welcome any examples you would like to add. Follow the pattern of the existing examples in the
examples/
folder. -
Bug reports and issues: Open them at https://github.com/rerun-io/rerun/issues.
You can also look at our good first issue
tag.
We use Trunk Based Development, which means we encourage small, short-lived branches.
Open draft PR:s to get some early feedback on your work until you feel it is ready for a proper review.
Do not make PR:s from your own main
branch, as that makes it difficult for reviewers to add their own fixes.
Add any improvements to the branch as new commits instead of rebasing to make it easier for reviewers to follow the progress (add images if possible!).
All PR:s are merged with Squash and Merge
, meaning they all get squashed to just one commit on the main
branch. This means you don't need to keep a clean commit history on your feature branches. In fact, it is preferable to add new commits to a branch rather than rebasing or squashing. For one, it makes it easier to track progress on a branch, but rebasing and force-pushing also discourages collaboration on a branch.
Our CI will record various binary sizes and run some benchmarks on each merged PR.
Pull requests from external contributors require approval for CI runs. This can be done manually, by clicking the Approve and run
button:
Members of the rerun-io
organization and collaborators in the rerun-io/rerun
repository may enable auto-approval of workflow runs for a single PR by commenting with @rerun-bot approve
:
Every CI job would in its ideal state consist of only a single pixi
(or similar) script invocation that works locally as-is.
This approach has a number of benefits:
- Instead of Bash embedded in YAML, scripts may be written in an Actual Programming Language™
- Significantly lower iteration times when working on CI
- Ability to perform a job manually in case the CI fails
Additionally, always output any artifacts produced by CI to GCS instead of the GHA artifact storage. This can be a serious lifesaver when something breaks, as it allows anyone to download the output of a script and continue from where it failed, instead of being forced to start over from scratch.
Here are some guidelines to follow when writing such scripts:
Local-first means easy for contributors to run.
The following should be documented in each script:
- Dependencies
- Files and directories
- Environment variables
- Usage examples
Inputs should be passed in explicitly via arguments, and use sane defaults. If an input has a default value, it should be documented in its description.
Every input should be checked as early as possible. This includes:
- Checking if authentication credentials are valid
- Validating inputs and parsing into more specific types where possible:
- Numeric ranges
- String character sets/encodings
- Length limits
- Date formats
- etc.
- Checking that input file paths are valid and the files they point to exist
Input and output file paths should also accept GCS paths (gs://bucket/blob/path
) and stdin/stdout (-
), if it makes sense.
Be extra descriptive in error messages, it may be the only piece of information someone debugging a CI failure has available to figure out what went wrong. Print frequently to hint at what is going on and display progress to the user.
Environment variables should only be used for authentication with external services and configuring output (e.g. disabling color). Many SDKs support some form of persistent/default authentication, and scripts should take advantage of this where possible. For example, GCP has Application Default Credentials.
If the script performs destructive or otherwise irreversible actions, then it should support a --dry-run
option if possible.
Be thoughtful when adding dependencies. Each new dependency is a liability which lead to increased compile times, a bigger binary, more code that can break, a larger attack surface, etc. Sometimes it is better to write a hundred lines of code than to add a new dependency.
Whenever you add a new dependency in a PR, make sure you motivate it:
- Why use the dependency instead of rolling our own?
- Why this dependency instead of another?
For Rust, make sure you use default-features = false
if it makes sense, to minimize the amount of new code that is pulled in.
When reviewing a PR, always check the diff of Cargo.lock
(it is collapsed by default in GitHub 😤).
For a guide on picking good dependencies, see https://gist.github.com/repi/d98bf9c202ec567fd67ef9e31152f43f.
Any full cargo update
should be its own stand-alone PR. Make sure you include the output of it in the commit message.
The main crates are found in the crates/
folder, with examples in the examples/
folder.
To get an overview of the crates, read their documentation with:
cargo doc --no-deps --open
To learn about the viewer, run:
cargo run -p rerun -- --help
There are various kinds of automated tests throughout the repository.
If not noted otherwise, all tests run automated on CI, however their frequency (per PR, on main
, nightly, etc.) and platform coverage may vary.
cargo test --all-targets --all-features
or alternatively (if you've installed cargo nextest):
cargo nextest run --all-targets --all-features
cargo test --all-features --doc
Runs both unit & integration tests for Rust crates, including the Rerun viewer.
Tests are written using the standard #[test]
attribute.
Some of the tests in the rerun
family of crates are insta
snapshot tests.
These tests work by comparing a textual output of a test against a checked-in reference.
They run as part of the regular Rust test suite, no extra action is required to include them in a test run.
If the output of them changes (either intentionally or not), they will fail, and you can review the results by running cargo insta review
(you first need to install it with cargo install cargo-insta
).
Some of the tests in the rerun
family of crates are image comparison tests.
These tests work by rendering an image and then comparing it with a checked-in reference image.
They run as part of the regular Rust test suite, no extra action is required to include them in a test run.
Comparison tests are driven by egui_kittest's Harness::snapshot
method.
Typically, we use TestContext in order to mock
relevant parts of the Rerun viewer.
Each run of the comparison tests will produce new images that are saved to the comparison images.
(typically at <your-test.rs>/snapshots
)
Upon failure, additionally diff.png
file is added that highlights all differences between the reference and the new image.
In order to update reference with the new image, run with UPDATE_SNAPSHOTS=1
environment variable set.
Use pixi run snapshots
to compare the results of all failed tests in Rerun.
For best practices & unexpected sources of image differences refer to the egui_kittest README.
Just like for drawing the viewer itself, drawing for comparison tests requires a wgpu
compatible driver.
As of writing comparison tests are only run via Vulkan & Metal.
For CI / headless environments we a recent version llvmpipe
for software rendering on Linux & Windows.
On MacOS we currently always use hardware rendering.
For details on how to set this up refer to the CI setup.
pixi run py-test
The Python SDK is tested using pytest
.
Tests are located in the ./rerun_py/tests/ folder.
pixi run cpp-test
The C++ SDK is tested using catch2
.
Tests are located in the ./rerun_cpp/tests/ folder.
pixi run -e py docs/snippets/compare_snippet_output.py
More details in the README.md.
Makes sure all of the snippets in the snippets/ folder are working and yield the same output in all of the supported languages, unless configured otherwise in the snippets.toml file.
pixi run ./tests/roundtrips.py
A set of cross SDK language tests that makes sure that the same logging commands for a select group of archetypes yields the same output in all of the supported languages.
Nowadays largely redundant with the snippet comparison tests.
pixi run -e examples python tests/python/release_checklist/main.py
More details in the README.md.
A set of manual checklist-style tests that should be run prior to each release. Introduction of new release checklists should be avoided as they add a lot of friction to the release process, and failures are easy to be missed.
There's various additional test scenes located at ./tests/cpp/, ./tests/python/ and ./tests/rust/. We generally build those as a CI step, but they are run only irregularly. See respective readme files for more details.
We use the pixi
for managing dev-tool versioning, download and task running. To see available tasks, use pixi task list
.
We use cargo deny to check our dependency tree for copy-left licenses, duplicate dependencies and rustsec advisories. You can configure it in deny.toml
. Usage: cargo deny check
Configure your editor to run cargo fmt
on save. Also configure it to strip trailing whitespace, and to end each file with a newline. Settings for VSCode can be found in the .vscode
folder and should be applied automatically. If you are using another editor, consider adding good setting to this repository!
Depending on the changes you made run cargo test --all-targets --all-features
, pixi run py-test
and pixi run -e cpp cpp-test
locally.
For details see the test section above.
It is not strictly required, but we recommend cargo nextest
for running Rust tests as it is significantly faster than cargo test
and yields much more readable output.
Note however, that as of writing cargo nextest
does not yet support doc tests, those need to be run with cargo test
.
Prior to pushing changes to a PR, at a minimum, you should always run pixi run fast-lint
. This is designed to run
in a few seconds for repeated runs and should catch the more trivial issues to avoid wasting CI time.
We recommend adding the Rerun pre-push hook to your local checkout, which among other-things will run
pixi run fast-lint
for you.
To install the hooks, simply copy them into the .git/hooks
directory of your local checkout.
cp hooks/pre-push .git/hooks/pre-push
chmod +x .git/hooks/pre-push
or if you prefer you can configure git to use this directory as the hooks directory:
git config core.hooksPath hooks
You can use bacon to automatically check your code on each save. For instance, running just bacon
will re-run cargo clippy
each time you change a Rust file. See bacon.toml
for more.
You can set up sccache
to speed up re-compilation (e.g. when switching branches). You can control the size of the cache with export SCCACHE_CACHE_SIZE="256G"
.
You can view higher log levels with export RUST_LOG=trace
.
Debug logging is automatically enabled for the viewer as long as you're running inside the rerun
checkout.