Contributing

Thank you for your interest in this project!

DiffeRT is mainly a one-person project, developed to support the author’s research during his PhD. However, it is also open source so that anyone can use this tool for its own research.

We hope that, by making this tool available to the public, other researchers will be able to benefit from it!

Reporting an issue

If you think you found a bug, an error in the documentation, or wish there was some feature that is currently missing, we would love to hear from you!

The best way to reach us is via the GitHub issues. If your problem is not covered by an already existing (closed or open) issue, then we suggest you create a new issue. You can choose from a list of templates, or open a blank issue if your issue does not fit one of the proposed topics.

The more precise you are in the description of your problem, the faster we will be able to help you!

If you rather have a question than a problem, then it is probably best suited to ask it in the Q&A category of the discussions.

Local development

If you want to develop your own version of this package, e.g., to later submit a pull request, then you need to install this package from source.

Depending on what you aim to do, the following sections may help you.

Attention

If you don’t plan on changing the Rust code (differt_core package), we recommend that you check out the building without Rust section.

Updating the differt-core package

While the differt package is updated automatically (because built in -e edit mode) whenever you update a Python file, this is not true for the differt_core package and its Rust files.

If you make any change to the Rust code of the latter, you need to rebuild it so that changes are taken into account:

uv sync --reinstall-package differt-core

Alternatively, you can install an import hook that will recompile the differt_core package each time it is imported:

just hook-install

While recompiling a package that hasn’t changed is relatively fast, it may be better to disable the import hook when it is not needed. You can do so by uninstalling it:

just hook-uninstall

Documentation

To generate the documentation, please run the following (from the root folder):

just docs/build

Finally, you can open docs/build/html/index.html to see the generated docs.

Other recipes are available, and you can list them with just docs/.

Testing

Both Rust and Python codebases have their own tests and benchmarks.

The following commands assume that you execute them from the root folder.

Testing Rust code

You can test Rust code using Cargo:

just test-rust

or benchmark it:

just bench-rust

Testing Python code

Similarly, you can test Python code with Pytest:

just test-python

or benchmark it:

just bench-python

Proposing changes

Once you feel ready and think your contribution is ready to be reviewed, create a pull request and wait for a reviewer to check your work!

Many thanks to you!

Tip

If you are not familiar with GitHub pull requests, please check out their Hello World tutorial or Fireship’s 100 seconds introduction video.