Contribution Guidelines#

To contribute to HyperVehicle, please read the instructions below to maintain the styling of the code.

Seek Feedback Early#

Please open an issue before a pull request to discuss any changes you wish to make.

Setting up for Development#

  1. Create a new Python virtual environment to isolate the package. You can do so using venv or anaconda.

  2. Install the code in editable mode using the command below (run from inside the hypervehicle root directory).

pip install -e .[all]

  1. Install the pre-commit hooks. This will check that your changes are formatted correctly before you make any commits.

pre-commit install

  1. Start developing! After following the steps above, you are ready to start developing the code. Make sure to follow the guidelines below.

Developing HyperVehicle#

  • Before making any changes, fork this repository and clone it to your machine.

  • Run black on any code you modify. This formats it according to PEP8 standards.

  • Document as you go: use numpy style docstrings, and add to the docs where relevant.

  • Write unit tests for the code you add, and include them in tests/. This project uses pytest.

  • Commit code regularly to avoid large commits with many unrelated changes.

  • Write meaningful commit messages, following the Conventional Commits standard. This is used for the purpose of maintaining semantic versioning and automated changelogs. The Python package commitizen is a great tool to help with this, and is already configured for this repo. Simply stage changed code, then use the cz c command to make a commit. If you do not wish to do this, your commits will be squashed before being merged into main.

  • Open a Pull Request when your code is complete and ready to be merged.

Building the Docs#

To build the documentation, run the commands below.

cd docs/
make html
xdg-open build/html/index.html

If you are actively developing the docs, consider using sphinx-autobuild. This will continuosly update the docs for you to see any changes live, rather than re-building repeatadly. From the root directory, run the following command:

sphinx-autobuild docs/source/ docs/build/html --open-browser