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.2 的 Bug,則應該先試著在 Godot 3.1 中復現該 Bug (不適用修正版本,原因見後方)。若該 Bug 沒有在 Godot 3.1 中出現,則請試著在 Godot 3.2 Beta 1 中 (也就是大約在所有測試版建置的中間) 嘗試復現。若沒辦法在 Godot 3.2 Beta 1 中復現,則請試試較新版本的 Beta 與 RC 建置。如果能成功在 Godot 3.2 Beta 1 中復現 Bug,則請接著試試較舊版本的 Alpha 建置。

警告

進行 Bisect 迴歸時,請不要使用如 Godot 3.1.2 這樣的修正釋出,請先使用主版本的釋出,如 Godot 3.1.這是因為,修正版本是在獨立的 穩定版分支 上建置的。這種分支並不會跟隨其他 Godot 在 master 分支中所進行的開發。

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 雜湊:

3.2-stable
3.1-stable
3.0-stable

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

使用 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/ 資料夾內的二進位檔,然後嘗試復現 Bug。

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

$ git bisect bad

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

$ git bisect good

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

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

備註

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