Contributions are welcome, and they are greatly appreciated! 😃 This project follows the all-contributors specification: every little bit helps and credit will always be given. ✨
Note
This project is released with a respect oriented Contributor Code of Conduct based on the Contributor Covenant. By participating in this project you agree to abide by its fair terms.
You can contribute in many ways:
Please report bugs at https://github.com/renemarc/countdoom/issues.
If you are reporting a bug, please include:
- Your operating system name and version.
- Any details about your local setup that might be helpful in troubleshooting.
- Detailed steps to reproduce the bug.
Look through the GitHub issues for bugs or features. Anything tagged with
bug
, enhancement
and help wanted
is open to whoever wants to
implement it. You rock!
Countdoom could always use more documentation, whether as part of the official Countdoom docs, in docstrings, or even on the web in blog posts, articles, and such.
The best way to send feedback is to file an issue at https://github.com/renemarc/countdoom/issues.
If you are proposing a feature:
- Explain in detail how it would work.
- Keep the scope as narrow as possible, to make it easier to implement.
- Remember that this is a volunteer-driven project, and that contributions are welcome 😃
Ready to contribute? Here's how to set up Countdoom for local development.
Note
While Countdoom runs on Python 3.5+, many dev tools will require Python 3.6+.
- Fork the Countdoom repo on GitHub.
- Clone your fork locally:
$ git clone git@github.com:YOUR_USERNAME_HERE/countdoom.git
3. Create a virtual environment for local development:
$ cd countdoom/ $ python -m venv .venv $ . .venv/bin/activate
- Install your local copy with all dependencies using pip:
$ pip install -e .[dev]
Alternatively, you can also use
setup.py
to install the above requirements:$ pip install --upgrade setuptools $ python setup.py develop
- Create a branch for local development:
$ git checkout -b name-of-your-bugfix-or-feature
Now you can make your changes locally!
6. To help you test your code, you can use pyenv version manager to install concurrent Python versions in local virtual environments (unless already installed):
$ pyenv install "3.5.9" $ pyenv install "3.6.10" $ pyenv install "3.7.6" $ pyenv install "3.8.1" $ pyenv install "pypy3.6-7.3.0" $ pyenv local "3.5.9" "3.6.10" "3.7.6" "3.8.1" "pypy3.6-7.3.0"
7. When you're done making changes, you can test the results with makefile. This will verify that your changes pass this opinionated code quality gauntlet 🛡️:
- black code formatter
- flake8 style enforcer
- isort imports checker
- mypy static type checker
- pylint code analyzer
- pytest python tests
- tox multi-version automated testing tool
$ make test-all $ make coverageAlternatively, you can run the test suites individually:
$ black --check --diff . $ flake8 $ isort --check -rc . $ mypy $ pylint setup.py countdoom examples $ pylint --disable=E0401 tests/*.py $ pytest $ tox -e py35 $ tox -e py36 $ tox -e py37 $ tox -e py38 $ tox -e pypy3 $ coverageNote
To run a subset of tests, you can mention either the whole file or just one function:
$ pytest tests/test_client.py $ pytest tests/test_client.py::test_valid_countdown
8. Commit your changes ideally using Conventional Commits comment style and push your branch to GitHub. To help catch any gotchas, pre-commit will automatically run various code quality linters on any modified files:
$ git add . $ git commit -m "type(scope): active voice summary of changes" $ git push origin name-of-your-bugfix-or-feature
9. Submit a pull request through GitHub.
Before you submit a pull request, check that it meets these guidelines:
- The pull request should include tests.
- If the pull request adds functionality, the docs should be updated. Put
your new functionality into a function with a docstring, mention the change
in the
CHANGELOG.rst
, and if necessary add the feature to the list inREADME.md
(repo) andREADME.rst
(docs). - The pull request should work for Python 3.5, 3.6, 3.7, 3.8, and for PyPy3. Check https://travis-ci.com/renemarc/countdoom/pull_requests and make sure that the tests pass for all supported Python versions.
A reminder for the maintainers on how to deploy. Make sure all your changes are committed (including an entry in CHANGELOG.rst). Then run:
$ bumpversion patch # possible: major / minor / patch
$ git push
$ git push --tags
Travis CI will then deploy to the Python Package Index if tests pass.