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

This commit is contained in:
Tim Graham 2015-02-17 14:36:29 -05:00
parent c8074d62f8
commit 0adf766e16
1 changed files with 49 additions and 0 deletions

View File

@ -420,3 +420,52 @@ the ticket database:
.. _`easy pickings`: https://code.djangoproject.com/query?status=!closed&easy=1 .. _`easy pickings`: https://code.djangoproject.com/query?status=!closed&easy=1
.. _`creating an account on Trac`: https://www.djangoproject.com/accounts/register/ .. _`creating an account on Trac`: https://www.djangoproject.com/accounts/register/
.. _password reset page: https://www.djangoproject.com/accounts/password/reset/ .. _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.