Ділення регресії навпіл

Ділення навпіл – це спосіб знайти регресії в програмному забезпеченні. Після повідомлення про помилку в репозиторії Godot на GitHub, учасник може попросити вас розділити проблему. Поділ навпіл дає змогу учасникам швидше виправляти помилки, оскільки вони можуть заздалегідь знати, який комміт спричинив регресію. Ваші зусилля будуть широко оцінені :)

У посібнику нижче пояснюється, як знайти регресію за допомогою ділення навпіл.

Що таке діління навпіл?

Розробники Godot використовують систему контролю версій Git. У контексті Git розділення навпіл — це процес виконання ручного бінарного пошуку, щоб визначити, коли з’явилася регресія. Хоча зазвичай він використовується для виявлення помилок, його також можна використовувати для пошуку інших типів неочікуваних змін, наприклад регресії продуктивності.

Використання офіційних збірок для прискорення розділення навпіл

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. Зробіть резервну копію свого проекту перед початком процесу розділення навпіл.

Перехід від найстарішої до найновішої збірки зазвичай зменшує ризик неможливості успішного відкриття проекту в редакторі завдяки зворотній сумісності. Також спробуйте скоротити свій проект до найменшого повторюваного прикладу. Чим мінімальнішим є проект, тим більша ймовірність, що ви зможете відкрити його без проблем із сумісністю в новіших версіях двигуна.

Команда Git розділити навпіл

Якщо ви знайшли збірку, яка не виявила помилки в описаному вище процесі тестування, тепер ви можете почати ділити регресію навпіл. Система контролю версій Git пропонує для цього вбудовану команду: git bisect. Це робить процес напівавтоматизованим, оскільки вам потрібно лише створити механізм, запустити його та спробувати відтворити помилку.

Примітка

Перш ніж розділити регресію навпіл, вам потрібно налаштувати середовище збірки для компіляції Godot з вихідного коду. Для цього прочитайте сторінку Compiling для вашої цільової платформи. (Для компіляції Godot з вихідних кодів не потрібні знання програмування C++.)

Зауважте, що компіляція Godot може зайняти деякий час на повільному апаратному забезпеченні (до години для кожного повного відновлення на повільному двоядерному процесорі). Це означає, що повний процес може тривати до кількох годин. Якщо ваше апаратне забезпечення надто повільне, ви можете зупинитися на цьому та повідомити про результати вашого «попереднього розділення навпіл» щодо проблеми GitHub, щоб інший учасник міг продовжити розділення навпіл звідти.

Визначте хеші фіксації

To start bisecting, you must first determine the commit hashes (identifiers) of the "bad" and "good" build. "bad" refers to the build that exhibits the bug, whereas "good" refers to the version that doesn't exhibit the bug.

You can use either a commit hash (like 06acfccf8), the tag of a stable release (like 4.2.1-stable), or a branch like master.

If you're using a pre-release build as the "good" or "bad" build, you can find the commit hash in the Project Manager in the lower-right corner, or in in the Help > About Godot dialog in the Godot editor. The version information will look something like v4.4.beta3.official [06acfccf8], and the commit hash is within the brackets, in this case 06acfccf8. You can click on the version information to copy it, including the commit hash.

Alternately, you can browse the interactive changelog to find commits for all releases, including development builds. The commits will be listed as a range, like commits: a013481b0...06acfccf8, and the second commit is the one you should use for bisecting. You can also browse the Godot Archive, and find the commit hash within the release page linked from the News button.

If you're using a stable release as the "good" or "bad" build, you can use the tag of that release directly, such as 4.2-stable or 4.2.1-stable. A full list of release tags is available on GitHub, and you can also find the actual commit hash that corresponds to a stable release there.

Щоб послатися на останній стан головної гілки, ви можете використовувати master замість хешу фіксації. Зауважте, що на відміну від тегованих випусків або хешів фіксації моментальних знімків, master є ціллю, що постійно змінюється.

Побудуйте двигун

Get Godot's source code using Git. Після цього у вікні терміналу скористайтеся командою 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/, і спробуйте відтворити помилку.

Примітка

Double-check the output file name в bin/, щоб переконатися, що ви дійсно використовуєте двійковий файл, який ви щойно скомпільували. Різні версії Godot виводитимуть двійкові файли з різними іменами.

Якщо збірка досі містить помилку, виконайте таку команду:

git bisect bad

Якщо збірка не виявляє помилку, виконайте таку команду:

git bisect good

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

Коли ви виконаєте достатньо кроків, Git відобразить хеш коміту, де з’явилася регресія. Напишіть цей хеш коміту як коментар до проблеми GitHub, яку ви розділили навпіл. Це допоможе вирішити проблему. Ще раз дякую за внесок у Godot :)

Дивись також

Ви можете прочитати повну документацію щодо git bisect тут.