Skip to content

Latest commit

 

History

History
88 lines (70 loc) · 4.56 KB

CONTRIBUTING.md

File metadata and controls

88 lines (70 loc) · 4.56 KB
Raw

Contributing

Documentation

Documentation is built using Sphinx with the autodoc extension. In order to build the documentation, you can install the necessary packages and then use make:

pip install -r doc_requirements.txt
make make -C docs/ html

All documentation source files and configuration are in the docs/source directory. Documentation for all modules is autogenerated and populated in the reference subdirectory. Additional reference material, such as tutorials, should be referenced in index.rst.

Testing

Changes are gated on:

  • Passing unit tests with minimum supported library versions
  • 100% test coverage
  • PEP8 style compliance, with some exceptions in the tox file
  • Incrementing the package version number in setup.py

Additionally, PRs are checked against (but not blocked by):

  • Passing unit tests with latest nominally supported versions of all dependencies
  • Documentation builds without warnings

In order to run tests locally, you'll need to install additional packages:

pip install -r test_requirements.txt

A test runner is available in scripts/run_tests.sh, which gives a convenient one-line invocation for testing.

As it can be easy to forget to verify these prior to pushing, it's possible to use git hooks to enforce compliance during normal workflows. Consider editing .git/hooks/pre-commit or .git/hooks/pre-push (or adding them and marking them as executable: chmod +x <file>). For example, you could set your local .git/hooks/pre-commit to be

scripts/run_tests.sh --quiet --exitfirst

to make sure you're not on the main branch, you've incremented the package version, you pass the linter and you have complete, passing tests.

Coding Style

This project follows PEP8, with the following exception:

  • Maximum line length is 99 characters

Additionally:

  • Type hints are strongly encouraged, but not required.
  • Positional arguments are strongly discouraged for methods with multiple arguments, especially for multiple arguments of the same type. Keyword-only arguments are preferred instead. Every positional argument should be required.

For additional (non-binding) inspiration, check out the Google Python Style Guide.

Branching strategy

This project currently follows a feature branch workflow:

  • Feature branches and bugfixes are branched off of main and then opened as PRs into main
  • Every PR must contain a version bump following semantic versioning
  • Backport branches for historical versions are created as-needed off of main; backports are branched off of and merged into them

During periods of rapid development activity, the branching strategy may change to accommodate it, but it will be kept up to date here.

Release process

The main branch does not continuously deploy to pypi. Rather, releases are cut explicitly by using GitHub's releases. To create a release:

  • Catalog the changes in order to inform release notes
    • To do this through the GitHub interface:
      • Navigate to the GitHub compare page
      • Set the base to the most recent tag (which corresponds to the most recent release)
      • Set the compare to the commit you want to deploy, typically main
    • You can use git diff as well, if you prefer
  • In another tab, navigate to the GitHub release creation page
  • Set the Target to the commit you want to deploy, typically main
  • Set the Tag version to v{x.y.z} where x.y.z is the version in setup.py, e.g. v1.2.3
  • Set the Release title to "GEMD v{x.y.z} is released!"
  • Populate the release notes with a 1 or 2 sentence summary and What's New, Improvements, Fixes, and Deprecated sections, as appropriate

Travis will trigger the deploy due to the addition of the tag. Only commits on the main or backports branches can be released, but it need not be the most recent commit on the branch. The tests contained within this repository are sufficient to verify a release.