Please review our Getting Started Guide for Developers before working on your contribution. It contains information on setting up a development environment to make following some of these requirements easier.
Branches must start with one of the following prefixes (e.g.
This is due to how labels are applied to PRs.
If the branch does not meet the requirement, any PRs from it will be blocked from being merged.
- bugfix | fix | hotfix
The branch contains a fix for a big.
- feature | feat
The branch contains a new feature or enhancement to an existing feature.
- docs | documentation
The branch only contains updates to documentation.
- maintain | maint | maintenance
The branch does not contain changes to the project itself to is aimed at maintaining the repo, CI/CD, or testing infrastructure. (e.g. README, GitHub action, integration test infrastructure)
Reserved for maintainers to prepare for the release of a new version.
In general, we loosely follow the Google Python Style Guide for Comments and Docstrings.
We use the
napoleon extension for Sphinx to parse docstrings.
Napoleon provides an Example Google Style Python Docstring that can be referenced.
In general, we loosely follow the Python Style Guide for documentation.
Not all documentation pages follow this yet. If the page you are updating deviates from this format, adapt to the format of the page.
Section headers are created by underlining (and optionally overlining) the section title with a punctuation character, at least as long as the text.
#with overline, for h1 (generally only one per file, at the top of the file)
*with overline, for h2
=, for h3
-, for h4
^, for h5
", for h6
h1 and h2 should have two blank lines separating them from sections with headings of the same level or higher.
A ‘’rubric’’ directive can be used to create a non-indexed heading.
######### Heading 1 ######### ********* Heading 2 ********* Heading 3 ========= Heading 4 --------- Heading 5 ^^^^^^^^^ Heading 6 """"""""" .. rubric:: Non-indexed Heading ********* Heading 2 ********* Heading 3 =========
In order for a PR to be merged it must be passing all checks and be approved by at least one maintainer.
Some of the checks can be run locally using
make lint and
To be considered for approval, the PR must meet the following requirements.
PR title must be a brief explanation of what was done in the PR (think commit message).
PR body must comply with the formatting and prompts provided in the template (automatically applied when creating a PR on GitHub). At a minimum the following should be provided in the body of the PR:
A summary of was done.
Explain why this change is needed.
Detail the changes that were made (think CHANGELOG).
Include tests for any new features or changes to existing features. (unit tests and integration tests depending on the nature of the change)
Documentation was updated for any new feature or changes to existing features.