Contributing
============

Humulus has been a personal project of mine, and I hope others will find it
useful. As a user and fan of open source, I welcome all contributions!

This guide is intended to help you contribute to this project with minimal
fuss. Please always feel free to open an issue to ask questions!

Issues
------

Do not hesitate to open issues if you have questions on how to use Humulus, or
if you think you've found a bug. Please provide any information that you may
find relevant.

Pull Requests
-------------

I welcome all pull requests!

For all pull requests, I ask the following:

1. Your pull request should address an open issue. If you'd like to contribute
   an enhancement, please open an issue first, describing what you'd like to
   accomplish.
2. Your code should pass all tests.
3. Your code should not decrease coverage of the tests.
4. Your code must have been passed through Black_. The ``pyproject.yml`` file
   is configured to limit line lengths to 79 characters.
5. Your code must pass the Flake8_ checks and your documentation must pass the
   doc8_ checks.
6. Your code should work with Python 3.6 and newer.
7. You agree to license your contribution under the `Apache 2.0 License`_. You
   retain your copyright. Add a copyright notice to the top of the file.

.. _Black: https://black.readthedocs.io/en/stable/
.. _Flake8: http://flake8.pycqa.org/en/latest/
.. _doc8: https://github.com/PyCQA/doc8
.. _`Apache 2.0 License`: https://www.apache.org/licenses/LICENSE-2.0


Build environment
-----------------

All requirements for developing this project are in the
``requirements-dev.txt`` file. Also, use `pre-commit`_ to help ensure your code
will pass the linting process.

::

    pip install -r requirements-dev.txt
    pre-commit install

.. _`pre-commit`: https://pre-commit.com/

Coverage tests
--------------

Run your code through coverage tests and make sure it passes. Humulus uses
pytest_ and Coverage.py_ to run tests. If you're contributing new code, please
add your own tests.

::

    coverage run -m pytest
    coverage report -m

.. _pytest: https://pytest.org/en/latest/
.. _Coverage.py: https://coverage.readthedocs.io/en/v4.5.x/