Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

Bisect 迴歸

Bisect 是一種在軟體中找出迴歸 (Regression) 的方法。當在 GitHub 上的 Godot 儲存庫 上回報 Bug 後，可能會有貢獻者要求你 Bisect 該問題。通過 Bisect 便能讓貢獻者進一步瞭解是哪個 Commit 造成該問題的，進而更快修正 Bug。大家會很感謝你的努力 :)

本指南解釋如何通過 Bisect 來找出迴歸。

什麼是 Bisect？

Godot 開發人員使用 Git 版本控制系統。在 Git 的脈路下，Bisect 是一個手動進行 二分搜尋 來判斷迴歸是何時產生的一個過程。雖然通常 Bisect 是用來找出 Bug 的，但也可以用來找出如效能迴歸等其他未預期的改動。

使用官方建置來加快 Bisect

在使用 Git 的 bisect 指令前，我們強烈建議試著通過較舊版本 (或較新) 的官方釋出版本來嘗試重現 Bug。這樣一來可以大幅降低可能需要用來從原始碼建置並進行測試的 Commit 範圍。可以在 此處 找到官方釋出版本、Alpha 版、RC 版的二進位檔。

如果您有使用 Godot 3.x 的經驗並且可以使用 Godot 4.0 重現問題，我們建議您嘗試在最新的 Godot 3.x 版本中重現問題（如果 3.x 中存在顯示錯誤的功能）。這可以用來檢查問題是否為 4.0 中的迴歸。

  • 如果 3.x 中**存在**問題，那麼您需要檢查較早的 3.x 版本中是否也出現該問題。

  • 如果問題在 3.x 中**不存在**，那麼您可以嘗試較舊的 4.0 alpha 和 beta 來確定回歸何時開始。

警告

Godot 版本之間的專案檔案可能不相容。 開始二分程式之前，先備份您的專案。

由於向後相容性，從最舊的版本到最新的版本通常會降低專案無法在編輯器中成功開啟的風險。也嘗試將您的專案縮減為最小的可重複範例。專案越小，您就越有可能在較新的引擎版本中開啟它而不會出現相容性問題。

Git 的 Bisect 指令

如果在上述測試過程中找到了沒有出現該 Bug 的建置，則可以開始 Bisect 迴歸。Git 版本控制系統提供了一個內建指令來進行 Bisect 迴歸： git bisect 。有了這個指令便可將此一過程半自動化，只需要建置引擎並嘗試重現該 Bug 即可。

備註

在 Bisect 迴歸前，需要先建置用於從原始碼編譯 Godot 的建置環境。要設定建置環境，請參考與建置目標平台對應的 編譯 頁面。(從原始碼編譯 Godot 並不需要 C++ 程式設計知識。)

請主義，在較慢的硬體上編譯 Godot 可能會花費一些時間 (在較慢的雙核 CPU 上，每個建置可能會花費高達一個小時)。這表示，整個過程可能會耗費數個小時。如果你使用較慢的硬體，則你可以停在這裡，並在 GitHub Issue 上回報你在「Bisect 前」的結果來讓其他貢獻者能從此處繼續進行 Bisect。

確定提交雜湊

要開始 Bisect，首先必須先判斷「壞的」與「好的」建置的 Commit 雜湊 (識別項)。「壞的」代表會出現 Bug 的建置，而「好的」則代表不會出現該 Bug 的版本。如果使用預釋出的建置來當作「好的」或「壞的」建置，則請瀏覽 下載鏡像 頁面，前往包含你下載的預釋出版本的資料夾內，然後找到 README.txt 檔案。該檔案內有寫上 Commit 雜湊。

如果你使用穩定版來作為「好的」或「壞的」建置，則請依據版本來使用下列其一 Commit 雜湊：

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

您也可以使用此 Bash 函式來檢索預發布版本的 Git 提交雜湊（將其新增至您的 $HOME/.bashrc 或類似檔案）：

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

範例：

$ gd_snapshot_commit 4.0 beta4

如果要參照 master 分支的最新狀態，則可以使用 master 來代替 Commit 雜湊。

建置 Mono 執行環境

使用 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

執行遊戲

執行 bin/ 資料夾內的二進位檔，然後嘗試復現 Bug。

備註

仔細檢查 ``bin/` 中的輸出檔案名稱 <doc_introduction_to_the_buildsystem_resulting_binary>` 以確保您實際上正在執行剛剛編譯的二進位檔案。不同的 Godot 版本將輸出具有不同名稱的二進位。

若該建置中 依然 會遇到 Bug，則請執行下列指令：

$ git bisect bad

如果該建置 沒有 出現 Bug，請執行下列指令：

$ git bisect good

輸入上述其中一個指令後，Git 會切換到不同的 Commit 上。接著應再次建置 Godot、嘗試復現 Bug、然後依據結果輸入 git bisect good 或 git bisect bad 。這個過程會需要重複多次。Commit 的範圍越大、就需要越多步驟。通常需要 5 到 10 個步驟才足夠找出大多數的迴歸；Git 會提示還剩下幾個步驟 (最糟情況下的剩餘步驟)。

完成了足夠的步驟後，Git 會顯示該迴歸出現的 Commit 雜湊。請將該 Commit 雜湊寫在所 Bisect 的 GitHub Issue 留言上。這樣有助於解決該問題。再次感謝你參與貢獻 Godot :)

備註

有關 git bisect 的完整說明文件可以參考 此處 。