pyurbantz/docs/contributing.rst

Contributing

Contributions to the project are greatly appreciated.

Bugs and suggestions

You may submit an issue to GitLab to warn of any bugs, ask for new features, or ask any questions that are not answered in this documentation.

When reporting a bug, do not forget to put in your version of Python and your version of pyurbantz. This will greatly help when troubleshooting, as most errors often come from version incompatibilities.

Development

Setup

You will need a virtual envionment to work properly. virtualenvwrapper is recommended:

git clone https://gitlab.com/Lucidiot/pyurbantz
cd pyurbantz
mkvirtualenv -a . pyurbantz
pip install -e .[dev]

This will clone the repository, create a virtual environment named pyurbantz, then tell pip to let the package be editable (-e). The [dev] suffix adds the extra requirements useful for development.

Unit tests

Unit tests use the standard unittest package; you may run them using the standard setup.py command:

./setup.py test

Tests coverage

I aim for 100% coverage on all of my Python packages whenever I add unit tests to them; this package is no exception. CI checks use the coverage Python package and codecov to check for test coverage. To get test coverage data locally, run:

coverage run setup.py test

You may then get a short coverage summary in your terminal:

coverage report

Or generate an HTML report in a htmlcov folder, which can be browsed offline using your favorite web browser and shows line by line coverage:

coverage html

If you are having issues reaching 100% coverage, try to still add some tests, and mention your issues when creating a pull request to the GitLab repository.

Linting

The source code follows the PEP 8 code style and performs CI checks using the flake8 tool. To perform the same checks locally, run flake8 on the root directory of this repository.

Documentation

The documentation you are reading is generated by the Sphinx tool. The text files that hold the documentation's contents are written in reStructuredText and are available under the /docs folder of the GitLab repository. They are also subject to linting using the doc8 tool.