Contributing¶
Thanks for considering helping out. We don’t bite. :-)
Reporting issues¶
Bugs and other tasks are tracked on GitHub.
Check whether the issue exists already. (Be sure to also check closed ones.)
Report which version of Clize the issue appears on. You can obtain it using:
pip show clize
For documentation-related bugs, you can either look at the version in the page URL, click the “Read the docs” insigna in the bottom-left corner or the hamburger menu on mobile.
When applicable, show how to trigger the bug and what was expected instead. Writing a testcase for it is welcome, but not required.
Submitting patches¶
Patches are submitted for review through GitHub pull requests.
- Follow PEP 8.
- When fixing a bug, include a test case in your patch. Make sure correctly tests against the bug: It must fail without your fix, and succeed with it. See Running the test suite.
- Submitting a pull request on GitHub implies your consent for merging, therefore authorizing the maintainer(s) to distribute your modifications under the project’s license.
Implementing new features¶
Before implementing a new feature, please open an issue on GitHub to discuss it. This ensures you do not work on a feature that would be refused inclusion.
Add tests for your feature to the test suite and make sure it completes
on all supported versions of Python. Make sure it is fully
tested using the cover
target.
Feel free to submit a pull request as soon as you have changes you need feedback on. In addition, TravisCI will run the test suite on all supported platforms and will perform coverage checking for you on the pull request page.
Running the test suite¶
The test suite can be run across all supported versions using, tox
:
pip install --user tox
tox
If you do not have all required Python versions installed or wish to save time when testing you can specify one version of Python to test against:
tox -e pyXY
Where X
and Y
designate a Python version as in X.Y
. For instance,
the following command runs the test suite against Python 3.4 only:
tox -e py34
Branches linked in a pull request will be run through the test suite on TravisCI and the results are linked back in the pull request. You can use this if installing all supported Python versions is impreactical for you.
coverage.py is used to measure code coverage. New code is expected to have full code coverage. You can run the test suite through it using:
tox -e cover
It will print the measured code coverage and generate webpages with
line-by-line coverage information in htmlcov
. Note that the cover
target requires Python 3.4.