How to Contribute
=================
Do you want to contribute fixes or improvements?

   **AWesome!** *Thank you very much, and let's get started.*

Set up a development environment
--------------------------------
The first thing that you need is a development environment so that you can
run the test suite, update the documentation, and everything else that is
involved in contributing.  The easiest way to do that is to create a virtual
environment for your endeavors::

   $ python3 -m venv env

Don't worry about writing code against previous versions of Python unless
you you don't have a choice.  That is why we run our tests using tox.
The next step is to install the development tools that this project uses.
These are listed in *requires/development.txt*::

   $ env/bin/pip install -qr requires/development.txt

At this point, you will have everything that you need to develop at your
disposal.  Use the unittest runner to run the test suite or the coverage
utility to run the suite with coverage calculation enabled::

   $ coverage run -m unittest
   $ coverage report

You can also run the tox utility to verify the supported Python versions::

   $ tox -p auto
   ✔ OK py37 in 2.636 seconds
   ✔ OK py38 in 2.661 seconds
   ✔ OK py39 in 2.705 seconds
   _________________________________________________________________________
     py37: commands succeeded
     py38: commands succeeded
     py39: commands succeeded
     congratulations :)

For other commands, *setup.py* is the swiss-army knife in your development
tool chest.  It provides the following commands:

**./setup.py build_sphinx**
   Generate the documentation using sphinx.

**./setup.py flake8**
   Run flake8 over the code and report style violations.

If any of the preceding commands give you problems, then you will have to
fix them **before** your pull request will be accepted.

Running Tests
-------------
The easiest (and quickest) way to run the test suite is to use the
unittest runner::

   $ python -m unittest tests

That's the quick way to run tests.  The slightly longer way is to run
the tox utility.  It will run the test suite against all of the supported
python versions in parallel.  This is essentially what our CI pipeline
will do when you issue a pull request anyway::

   $ tox -p auto
   ✔ OK py37 in 2.636 seconds
   ✔ OK py38 in 2.661 seconds
   ✔ OK py39 in 2.705 seconds
   __________________________________________________________________________
     py37: commands succeeded
     py38: commands succeeded
     py39: commands succeeded
     congratulations :)

This is what you want to see.  Now you can make your modifications and keep
the tests passing.

Submitting a Pull Request
-------------------------
Once you have made your modifications, gotten all of the tests to pass,
and added any necessary documentation, it is time to contribute back for
posterity.  You've probably already cloned this repository and created a
new branch.  If you haven't, then checkout what you have as a branch and
roll back *master* to where you found it.  Then push your repository up
to github and issue a pull request.  Describe your changes in the request,
if CI pipeline passes then someone will review it, and eventually merge
it back.