.. Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0 .. For details: https://bitbucket.org/ned/coveragepy/src/default/NOTICE.txt .. _contributing: =========================== Contributing to coverage.py =========================== .. :history: 20121112T154100, brand new docs. .. highlight:: console I welcome contributions to coverage.py. Over the years, dozens of people have provided patches of various sizes to add features or fix bugs. This page should have all the information you need to make a contribution. One source of history or ideas are the `bug reports`_ against coverage.py. There you can find ideas for requested features, or the remains of rejected ideas. .. _bug reports: https://bitbucket.org/ned/coveragepy/issues?status=new&status=open Before you begin ---------------- If you have an idea for coverage.py, run it by me before you begin writing code. This way, I can get you going in the right direction, or point you to previous work in the area. Things are not always as straightforward as they seem, and having the benefit of lessons learned by those before you can save you frustration. Getting the code ---------------- The coverage.py code is hosted on a `Mercurial`_ repository at https://bitbucket.org/ned/coveragepy. To get a working environment, follow these steps: #. (Optional, but recommended) Create a virtualenv to work in, and activate it. .. like this: mkvirtualenv -p /usr/local/pythonz/pythons/CPython-2.7.11/bin/python coverage #. Clone the repo:: $ hg clone https://bitbucket.org/ned/coveragepy $ cd coveragepy #. Install the requirements:: $ pip install -r requirements/dev.pip #. Install a number of versions of Python. Coverage.py supports a wide range of Python versions. The more you can test with, the more easily your code can be used as-is. If you only have one version, that's OK too, but may mean more work integrating your contribution. Running the tests ----------------- The tests are written as standard unittest-style tests, and are run with `tox`_:: $ tox py27 develop-inst-noop: /Users/ned/coverage/trunk py27 installed: apipkg==1.4,-e hg+ssh://hg@bitbucket.org/ned/coveragepy@6664140e34beddd6fee99b729bb9f4545a429c12#egg=coverage,covtestegg1==0.0.0,decorator==4.0.10,eventlet==0.19.0,execnet==1.4.1,funcsigs==1.0.2,gevent==1.1.2,greenlet==0.4.10,mock==2.0.0,pbr==1.10.0,py==1.4.31,PyContracts==1.7.12,pyparsing==2.1.10,pytest==3.0.5.dev0,pytest-warnings==0.2.0,pytest-xdist==1.15.0,six==1.10.0,unittest-mixins==1.1.1 py27 runtests: PYTHONHASHSEED='4113423111' py27 runtests: commands[0] | python setup.py --quiet clean develop no previously-included directories found matching 'tests/eggsrc/dist' no previously-included directories found matching 'tests/eggsrc/*.egg-info' py27 runtests: commands[1] | python igor.py zip_mods install_egg remove_extension py27 runtests: commands[2] | python igor.py test_with_tracer py === CPython 2.7.12 with Python tracer (.tox/py27/bin/python) === gw0 [679] / gw1 [679] / gw2 [679] scheduling tests via LoadScheduling ...........ss...................................................................................ss...s.......s...........................s...............................................................................s.....................................................................................................................................................s.........................................................................................s.s.s.s.s.ssssssssssss.ss..................................................s...................................................................s.............................................................................. 649 passed, 30 skipped in 42.89 seconds py27 runtests: commands[3] | python setup.py --quiet build_ext --inplace py27 runtests: commands[4] | python igor.py test_with_tracer c === CPython 2.7.12 with C tracer (.tox/py27/bin/python) === gw0 [679] / gw1 [679] / gw2 [679] scheduling tests via LoadScheduling ............ss................................................................................s..s.....s......s.........................s..........................................................................................s............................................................................................................s............................................................................................................................s...................................................................s........................................................................s............................................................................ 667 passed, 12 skipped in 41.87 seconds py35 develop-inst-noop: /Users/ned/coverage/trunk py35 installed: apipkg==1.4,-e hg+ssh://hg@bitbucket.org/ned/coveragepy@6664140e34beddd6fee99b729bb9f4545a429c12#egg=coverage,covtestegg1==0.0.0,decorator==4.0.10,eventlet==0.19.0,execnet==1.4.1,gevent==1.1.2,greenlet==0.4.10,mock==2.0.0,pbr==1.10.0,py==1.4.31,PyContracts==1.7.12,pyparsing==2.1.10,pytest==3.0.5.dev0,pytest-warnings==0.2.0,pytest-xdist==1.15.0,six==1.10.0,unittest-mixins==1.1.1 py35 runtests: PYTHONHASHSEED='4113423111' py35 runtests: commands[0] | python setup.py --quiet clean develop no previously-included directories found matching 'tests/eggsrc/dist' no previously-included directories found matching 'tests/eggsrc/*.egg-info' py35 runtests: commands[1] | python igor.py zip_mods install_egg remove_extension py35 runtests: commands[2] | python igor.py test_with_tracer py === CPython 3.5.2 with Python tracer (.tox/py35/bin/python) === gw0 [679] / gw1 [679] / gw2 [679] scheduling tests via LoadScheduling ............s..........................................................................................................................................................s..s...........................................................................................................................................................................................s.................................................................................................sssssssssssssssssss............................................................s................................................................s.............................................................................. 654 passed, 25 skipped in 47.25 seconds py35 runtests: commands[3] | python setup.py --quiet build_ext --inplace py35 runtests: commands[4] | python igor.py test_with_tracer c === CPython 3.5.2 with C tracer (.tox/py35/bin/python) === gw0 [679] / gw1 [679] / gw2 [679] scheduling tests via LoadScheduling ...........s...............................................................................................................................................................................................s......s..........................................................................................................................................................s.................................................................................................s....................................................................................................................................s.................................................................................. 673 passed, 6 skipped in 53.20 seconds _________________________________________________________________________________________ summary __________________________________________________________________________________________ py27: commands succeeded py35: commands succeeded Tox runs the complete test suite twice for each version of Python you have installed. The first run uses the Python implementation of the trace function, the second uses the C implementation. To limit tox to just a few versions of Python, use the ``-e`` switch:: $ tox -e py27,py37 To run just a few tests, you can use `pytest test selectors`_:: $ tox tests/test_misc.py $ tox tests/test_misc.py::SetupPyTest $ tox tests/test_misc.py::SetupPyTest::test_metadata These command run the tests in one file, one class, and just one test, respectively. Of course, run all the tests on every version of Python you have, before submitting a change. .. _pytest test selectors: http://doc.pytest.org/en/latest/usage.html#specifying-tests-selecting-tests Lint, etc --------- I try to keep the coverage.py as clean as possible. I use pylint to alert me to possible problems:: $ make lint pylint coverage setup.py tests python -m tabnanny coverage setup.py tests python igor.py check_eol The source is pylint-clean, even if it's because there are pragmas quieting some warnings. Please try to keep it that way, but don't let pylint warnings keep you from sending patches. I can clean them up. Lines should be kept to a 100-character maximum length. I recommend an `editorconfig.org`_ plugin for your editor of choice. Other style questions are best answered by looking at the existing code. Formatting of docstrings, comments, long lines, and so on, should match the code that already exists. Coverage testing coverage.py ---------------------------- Coverage.py can measure itself, but it's complicated. The process has been packaged up to make it easier:: $ make metacov metahtml Then look at htmlcov/index.html. Note that due to the recursive nature of coverage.py measuring itself, there are some parts of the code that will never appear as covered, even though they are executed. Contributing ------------ When you are ready to contribute a change, any way you can get it to me is probably fine. A pull request on Bitbucket is great, but a simple diff or patch works too. .. _editorconfig.org: http://editorconfig.org .. _Mercurial: https://www.mercurial-scm.org/ .. _tox: https://tox.readthedocs.io/