|
|
@@ -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.
|
Tim Graham