From 2c75f2090816730fa8ef57a8c353a1893c504573 Mon Sep 17 00:00:00 2001
From: Blazej Michalik <blazej.michalik@nokia.com>
Date: Wed, 29 Sep 2021 01:32:22 +0200
Subject: [PATCH] Add a section about debugging to development docs

---
 docs/html/development/getting-started.rst | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/docs/html/development/getting-started.rst b/docs/html/development/getting-started.rst
index 7b00c9319d5..19b69275737 100644
--- a/docs/html/development/getting-started.rst
+++ b/docs/html/development/getting-started.rst
@@ -125,6 +125,25 @@ To use linters locally, run:
     readability problems.
 
 
+Running pip under a debugger
+============================
+
+In order to debug pip's behavior, you can run it under a debugger like so:
+
+.. code-block:: console
+
+    $ python -m pdb -m pip --debug ...
+
+
+Replace the ``...`` with arguments you'd like to run pip with. Give PDB the
+``c`` ("continue") command afterwards, to run the process.
+
+The ``--debug`` flag disables pip's exception handler, which would normally
+catch all unhandled exceptions. With this flag, pip will let these exceptions
+propagate outside of its main subroutine, letting them get caught by the
+debugger. This way you'll be able to debug an exception post-mortem via PDB.
+
+
 Building Documentation
 ======================