Contributing To GraphNeT

To make sure that the process of contributing is as smooth and effective as possible, we provide a few guidelines in this contributing guide that we encourage contributors to follow.

GitHub issues

Use GitHub issues for tracking and discussing requests and bugs. If there is anything you’d wish to contribute, the best place to start is to create a new issues and describe what you would like to work on. Alternatively you can assign open issues to yourself, to indicate that you would like to take ownership of a particular task. Using issues actively in this way ensures transparency and agreement on priorities. This helps avoid situations with a lot of development effort going into a feature that e.g. turns out to be outside of scope for the project; or a specific solution to a problem that could have been better solved differently.

Pull requests

Develop code in a fork of the main repo. Make contributions in dedicated development/feature branches on your forked repositories, e.g. if you are implementing a specific GraphDefinition class you could create a branch named add-euclidean-graph-definition on your own fork.

Create pull requests from your development branch into graphnet-team/graphnet:main to contribute to the project. To be accepted, pull requests must:

• pass all automated checks,

• be reviewed by at least one other contributor. These reviews should check for:

  1. standard python coding conventions, e.g. PEP8

  2. docstring (Google-style) and type hinting as necessary

  3. unit tests as necessary

  4. clean coding practices, see e.g. here.

Conventions

This repository aims to support python 3 version that are actively supported (currently >=3.8). Standard python coding conventions should be followed:

• Adhere to PEP8 black

• Use pylint / flake8 and black to ensure as clean and well-formatted code as possible

• When relevant, adhere to clean code practices

Code quality

To ensure consistency in code style and adherence to select best practices, we require that all developers use black, flake8, mypy, pydocstyle, and docformatter for automatically formatting and checking their code. This can conveniently be done using pre-commit hooks. To set this up, first make sure that you have installed the pre-commit python package. It is included when installing GraphNeT with the develop tag, i.e., pip install -e .[develop]. Then, do

pre-commit install

Then, everytime you commit a change, your code and docstrings will automatically be formatted using black and docformatter, while flake8, mypy, and pydocstyle will check for errors and adherence to PEP8, PEP257, and static typing. See an illustration of the concept below:

Image source: https://ljvmiranda921.github.io/notebook/2018/06/21/precommits-using-black-and-flake8/