Bisecting regressions

Bisecting is a way to find regressions in software. After reporting a bug on the Godot repository on GitHub, you may be asked by a contributor to bisect the issue. Bisecting makes it possible for contributors to fix bugs faster, as they can know in advance which commit caused the regression. Your effort will be widely appreciated :)

The guide below explains how to find a regression by bisecting.

Что такое рассечение?

Godot developers use the Git version control system. In the context of Git, bisecting is the process of performing a manual binary search to determine when a regression appeared. While it's typically used for bugs, it can also be used to find other kinds of unexpected changes such as performance regressions.

Using official builds to speed up bisecting

Before using Git's bisect command, we strongly recommend trying to reproduce the bug with an older (or newer) official release. This greatly reduces the range of commits that potentially need to be built from source and tested. You can find binaries of official releases, as well as alphas, betas, and release candidates here.

Например, если вы сообщили об ошибке в Godot 3.2, сначала попробуйте воспроизвести ошибку в Godot 3.1 (не патч-релиз, о причине см. ниже). Если ошибка не проявилась там, попробуйте воспроизвести её в Godot 3.2 beta 1 (это примерно середина всех доступных тестовых сборок). Если вы не можете воспроизвести ошибку в Godot 3.2 beta 1, попробуйте более новые бета-версии и RC-сборки. Если вам удалось воспроизвести ошибку с Godot 3.2 beta 1, попробуйте более старые альфа-сборки.

Предупреждение

For bisecting regressions, don't use patch releases such as Godot 3.1.2. Instead, use the minor version's first release like Godot 3.1. This is because patch releases are built from a separate stable branch. This kind of branch doesn't follow the rest of Godot's development, which is done in the master branch.

The Git bisect command

If you've found a build that didn't exhibit the bug in the above testing process, you can now start bisecting the regression. The Git version control system offers a built-in command for this: git bisect. This makes the process semi-automated as you only have to build the engine, run it and try to reproduce the bug.

Примечание

Before bisecting a regression, you need to set up a build environment to compile Godot from source. To do so, read the Compiling page for your target platform. (Compiling Godot from source doesn't require C++ programming knowledge.)

Note that compiling Godot can take a while on slow hardware (up an hour for each full rebuild on a slow dual-core CPU). This means the full process can take up to several hours. If your hardware is too slow, you may want to stop there and report the results of your "pre-bisecting" on the GitHub issue so another contributor can continue bisecting from there.

Чтобы начать биссектрису, необходимо сначала определить хэши (идентификаторы) коммитов "плохой" и "хорошей" сборки. "Плохой" называется сборка, в которой обнаружена ошибка, а "хорошей" - версия, в которой ошибка не обнаружена. Если вы используете предварительную сборку в качестве "хорошей" или "плохой" сборки, просмотрите зеркало загрузки ` <https://downloads.tuxfamily.org/godotengine/>` __, перейдите в папку, содержащую предварительную сборку, которую вы загрузили, и найдите файл README.txt. Хэш коммита записан внутри этого файла.

If you're using a stable release as the "good" or "bad" build, use one of the following commit hashes depending on the version:

3.2-stable
3.1-stable
3.0-stable

To refer to the latest state of the master branch, you can use master instead of a commit hash.

Get Godot's source code using Git. Once this is done, in the terminal window, use cd to reach the Godot repository folder and enter the following command:

# <good commit hash> is hash of the build that works as expected.
# <bad commit hash> is hash of the build exhibiting the bug.
$ git bisect start
$ git bisect good <good commit hash>
$ git bisect bad <bad commit hash>

Compile Godot. This assumes you've set up a build environment:

# <platform> is the platform you're targeting for regression testing,
# like "windows", "x11" or "osx".
$ scons platform=<platform> -j4

Since building Godot takes a while, you want to dedicate as many CPU threads as possible to the task. This is what the -j parameter does. Here, the command assigns 4 CPU threads to compiling Godot.

Run the binary located in the bin/ folder and try to reproduce the bug.

If the build still exhibits the bug, run the following command:

$ git bisect bad

If the build does not exhibit the bug, run the following command:

$ git bisect good

После ввода одной из команд, указанных выше, Git переключится на другой коммит. Теперь вы должны снова собрать Godot, попытаться воспроизвести ошибку, затем ввести git bisect good или git bisect bad в зависимости от результата. Вам придется повторить это несколько раз. Чем больше диапазон фиксации, тем больше шагов потребуется. Обычно 5-10 шагов достаточно, чтобы найти большинство регрессий; Git напомнит вам о количестве оставшихся шагов (в худшем случае).

Once you've completed enough steps, Git will display the commit hash where the regression appeared. Write this commit hash as a comment to the GitHub issue you've bisected. This will help in solving the issue. Thanks again for contributing to Godot :)

Примечание

You can read the full documentation on git bisect here.