From 3ad682e2f5cded56a4ddfce0078241f8dbdb4e6d Mon Sep 17 00:00:00 2001
From: Randy Barlow <randy@electronsweatshop.com>
Date: Jan 21 2019 14:04:15 +0000
Subject: Document how to use diff-cover.


This patch documents how to use diff-cover to enforce patches
having 100% coverage on the code they edit.

Signed-off-by: Randy Barlow <randy@electronsweatshop.com>

---

diff --git a/docs/dev-guide/writing-tests.rst b/docs/dev-guide/writing-tests.rst
index a7aac15..ed1c682 100644
--- a/docs/dev-guide/writing-tests.rst
+++ b/docs/dev-guide/writing-tests.rst
@@ -81,10 +81,11 @@ ensure the project's documentation builds without errors or warnings.
 Here's an example ``tox.ini`` file that runs a project's unit tests in Python
 2.7, Python 3.4, Python 3.5, and Python 3.6. It also runs `flake8`_ on the
 entire codebase and builds the documentation with the "warnings treated as
-errors" Sphinx flag enabled::
+errors" Sphinx flag enabled. Finally, it enforces 100% coverage on lines edited
+by new patches using `diff-cover`_::
 
     [tox]
-    envlist = py27,py34,py35,py36,lint,docs
+    envlist = py27,py34,py35,py36,lint,diff-cover,docs
     # If the user is missing an interpreter, don't fail
     skip_missing_interpreters = True
 
@@ -100,6 +101,12 @@ errors" Sphinx flag enabled::
     # a home directory when looking for configuration files.
     passenv = HOME
 
+    [testenv:diff-cover]
+    deps =
+        diff-cover
+    commands =
+        diff-cover coverage.xml --compare-branch=origin/master --fail-under=100
+
     [testenv:docs]
     changedir = docs
     deps =
@@ -130,7 +137,8 @@ Coverage
 
 `coverage`_ is a good way to collect test coverage statistics. `pytest`_ has a
 `pytest-cov`_ plugin that integrates with `coverage`_ and `nose-cov`_ provides
-integration for the `nose`_ test runner.
+integration for the `nose`_ test runner. `diff-cover`_ can be used to ensure
+that all lines edited in a patch have coverage.
 
 It's possible (and recommended) to have the test suite fail if the coverage
 percentage goes down. This example ``.coveragerc``::
@@ -177,6 +185,7 @@ request and should increase the minimum test coverage until it is 100%.
     to leave a comment explaining why it's excluded!
 
 .. _coverage: https://pypi.python.org/pypi/coverage/
+.. _diff-cover: https://pypi.org/project/diff-cover/
 .. _exclusion: https://coverage.readthedocs.io/en/coverage-4.3.4/excluding.html
 .. _flake8: https://pypi.python.org/pypi/flake8
 .. _pytest: http://docs.pytest.org/en/latest/contents.html