Skip to content

Latest commit

 

History

History
140 lines (103 loc) · 4.63 KB

CONTRIBUTING.rst

File metadata and controls

140 lines (103 loc) · 4.63 KB

Contributing Guidelines

Please follow these guidelines for contributing to this project.

Repository Management

  • Fork this project into your own repository.
  • Follow the version control guidelines.
  • No changes should reach the main branch except by way of a pull request.

Submitting Issues

Create an issue to report bugs or request enhancements. Better yet, if you are able, fix the problem yourself and submit a pull request.

Bug Reports

When reporting a bug, please provide the steps to reproduce the problem and any details that could be important such as whether this is the first time this has happened or whether others are experiencing it.

Handling Pull Requests

  • Pull requests must include:
    • Title describing the change
    • Description explaining the change in detail
    • Tests
  • A maintainer will respond to Pull Requests with one of:
    • Ship It, LGTM, 🚢, or some other affirmation
    • What must be changed
    • Won't accept and why

Note

  • Submitting a draft pull request is a good way to get feedback from maintainers if you are unsure about your changes.
  • A pull request that has been approved may not be merged immediately.
  • You may be asked to rebase or squash your commits to keep an orderly version control history.

Using Version Control

  • Fork the central repository and work from a clone of your own fork.
  • Follow the topic branch model and submit pull requests from branches named according to their purpose.
  • Review the GitHub Flow documentation and, in general, try to stick to the principles outlined there.

Writing Code

Writing code is a creative process and there will always be exceptions to the rules, but it's good to maintain certain standards. In general, please follow these code conventions.

Coding Style

  • Code in this project must be formatted with black.
  • Code in this project must be linted with flake8.
  • Try to follow PEP 8 guidelines.
  • Try to respect the style of existing code.

Coding style checks are bundled into the static analysis automation in this repository's tox configuration. To validate your coding style run

tox -e static

Test Environment

  • Code must be tested. Write or update related unit tests to avoid repeated manual testing.
  • Tests for this project are written using the pytest framework and executed via tox.
  • While it isn't always achievable this project strives to maintain 💯% test coverage.
  • In addition to unit testing code in this project is
    • statically type checked using mypy
    • formatted with black
    • linted using flake8

Here are some example invocations for running unit tests/static analysis.

tox                       # Build and test the project
tox -e py39               # in a specific environment
tox -e py39 -- --pdb      # with extra options
                          # or
tox -e py39 --devenv venv # create a development environment
venv/bin/python -V        # and call scripts/binaries in it.

Documentation

  • Public interfaces must be thoroughly documented. At a minimum this includes inputs, return types, exceptions raised, and surprising behavior like state changes.
  • Documentation for this project is written in reStructuredText with the Google style and generated with Sphinx.

To generate documentation run

tox -e docs