Contributing¶

Contributions are welcome. Every little bit helps, and credit is always given.

Ways to contribute¶

Report bugs¶

Report bugs at https://github.com/trungdong/prov/issues. Include your operating system and version, any details about your local setup that might help, and the steps to reproduce the bug.

Fix bugs or implement features¶

Look through the issues. Anything tagged “bug” or “feature” is open to whoever wants to work on it.

Write documentation¶

More documentation is always useful, whether in the official docs, in docstrings, or as blog posts and articles elsewhere.

Propose a feature¶

File an issue at https://github.com/trungdong/prov/issues. Explain how the feature would work and keep the scope as narrow as possible, so that it is easier to implement. This is a volunteer-driven project.

Set up for development¶

Fork the prov repository on GitHub.

Clone your fork:

git clone git@github.com:your_name_here/prov.git

Create the development environment with uv, which manages the project virtualenv for you:
```
cd prov/
uv sync --extra rdf --extra xml --extra dot --extra graph
```
The full test suite needs all four extras. docs/dependencies.md explains what each dependency is for.
Install the pre-commit hooks:
```
uv run pre-commit install
```
The hooks run ruff (lint and format) and hygiene checks (trailing whitespace, end-of-file newlines, YAML and TOML validation) on every commit.

Create a branch:

git checkout -b name-of-your-bugfix-or-feature

Make your changes, then run the tests on every supported interpreter:
```
for py in 3.10 3.11 3.12 3.13 3.14 3.15 pypy3.11; do uv run --python $py --extra rdf --extra xml --extra dot --extra graph pytest || break; done
```
The first run downloads any interpreter you do not already have cached.

Then run the static checks, which CI also runs:
```
uv run mypy src
uv run ruff check src/ benchmarks/
uv run ruff format --check src/ benchmarks/
```
mypy checks the tests under the same strict settings as the library, so a new test module needs type annotations, including -> None on each test function. Older test modules that do not pass yet are listed under [[tool.mypy.overrides]] in pyproject.toml. Do not add a module to that list. If your change makes a listed module pass, delete its name.

Commit and push your branch:

git add .
git commit -m "Your detailed description of your changes."
git push origin name-of-your-bugfix-or-feature

Open a pull request on GitHub.

Pull request guidelines¶

Include tests.
If the pull request adds functionality, update the docs. Give new functions a docstring and add the feature to the list in README.md.
The pull request must pass on CPython 3.10 to 3.15 and on PyPy 3.11. The automated checks at the bottom of the pull request run the full matrix.
The benchmark check times your change and the target branch on one CI runner. It is advisory and never blocks a merge. If it is red, or if your change is meant to alter speed, run uv run python benchmarks/ab.py main --python 3.12 and put its table in the pull request. benchmarks/README.md describes the script.

Licensing¶

prov is released under the MIT licence (see LICENSE). By submitting a contribution you agree that it is licensed under the same terms, with no additional restrictions. The licence that applies to your contribution inbound is the licence the project applies outbound. There is no contributor licence agreement to sign.