diff --git a/docs/contributing.rst b/docs/contributing.rst index 5a1988f..4e81445 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -1,2 +1,70 @@ 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/