Skip to content

Commit f57a73e

Browse files
seljaksnoatamir
authored andcommitted
DOC: Added section on git bisect to pandas maintenance (pandas-dev#48968)
* DOC: add section on bisect GH35685 * DOC: added whatsnew entry GH35685 * DOC: modified bisect section GH35685 * DOC: modified whatsnew entry on bisect * Revert "DOC: modified whatsnew entry on bisect" This reverts commit 6364688. * Revert "DOC: added whatsnew entry GH35685" This reverts commit 046badb.
1 parent 1c40fb2 commit f57a73e

File tree

1 file changed

+43
-0
lines changed

1 file changed

+43
-0
lines changed

doc/source/development/maintaining.rst

+43
Original file line numberDiff line numberDiff line change
@@ -121,6 +121,49 @@ Here's a typical workflow for triaging a newly opened issue.
121121
unless it's know that this issue should be addressed in a specific release (say
122122
because it's a large regression).
123123

124+
.. _maintaining.regressions:
125+
126+
Investigating regressions
127+
-------------------------
128+
129+
Regressions are bugs that unintentionally break previously working code. The common way
130+
to investigate regressions is by using
131+
`git bisect <https://git-scm.com/docs/git-bisect>`_,
132+
which finds the first commit that introduced the bug.
133+
134+
For example: a user reports that ``pd.Series([1, 1]).sum()`` returns ``3``
135+
in pandas version ``1.5.0`` while in version ``1.4.0`` it returned ``2``. To begin,
136+
create a file ``t.py`` in your pandas directory, which contains
137+
138+
.. code-block:: python
139+
140+
import pandas as pd
141+
assert pd.Series([1, 1]).sum() == 2
142+
143+
and then run::
144+
145+
git bisect start
146+
git bisect good v1.4.0
147+
git bisect bad v1.5.0
148+
git bisect run bash -c "python setup.py build_ext -j 4; python t.py"
149+
150+
This finds the first commit that changed the behavior. The C extensions have to be
151+
rebuilt at every step, so the search can take a while.
152+
153+
Exit bisect and rebuild the current version::
154+
155+
git bisect reset
156+
python setup.py build_ext -j 4
157+
158+
Report your findings under the corresponding issue and ping the commit author to get
159+
their input.
160+
161+
.. note::
162+
In the ``bisect run`` command above, commits are considered good if ``t.py`` exits
163+
with ``0`` and bad otherwise. When raising an exception is the desired behavior,
164+
wrap the code in an appropriate ``try/except`` statement. See :issue:`35685` for
165+
more examples.
166+
124167
.. _maintaining.closing:
125168

126169
Closing issues

0 commit comments

Comments
 (0)