Contributing ¶

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:

Types of contributions ¶

Report bugs¶

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.

Fix bugs¶

Look through the GitHub issues for bugs. Anything tagged with bug and help wanted is open to whoever wants to implement it.

Implement features¶

Look through the GitHub issues for features. Anything tagged with enhancement and help wanted is open to whoever wants to implement it.

Write documentation¶

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.

Submit feedback¶

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 😃

Get started! ¶

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 coverage
Alternatively, 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
$ coverage
Note

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 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): detailed description of your changes."
$ git push origin name-of-your-bugfix-or-feature

9. Submit a pull request through the GitHub website.

Pull request guidelines ¶

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 in README.md (repo) and README.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.

Deploying ¶

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.