Fixed #23811 -- Added a guide for using git bisect.

1 files changed, 49 insertions, 0 deletions

diff --git a/docs/internals/contributing/triaging-tickets.txt b/docs/internals/contributing/triaging-tickets.txt
index 8c5aed5e3e..8703e6a996 100644
--- a/docs/internals/contributing/triaging-tickets.txt
+++ b/docs/internals/contributing/triaging-tickets.txt
@@ -420,3 +420,52 @@ the ticket database:
 .. _`easy pickings`: https://code.djangoproject.com/query?status=!closed&easy=1
 .. _`creating an account on Trac`: https://www.djangoproject.com/accounts/register/
 .. _password reset page: https://www.djangoproject.com/accounts/password/reset/
+
+Bisecting a regression
+----------------------
+
+.. highlight:: console
+
+A regression is a bug that's present in some newer version of Django but not in
+an older one. An extremely helpful piece of information is the commit that
+introduced the regression. Knowing the commit that caused the change in
+behavior helps identify if the change was intentional or if it was an
+inadvertent side-effect. Here's how you can determine this.
+
+Begin by writing a regression test for Django's test suite for the issue. For
+example, we'll pretend we're debugging a regression in migrations. After you've
+written the test and confirmed that it fails on the latest master, put it in a
+separate file that you can run standalone. For our example, we'll pretend we
+created ``tests/migrations/test_regression.py``, which can be run with::
+
+    $ ./runtests.py migrations.test_regression
+
+Next, we mark the current point in history as being "bad" since the test fails::
+
+    $ git bisect bad
+    You need to start by "git bisect start"
+    Do you want me to do it for you [Y/n]? y
+
+Now, we need to find a point in git history before the regression was
+introduced (i.e. a point where the test passes). Use something like
+``git co HEAD~100`` to checkout an earlier revision (100 commits earlier, in
+this case). Check if the test fails. If so, mark that point as "bad"
+(``git bisect bad``), then checkout an earlier revision and recheck. Once you
+find a revision where your test passes, mark it as "good"::
+
+    $ git bisect good
+    Bisecting: X revisions left to test after this (roughly Y steps)
+    ...
+
+Now we're ready for the fun part: using ``git bisect run`` to automate the rest
+of the process::
+
+    $ git bisect run python runtests.py migrations.test_regression
+
+You should see ``git bisect`` use a binary search to automatically checkout
+revisions between the good and bad commits until it finds the first "bad"
+commit where the test fails.
+
+Now, report your results on the Trac ticket, and please include the regression
+test as an attachment. When someone writes a fix for the bug, they'll already
+have your test as a starting point.