A Contributing page in the docs. #171

4 files changed, 175 insertions, 0 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index 7ff2da98..5141b172 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -46,6 +46,9 @@ Version 3.5.4b1
 - The pydoc tool can now show docmentation for the class `coverage.coverage`.
   Closes `issue 206`_.
 
+- Added a page to the docs about contributing to coverage.py, closing
+  `issue 171`_.
+
 - Other minor bugs fixed: `issue 153`_.
 
 .. _issue 89: https://bitbucket.org/ned/coveragepy/issue/89/on-windows-all-packages-are-reported-in
@@ -53,6 +56,7 @@ Version 3.5.4b1
 .. _issue 143: https://bitbucket.org/ned/coveragepy/issue/143/omit-doesnt-seem-to-work-in-coverage
 .. _issue 153: https://bitbucket.org/ned/coveragepy/issue/153/non-existent-filename-triggers
 .. _issue 163: https://bitbucket.org/ned/coveragepy/issue/163/problem-with-include-and-omit-filename
+.. _issue 171: https://bitbucket.org/ned/coveragepy/issue/171/how-to-contribute-and-run-tests
 .. _issue 193: https://bitbucket.org/ned/coveragepy/issue/193/unicodedecodeerror-on-htmlpy
 .. _issue 201: https://bitbucket.org/ned/coveragepy/issue/201/coverage-using-django-14-with-pydb-on
 .. _issue 203: https://bitbucket.org/ned/coveragepy/issue/203/duplicate-filenames-reported-when-filename
diff --git a/doc/contributing.rst b/doc/contributing.rst
new file mode 100644
index 00000000..273d06d0
--- /dev/null
+++ b/doc/contributing.rst
@@ -0,0 +1,166 @@
+.. _contributing:
+
+===========================
+Contributing to coverage.py
+===========================
+
+:history: 20121112T154100, brand new docs.
+
+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.
+
+#.  Clone the repo:
+
+    .. code-block:: console
+
+        $ hg clone https://bitbucket.org/ned/coveragepy
+
+#.  Install the requirements:
+
+    .. code-block:: console
+
+        $ pip install -r requirements.txt
+
+#.  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`_:
+
+    .. code-block:: console
+
+        $ tox
+        GLOB sdist-make: /home/ned/coverage/setup.py
+        py25 sdist-reinst: /home/ned/coverage/tox/dist/coverage-3.5.4b1.zip
+        py25 runtests: commands[0]
+        py25 runtests: commands[1]
+        py25 runtests: commands[2]
+        py25 runtests: commands[3]
+        py25 runtests: commands[4]
+        === Python 2.5.5 with Python tracer (/home/ned/coverage/tox/py25/bin/python) ===
+        ...........................................................................................(etc)
+        ----------------------------------------------------------------------
+        Ran 360 tests in 10.836s
+
+        OK
+        py25 runtests: commands[5]
+        py25 runtests: commands[6]
+        === Python 2.5.5 with C tracer (/home/ned/coverage/tox/py25/bin/python) ===
+        ...........................................................................................(etc)
+        ----------------------------------------------------------------------
+        Ran 360 tests in 10.044s
+
+        OK
+        py26 sdist-reinst: /home/ned/coverage/trunk/.tox/dist/coverage-3.5.4b1.zip
+        py26 runtests: commands[0]
+        py26 runtests: commands[1]
+        py26 runtests: commands[2]
+        py26 runtests: commands[3]
+        py26 runtests: commands[4]
+        === CPython 2.6.6 with Python tracer (/home/ned/coverage/tox/py26/bin/python) ===
+        ...........................................................................................(etc)
+        ----------------------------------------------------------------------
+        Ran 364 tests in 12.572s
+
+        OK
+        py26 runtests: commands[5]
+        py26 runtests: commands[6]
+        === CPython 2.6.6 with C tracer (/home/ned/coverage/tox/py26/bin/python) ===
+        ...........................................................................................(etc)
+        ----------------------------------------------------------------------
+        Ran 364 tests in 11.458s
+
+        OK
+        (and so on...)
+
+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:
+
+    .. code-block:: console
+
+        $ tox -e py27,py33
+
+To run just a few tests, you can use nose test selector syntax:
+
+    .. code-block:: console
+
+        $ tox test.test_misc:SetupPyTest.test_metadata
+
+This looks in `test/test_misc.py` to find the `SetupPyTest` class, and runs the
+`test_metadata` test method.
+
+Of course, run all the tests on every version of Python you have, before
+submitting a change.
+
+
+Lint, etc
+---------
+
+I try to keep the coverage.py as clean as possible.  I use pylint to alert me
+to possible problems:
+
+    .. code-block:: console
+
+        $ make lint
+        pylint --rcfile=.pylintrc coverage setup.py test
+        ************* Module coverage.collector
+        F0401:  7,4: Unable to import 'coverage.tracer'
+        E0611:  7,4: No name 'tracer' in module 'coverage'
+        ************* Module coverage.parser
+        W0631:532,32:ByteParser._split_into_chunks: Using possibly undefined loop variable 'bc'
+        W0631:579,40:ByteParser._arcs: Using possibly undefined loop variable 'ch'
+        make: [lint] Error 7 (ignored)
+        python -m tabnanny coverage setup.py test
+        python igor.py check_eol
+
+As you can see, a few warnings persist, don't worry about them.  But clean up
+any ones you may be responsible for.
+
+
+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 is great too.
+
+
+.. _Mercurial: http://mercurial.selenic.com/
+.. _tox: http://tox.testrun.org/
diff --git a/doc/index.rst b/doc/index.rst
index 9e8ed502..6fc7a057 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -154,6 +154,7 @@ More information
     branch
     subprocess
     api
+    contributing
     faq
     changes
 
diff --git a/requirements.txt b/requirements.txt
new file mode 100644
index 00000000..bdeb80c9
--- /dev/null
+++ b/requirements.txt
@@ -0,0 +1,4 @@
+nose
+mock
+tox
+pylint