Contributing

Conversations about development and issues take place in the GitHub repository. Feel free to open a new issue if you have something to discuss.

Setting up a local installation

Make sure you have a reasonably modern C++ compiler. Any recent version that supports (most of) the C++20 standard should do. Once you have a compiler installed, you can proceed by forking the pyvrp repository from the GitHub website. Then, clone your new fork to some local environment:

git clone https://github.com/<your username>/PyVRP.git

Now, change into the PyVRP directory, and set-up the virtual environment using poetry:

cd PyVRP

pip install --upgrade poetry
poetry install --with examples,docs,dev

This might take a few minutes, but only needs to be done once. Now make sure everything runs smoothly, by executing the test suite:

poetry run pytest

Note

If you use pre-commit, you can use our pre-commit configuration file to set that up too. Simply type:

pre-commit install

After this completes, style and typing issues are automatically checked whenever you make a new commit to your feature branch.

Building the Python extensions

For performance, the PyVRP packages uses a number of Python extensions that are written in C++. These extensions are built every time poetry install is used, but that command builds everything in release mode. While developing, one typically wants to use debug builds. These (and more) can be made by using the build_extensions.py script directly, as follows:

poetry run python build_extensions.py

The script takes a number of command-line arguments, which you can discover using

poetry run python build_extensions.py --help

We use the Meson build system to compile the C++ extensions. Meson is configured using the meson.build file in the repository root. You should not have to touch this file often: all installation is handled via the build_extensions.py script.

Committing changes

We use pull requests to develop the pyvrp package. For a pull request to be accepted, you must meet the below requirements. This greatly reduces the job of maintaining and releasing the software.

  • One branch. One feature. Branches are cheap and GitHub makes it easy to merge and delete branches with a few clicks. Avoid the temptation to lump in a bunch of unrelated changes when working on a feature, if possible. This helps us keep track of what has changed when preparing a release.

  • Commit messages should be clear and concise. This means a subject line of less than 80 characters, and, if necessary, a blank line followed by a commit message body.

  • Code submissions should always include tests.

  • Each function, class, method, and attribute needs to be documented using docstrings. We conform to the NumPy docstring standard.

  • If you are adding new functionality, you need to add it to the documentation by editing (or creating) the appropriate file in docs/source/.

  • Make sure your documentation changes parse correctly. See the documentation in the docs/ directory for details on how to build the documentation locally.

Note

Please use the “Pull request” template on GitHub when opening a pull request.