CONTRIBUTING.md

Contributing

How to submit feedback?

The best way to submit feedback is to file an issue.

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.

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 :).

Developer's Guide

Basic Usage 🔢

Before making a PR please run the following

• Optional one time setup: run make use-docker if you need to build/test this with docker
• make lint to check for any format or convention issues
• make test to run all tests

How do I ... ❓

🔧 See available make targets

To see available make targets, simply run make.

🐳 Switch to and from using Docker

To start using Docker, run make use-docker. Every subsequent make command you run will then be run inside the associated container whenever appropriate.

To stop using Docker, run make remove-docker. Every subsequent make command you run will then be run inside your native virtual environment whenever appropriate.

🛠 Add a new pip dependency

New dependencies need to be added to requirements.in. Your requirements.txt will then automatically be updated to reflect those changes the next time a relevant make target is run. Alternatively, you can run make update-requirements.

Note:

• Before any make command is run, requirements are synced so that the development environment matches your requirements.txt exactly i.e. extra packages that are not present in the requirements.txt are removed and any missing packages are installed. This helps providing a consistent environment across platforms, and ensures that whenever requirements change, only minimal updates are performed.
• Check out pip-tools for more information.

🙈 Ignore linting violations

For flake8 violations, you can:

• ignore a rule for a single line of code using a #noqa comment e.g. python x = 1 # noqa: WPS111
• ignore a rule for an entire file by adding it to flake8.per-file-ignores inside setup.cfg.
• exclude an entire file from flake8 checks by adding it to flake8.exclude inside setup.cfg.
• ignore a rule for all files by adding it to the flake8.ignore list inside setup.cfg.

For mypy violations, you can:

• ignore type checking for a single line of code using a # type: ignore comment.
• ignore type checking for an entire file by putting a # type: ignore comment at the top of a module (before any statements, including imports or docstrings).

For pydocstyle violations, you can:

• ignore a rule for a single line of code using a # noqa comment (this can be combined with flake8 exclusions).
• exclude an entire file from pydocstyle checks by excluding it from pydocstyle.match inside setup.cfg.
• ignore a rule for all files by adding it to the pydocstyle.ignore list inside setup.cfg.

For coverage violations, you can:

• exclude a single line of code using a # pragma: no cover comment.
• exclude an entire file from coverage checks by adding it to the coverage:run.omit list inside setup.cfg.
• exclude all lines matching a given pattern by adding it to the coverage:report.exclude_lines list inside setup.cfg.

🧪 Run specific tests

First, get a shell inside your development environment by running make dev-shell.

You can then use the pytest -k option to select tests based on their names, e.g.

python -m pytest -k "included_test"

You can also use "and", "or" and "not" keywords e.g.

python -m pytest -k "included_test or not excluded"

📄 Build and view docs from a local version

You can generate docs locally by running make build-docs. You can then see the generated docs by running

cd docs/build
python -m http.server

and going to http://localhost:8000/

🍪 Update my project to match the cookiecutter which generated it

This project is enabled with cruft to be able to update the template with any improvements made in the cc-python cookiecutter which generated it.

• make check-cc will report if this project is up to date or out of sync with the cookiecutter.
• make update-cc will update this project to be in sync with the cc-python cookiecutter. This can give improvements or new features which are added to the template after this project was created. Note one should do this on a clean branch. After running this it is a good idea to run make all to rebuild everything and ensure things still work after the update.

Badges 📛

Every badge shown below corresponds with a development tool used to maintain this project. Every badge is clickable and links back to that project's github / documentation site:

tools / frameworks used by test suite (i.e. used by make test):

linters used to maintain code quality (i.e. used by make lint):

tools / frameworks used to render documentation (i.e used by make build-docs):

miscellaneous tools used to maintain this project:

New Releases

This section serves as a reminder to the maintainers of this project on how to release a new version of this package to PyPI.

Make sure all your changes are committed, that you have added a new section to the CHANGELOG.md file, and that you have bumpversion installed. Then run:

bumpversion patch  # possible values: major / minor / patch
git push
git push --tags

A new version of zorg will then deploy to PyPI if all CI checks pass.