Skip to content

Contributing to mplhep¤

We are happy to accept contributions to mplhep via Pull Requests to the GitHub repo. To get started fork the repo.

AI Policy¤

AI-assisted contributions are welcome. We ask that you:

  • Disclose that AI was used, and name the tool and model.
  • Review and understand every line you submit. You are responsible for it.
  • Meet the same quality, testing, and style standards as any other contribution.
  • Do not use fully autonomous agents to open issues or pull requests.
  • Respond to review comments yourself.

This applies to issues and comments as well as pull requests. Using AI for translation or grammar help is fine and needs no disclosure.

Unsolicited, undisclosed, or low-effort AI pull requests may be closed at maintainer discretion.

Crediting AI in commits¤

Only humans can be named as co-authors, and an AI can never sign off on a commit.

  • Do not add a Co-authored-by: trailer for an AI. That trailer asserts authorship and a copyright interest — an AI is a tool, not an author, and the work stays yours.
  • Do not let a tool add Signed-off-by: on your behalf. That line certifies the Developer Certificate of Origin, a legal statement only a human can make.

Credit AI assistance with the trailer the Linux kernel standardised in Documentation/process/coding-assistants.rst:

Assisted-by: <harness>:<model>

for example:

Assisted-by: claude-code:claude-opus-5

Put the trailer in the commit. If you also propose a squash message in the pull request body, put it there too.

Bug Reports¤

Please open an issue.

Cloning the repository¤

git clone https://github.com/scikit-hep/mplhep.git

That is all you need — roughly 26 MB.

The built documentation site does not live here. It is published to scikit-hep/mplhep_docs, because keeping the rendered HTML for every released version in this repository meant every contributor downloaded the whole published site just to work on the library. Doc sources stay here, under new_docs/; only the build output is elsewhere.

Installing the development environment¤

python -m pip install --upgrade --editable ".[all]"
Also conveniently accessible as bash install.sh.

Pull Requests¤

Pull Requests Procedure¤

If you would like to make a pull request please:

  1. Make a fork of the project
  2. Clone your fork locally
  3. Install prek and the project's pre-commit hooks
  4. Test your changes with pytest
  5. Commit your changes to a feature branch of your fork, push to your branch
  6. Make a PR

Running the tests¤

You can run the unit tests (which should be fast!) via the following command:

With pytest

pytest --mpl --ignore=tests/test_notebooks.py

Note: This ignores the notebook tests (which are run via papermill) and run somewhat slow.

Make sure to run the complete suite before submitting a PR

python -m pytest -r sa --mpl --mpl-results-path=pytest_results -n 4

With nox

nox -s tests

Making a pull request¤

We follow Conventional Commit for commit messages and PR titles. Pull requests are often squash-merged, and then it is the final commit message — the one proposed in the PR body — that needs to follow the convention. A PR whose commits are already well organised may instead be merged as it is, so it is worth having each of them follow it too.

Generating Reference Visuals¤

If you modified expected outcomes of the tests. New baseline visuals can be generated using this command:

With pytest

 python -m pytest -r sa --mpl -n 4 --mpl-generate-path=tests/baseline

With nox

 nox -s generate_examples_figures

Only include the actually modified baseline images in your PR! Running git add -a and the like will sometimes result in including images which are visually identically but not the same bit-wise.

Linting and Formatting¤

We use prek to manage code formatting and linting. Make sure to run it before committing your changes:

With prek

prek run --all-files

With nox

nox -s lint

Contributing to the documentation¤

The documentation is built using MkDocs and the Material for MkDocs theme. To contribute to the documentation, please look at the new_docs/CONTRIBUTING_DOC.md file for instructions.