From c60e77c3c1d4b06caf01967ebcc8139052a6fcdc Mon Sep 17 00:00:00 2001
From: Hynek Schlawack <hs@ox.cx>
Date: Thu, 1 Sep 2022 18:57:13 +0200
Subject: [PATCH] Add missing local test dep and document it

---
 CONTRIBUTING.rst                    | 29 +++++++++++++++++++++--------
 setup.py                            |  1 +
 src/towncrier/newsfragments/415.doc |  1 +
 3 files changed, 23 insertions(+), 8 deletions(-)
 create mode 100644 src/towncrier/newsfragments/415.doc

diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index 7ef566a8..cf9518b4 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -89,12 +89,27 @@ Running the test suite
 ----------------------
 
 We use the `twisted.trial`_ module and `tox`_ to run tests against all supported
-Python versions and operating systems. All test dependencies, other than tox, are installed
-automatically.
+Python versions and operating systems.
 
 The following list contains some ways how to run the test suite:
 
-* To run all tests, use::
+* To install Towncrier into a virtualenv along with the dependencies necessary
+  to run the tests and build the documentation::
+
+    $ pip install -e .[dev]
+
+* To run the tests, use ``like`` like so::
+
+    $ trial towncrier
+
+* To investigate and debug errors, use the ``trial`` command like this::
+
+    $ trial -b towncrier
+
+  This will invoke a PDB session. If you press ``c`` it will continue running
+  the test suite until it runs into an error.
+
+* To run all tests against all supported versions, install tox and use::
 
     $ tox
 
@@ -120,12 +135,10 @@ The following list contains some ways how to run the test suite:
     $ pip install pre-commit
     $ pre-commit install
 
-* To investigate and debug errors, use the ``trial`` command like this::
-
-    $ trial -b towncrier
-
-  This command creates a virtual environment and invokes a PDB session.
 
+**Please note**: If the test suite works in tox, but doesn't by calling
+``trial``, it could be that you've got GPG-signing active for git commits which
+fails with our dummy test commits.
 
 .. ### Links
 
diff --git a/setup.py b/setup.py
index 8747d26a..0f7fef17 100644
--- a/setup.py
+++ b/setup.py
@@ -49,6 +49,7 @@
         "dev": [
             "packaging",
             "sphinx >= 5",
+            "twisted",
         ],
     },
     package_dir={"": "src"},
diff --git a/src/towncrier/newsfragments/415.doc b/src/towncrier/newsfragments/415.doc
new file mode 100644
index 00000000..af35a5dd
--- /dev/null
+++ b/src/towncrier/newsfragments/415.doc
@@ -0,0 +1 @@
+Improved contribution documentation.