Skip to content

Latest commit

 

History

History
52 lines (38 loc) · 4.05 KB

CONTRIBUTING.md

File metadata and controls

52 lines (38 loc) · 4.05 KB
Raw

Contributing

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 forks of the main repo. Make contributions in dedicated development/feature branches on your forked repositories, e.g. if you are implementing a specific GraphBuiler class you could create a branch named add-euclidean-graph-builder 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:
    • standard python coding conventions, e.g. PEP8
    • docstring (Google-style) and type hinting as necessary,
    • unit tests as necessary,
    • clean coding practices, see e.g. here.

Conventions

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

Code quality

To ensure consistency in code style and adherence to select best practices, we recommend 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 comes with 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, and flake8, mypy, and pydocstyle will check for errors and adherence to PEP8, PEP257, and static typing. See an illustration of the concept below: pre-commit pipeline Image source: https://ljvmiranda921.github.io/notebook/2018/06/21/precommits-using-black-and-flake8/

Version control best practices

From "Software Best Practices Effective Version Control", Alex Olivas, IceCube Bootcamp 2020:

  • Make the commits small enough that they don't break the code.
    • What constitutes "broken" code? Doesn't compile. Tests don't pass.
  • Do not commit something that covers more than one change: E.g. git commit -m 'Refactor and critical bugfix' is bad.
  • Do not wait until the end of the day or week to commit.
  • Do not mix functional changes with whitespace cleanups.
  • Do write good commit messages. Examples:
    • Good commit message: "Fixes issue #123: Use std::shared_ptr to avoid memory leaks. See C++ Coding Standards for more information."
    • Bad commit message: "blerg"

Others:

  • Keep backward compatibility in mind when you change code.