From 3ac70a5907e054c734ca26e435f1ec1215797b08 Mon Sep 17 00:00:00 2001
From: Tim Graham <timograham@gmail.com>
Date: Thu, 11 Oct 2012 06:11:52 -0400
Subject: [PATCH] [1.4.X] Fixed #16817 - Added a guide of code coverage to
 contributing docs.

Thanks Pedro Lima for the draft patch.

Backport of 06f5da3d78 from master
---
 .gitignore                                    |  2 ++
 .hgignore                                     |  2 ++
 .../contributing/writing-code/unit-tests.txt  | 20 +++++++++++++++++++
 docs/topics/testing.txt                       |  2 ++
 tests/.coveragerc                             |  5 +++++
 5 files changed, 31 insertions(+)
 create mode 100644 tests/.coveragerc

diff --git a/.gitignore b/.gitignore
index a34f512130..105829ac74 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,3 +2,5 @@
 *.pot
 *.py[co]
 docs/_build/
+tests/coverage_html/
+tests/.coverage
diff --git a/.hgignore b/.hgignore
index 765a29d091..3dc253a3c1 100644
--- a/.hgignore
+++ b/.hgignore
@@ -4,3 +4,5 @@ syntax:glob
 *.pot
 *.py[co]
 docs/_build/
+tests/coverage_html/
+tests/.coverage
\ No newline at end of file
diff --git a/docs/internals/contributing/writing-code/unit-tests.txt b/docs/internals/contributing/writing-code/unit-tests.txt
index 9f5f9b0bef..3e791c09a1 100644
--- a/docs/internals/contributing/writing-code/unit-tests.txt
+++ b/docs/internals/contributing/writing-code/unit-tests.txt
@@ -165,6 +165,26 @@ associated tests will be skipped.
 .. _gettext: http://www.gnu.org/software/gettext/manual/gettext.html
 .. _selenium: http://pypi.python.org/pypi/selenium
 
+Code coverage
+~~~~~~~~~~~~~
+
+Contributors are encouraged to run coverage on the test suite to identify areas
+that need additional tests. The coverage tool installation and use is described
+in :ref:`testing code coverage<topics-testing-code-coverage>`.
+
+To run coverage on the Django test suite using the standard test settings::
+
+    coverage run ./runtests.py --settings=test_sqlite
+
+After running coverage, generate the html report by running::
+
+    coverage html
+
+When running coverage for the Django tests, the included ``.coveragerc``
+settings file  defines ``coverage_html`` as the output directory for the report
+and also excludes several directories not relevant to the results
+(test code or external code included in Django).
+
 .. _contrib-apps:
 
 Contrib apps
diff --git a/docs/topics/testing.txt b/docs/topics/testing.txt
index 3e9c048820..7ef33afe91 100644
--- a/docs/topics/testing.txt
+++ b/docs/topics/testing.txt
@@ -575,6 +575,8 @@ to a faster hashing algorithm::
 Don't forget to also include in :setting:`PASSWORD_HASHERS` any hashing
 algorithm used in fixtures, if any.
 
+.. _topics-testing-code-coverage:
+
 Integration with coverage.py
 ----------------------------
 
diff --git a/tests/.coveragerc b/tests/.coveragerc
new file mode 100644
index 0000000000..b979e94c58
--- /dev/null
+++ b/tests/.coveragerc
@@ -0,0 +1,5 @@
+[run]
+omit = runtests,test_sqlite,regressiontests*,modeltests*,*/django/contrib/*/tests*,*/django/utils/unittest*,*/django/utils/simplejson*,*/django/utils/importlib.py,*/django/test/_doctest.py,*/django/core/servers/fastcgi.py,*/django/utils/autoreload.py,*/django/utils/dictconfig.py
+
+[html]
+directory = coverage_html