Contribution Requirements

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.

Branch Requirements

Branches must start with one of the following prefixes (e.g. <prefix>/<your-branch-name>). 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)

release

Reserved for maintainers to prepare for the release of a new version.

Documentation Requirements

Docstrings

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.

reStructuredText Formatting

In general, we loosely follow the Python Style Guide for documentation.

Note

Not all documentation pages follow this yet. If the page you are updating deviates from this format, adapt to the format of the page.

Headings

Section headers are created by underlining (and optionally overlining) the section title with a punctuation character, at least as long as the text.

  1. # with overline, for h1 (generally only one per file, at the top of the file)

  2. * with overline, for h2

  3. =, for h3

  4. -, for h4

  5. ^, for h5

  6. ", 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.

Example

#########
Heading 1
#########


*********
Heading 2
*********

Heading 3
=========

Heading 4
---------

Heading 5
^^^^^^^^^

Heading 6
"""""""""

.. rubric:: Non-indexed Heading


*********
Heading 2
*********

Heading 3
=========

PR Requirements

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 make test.

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.