Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Regression 的二分查找

二分查找是在软件中查找回归的一种方法。在 GitHub 上的 Godot 仓库中报告了一个错误之后，贡献者可能会要求您去做二分查找。二分查找可以让贡献者更快地修复错误，因为他们可以提前知道是哪个提交导致了回归。您的努力将受到广泛赞赏 :)

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

什么是两分法？

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

使用官方版本加快平分

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

If you have experience with Godot 3.x and can reproduce an issue with Godot 4.0, we recommend trying to reproduce the issue in the latest Godot 3.x version (if the feature exhibiting the bug is present in 3.x). This can be used to check whether the issue is a regression in 4.0 or not.

• If the issue is present in 3.x, then you'll need to check whether the issue occurs in older 3.x versions as well.

• If the issue is not present in 3.x, then you can try older 4.0 alphas and betas to determine when the regression started.

警告

Project files may be incompatible between Godot versions. Make a backup of your project before starting the bisection process.

Going from the oldest to the newest build generally reduces the risk of the project not being able to successfully open in the editor, thanks to backwards compatibility. Try to reduce your project to the smallest repeatable example too. The more minimal the project is, the more likely you'll be able to open it without compatibility issues in newer engine versions.

Git bisect 命令

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

备注

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

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

Determine the commit hashes

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

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

4.1.1-stable
4.1-stable
4.0.3-stable
4.0.2-stable
4.0.1-stable
4.0-stable
3.5.2-stable
3.5.1-stable
3.5-stable
3.4.5-stable
3.4.4-stable
3.4.3-stable
3.4.2-stable
3.4.1-stable
3.4-stable
3.3.4-stable
3.3.3-stable
3.3.2-stable
3.3.1-stable
3.3-stable
3.2-stable
3.1-stable
3.0-stable

You can also use this Bash function to retrieve the Git commit hash of a pre-release build (add it to your $HOME/.bashrc or similar):

gd_snapshot_commit() {
    curl -s https://downloads.tuxfamily.org/godotengine/$1/$2/README.txt \
        | grep 'from commit' \
        | sed 's/^Built from commit \(.*\)\.$/\1/'
}

Example usage:

$ gd_snapshot_commit 4.0 beta4

To refer to the latest state of the master branch, you can use master instead of a commit hash. Note that unlike tagged releases or snapshot commit hashes, master is a perpetually moving target.

Build the engine

使用 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。这假定您已经设置好了构建环境：

$ scons

Run the engine

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

备注

Double-check the output file name in bin/ to make sure you're actually running the binary you've just compiled. Different Godot versions will output binaries with different names.

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

$ git bisect bad

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

$ git bisect good

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

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

备注

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