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

.. _`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.