Regression 的二分查找

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 :)

以下指南说明了如何通过二等分查找回归.

什么是两分法?

Godot开发人员使用 Git 版本控制系统. 在Git的上下文中, 二等分是执行手动 二进制搜索 的过程, 以确定什么时候出现了回归. 尽管它通常用于错误, 但也可以用于查找其他种类的意外更改, 例如性能下降.

使用官方版本加快平分

在使用Git的 bisect 命令之前, 我们强烈建议尝试使用较旧的(或较新的)正式版本重现该错误. 这大大减少了可能需要从源构建和测试的提交范围. 您可以在 此处 找到官方发行版的二进制文件以及alpha,beta和发行候选文件.

例如,如果您报告了 Godot 3.2 中的错误,则应首先尝试在 Godot 3.1 中重现该错误(不是补丁版本,原因见下文)。如果那里没有发生该错误,请尝试在 Godot 3.2 beta 1 中重现该错误(大约在所有可用测试版本的中间)。如果您无法使用 Godot 3.2 beta 1 重现该错误,请尝试使用较新的 beta 和 RC 版本。如果您用 Godot 3.2 beta 1 重现了该错误,那么就再尝试使用较早的 alpha 版本。

警告

对于二等分回归, 请勿使用修补程序版本, 例如Godot 3.1.2. 而是使用次要版本的第一个发行版, 例如Godot 3.1. 这是因为修补程序版本是从单独的* stable分支*构建的. 这种分支没有遵循Godot的其余开发, 而是在" master"分支中完成的.

Git bisect 命令

如果您发现在上述测试过程中未显示该错误的构建,则可以立即将回归二等分。Git 版本控制系统为此提供了一个内置命令:git bisect。这使过程成为半自动化的过程,因为您只需要构建引擎,运行它并尝试重现该错误即可。

备注

在平分回归之前, 您需要设置一个构建环境以从源代码编译Godot. 为此, 请阅读目标平台的 Compiling 页面. (从源代码编译Godot不需要C ++编程知识.)

请注意, 编译 Godot 可能需要在缓慢的硬件上一段时间(在缓慢的双核 CPU 上, 每次完全重建需要一个小时). 这意味着整个过程最多可能需要几个小时. 如果您的硬件太慢, 您可能希望停止并报告 GitHub 问题的 "预分节" 结果, 以便其他参与者可以继续从该部分开始参与.

要开始划分, 你必须首先确定 "坏" 和 "好" 的版本提交散列值(标识符)."坏" 指的是表现出错误的版本, 而 "好" 指的是没有表现出错误的版本. 如果你使用一个预发布版本作为 "好" 或 "坏" 下载镜像, 进入包含你下载的预发布版本的文件夹, 寻找 README.txt 文件. 提交的哈希值就写在该文件中.

如果您使用稳定版本作为“好”或“坏”版本,请根据版本使用以下提交哈希之一:

3.2-stable
3.1-stable
3.0-stable

要引用 master 分支的最新状态,可以使用 master 代替提交哈希。

使用 Git 获取 Godot 的源代码。完成后,在终端窗口中,使用 cd 进入 Godot 仓库文件夹并输入以下命令:

# <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>

编译 Godot。这假定您已经设置好了构建环境:

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

由于构建 Godot 需要花上一定时间,因此您会希望为任务分配尽可能多的 CPU 线程。这就是 -j 参数的作用。在此,该命令会分配 4 个 CPU 线程来编译 Godot。

运行位于 bin/ 文件夹中的二进制文件并尝试重现该错误。

如果构建仍然显示错误,请运行以下命令:

$ git bisect bad

如果构建没有显示错误,请运行以下命令:

$ git bisect good

输入上述命令之一后,Git 将切换到其他提交. 现在, 您应该再次构建 Godot, 尝试重现 Bug, 然后根据结果输入"git 一部分好 "或"git 一次坏". 你必须重复几次. 提交范围越长, 所需的步骤就越多.5 到 10 个步骤通常足以查找大多数回归;Git 将提醒您剩余步骤数(在最坏的情况下).

完成足够的步骤后,Git将在出现回归的位置显示提交哈希. 将此提交哈希值写成对一分为二的GitHub问题的评论. 这将有助于解决问题. 再次感谢您对Godot的贡献:)

备注

您可以在 git bisect 上阅读完整文档, 这里 .