Skip to content

Contributing

First, thank you for considering a contribution to this project!

This document should help detail the project's expectations about contributions.

Development tools

This project uses the following tools for development:

  • Rust
  • uv for managing Python dependencies.
  • yarn for managing JavaScript dependencies. Actually, yarn@4.9.2 is checked into this repository, so really Node.js needs to be installed with corepack enabled. fnm is recommended to install Node.js.
  • nur for running common development tasks
  • cargo-nextest for running Rust tests
  • cargo-llvm-cov for collecting Rust code coverage
  • clang-format v14 for formatting C++ sources
  • cbindgen for generating the C++ header file for the C++ binding

Optional tools

Code style

This project's CI leverages pre-commit to ensure

  • line endings all use LF (not CRLF)
  • lines have no trailing whitespace
  • files end with a blank line
  • valid syntax is used in all yaml and toml files
  • no large files (greater than 500 kB) are added
  • no unknown or misspelled words are present

To run pre-commit, you can use uv or nur:

uv run pre-commit run --all-files

The following nur command uses the above uv command

nur pre-commit

Additional options are shown and documented with nur pre-commit -h.

Tip

To register the pre-commit hooks, use:

uv run pre-commit install

Linting code

This project uses several tools to lint and format various language syntaxes:

Tool Description Managed by
clippy For linting Rust sources rustup
rustfmt For formatting Rust sources rustup
clang-format For formatting C++ sources Independently installed; v14 is expected.
ruff For formatting and linting Python sources uv
oxlint For linting Javascript/Typescript sources yarn
prettier For formatting Javascript/Typescript sources yarn

All of these tools can be invoked with a nur command:

nur lint

Running tests

This project uses unit tests to ensure expected behavior. Each language employs its own testing harness.

Rust tests

Code coverage is calculated only from the mk-pass Rust crate/library.

First ensure that the following cargo-managed binaries are installed:

Use nur to run the Rust tests:

nur test

Additional options are shown and documented with nur test -h.

Tip

Different test profiles are still defined in .config/nextest.toml. The above command uses the "default" profile, but to mimic the CI, use:

nur test --profile ci

To generate a coverage report:

nur test llvm-cov --open

The --open part is optional. It opens the built coverage report in your default browser.

Tip

Coverage data is uploaded to codecov using a lcov.info file. A lcov.info file can be generated with

nur test lcov

Python tests

For the Python binding, pytest is used, but the binding needs to be installed (and up-to-date) first. This can be done using the following nur command:

nur test py

Additional options are shown and documented with nur test py -h.

Javascript/Typescript tests

For the Node.js binding, ava is used, but the binding needs to be built (and up-to-date) first. This can be done using the following nur command:

nur test js

Additional options are shown and documented with nur test js -h.

C++ tests

For the C++ binding, CMake and CTest are used, but the binding's generated header file needs to be up-to-date first. This can be done using the following nur command:

nur test cpp

Additional options are shown and documented with nur test cpp -h.

Note

This project uses corrosion to integrate the Rust sources with CMake. In this project, CMake is configured to automatically download corrosion if it is not discovered/installed on the system.

Generating docs

This project's documentation is comprised of HTML output from several different documentation tools.

Tool Description Managed by
rustdoc For documenting the Rust API rustup
doxygen For documenting the C++ API Independently installed (recommend v1.14.0)
typedoc For documenting the Javascript/Typescript API yarn
mkdocs For wrapping the above tools' output (and generating the Python API documentation) into a single site uv which also manages mkdocs plugins/theme

To view the docs locally, use

nur docs --open

The --open part is optional. It opens the built docs in your default browser.

To simply build the docs without spawning a local server (as done in CI), the --built flag can be used:

nur docs --build

Additional options are shown and documented with nur docs -h.