Régressions en bisectation

La bisection est un moyen de trouver des régressions dans les logiciels. Après avoir signalé un bogue sur le dépôt Godot sur GitHub, un contributeur peut vous demander de bisecter le problème. Le Bisecting permet aux contributeurs de corriger les bugs plus rapidement, car ils peuvent savoir à l'avance quel commit a causé la régression. Votre effort sera largement apprécié :)

Le guide ci-dessous explique comment trouver une régression par bissection.

Qu'est-ce que la bissection ?

Les développeurs de Godot utilisent le système de contrôle de version Git. Dans le contexte de Git, la bissection est le processus consistant à effectuer une recherche binaire pour déterminer quand une régression est apparue. Bien qu'il soit généralement utilisé pour les bogues, il peut également être utilisé pour trouver d'autres types de changements inattendus tels que les régressions de performance.

Utiliser les compilations officielles pour accélérer la bissection

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.

Danger

Les fichiers de projet peuvent être incompatibles entre les versions Godot. Faites une sauvegarde de votre projet avant de commencer le processus de bisection.

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.

La commande git bisect

Si vous avez trouvé une compilation qui ne présentait pas le bogue dans le processus de test ci-dessus, vous pouvez maintenant commencer à couper la régression en deux. Le système de contrôle de version Git offre une commande intégrée pour cela : git bisect. Cela rend le processus semi-automatique, car il suffit de construire le moteur, de l'exécuter et d'essayer de reproduire le bogue.

Note

Avant de bissecter une régression, vous devez mettre en place un environnement de compilation pour compiler Godot à partir de la source. Pour ce faire, lisez la page Compiling pour votre plate-forme cible. (Compiler Godot à partir des sources ne nécessite pas de connaissances en programmation C++.)

Notez que la compilation de Godot peut prendre un certain temps sur du matériel lent (jusqu'à une heure pour chaque recompilation complète sur un CPU dual-core lent). Cela signifie que le processus complet peut prendre jusqu'à plusieurs heures. Si votre matériel est trop lent, vous pouvez vous arrêter là et rapporter les résultats de votre "pré-bisection" sur le numéro de GitHub afin qu'un autre contributeur puisse continuer à bissecter à partir de là.

Determine the commit hashes

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.

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

Obtenez le code source de Godot avec Git. Une fois cela fait, dans la fenêtre du terminal, utilisez cd pour atteindre le dossier du dépôt de Godot et entrez la commande suivante :

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

Compiler Godot. Cela suppose que vous avez mis en place un environnement de compilation :

scons

Run the engine

Exécutez le binaire situé dans le dossier bin/ et essayez de reproduire le bogue.

Note

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.

Si le build présente encore le bug, lancez la commande suivante :

git bisect bad

Si le build ne présente pas le bug, lancez la commande suivante :

git bisect good

Après avoir entré l'une des commandes ci-dessus, Git passera à un commit différent. Vous devez maintenant recompiler Godot, essayer de reproduire le bug, puis entrer git bisect good ou git bisect bad selon le résultat. Vous devrez répéter cela plusieurs fois. Plus la plage de validation est longue, plus il faudra d'étapes. 5 à 10 étapes sont généralement suffisantes pour trouver la plupart des régressions ; Git vous rappellera le nombre d'étapes restantes (dans le pire des cas).

Une fois que vous avez effectué suffisamment d'étapes, Git affichera le hach de commit où la régression est apparue. Écrivez ce hach de commit en commentaire du numéro de GitHub que vous avez découpé. Cela vous aidera à résoudre le problème. Merci encore d'avoir contribué à Godot :)

Voir aussi

Vous pouvez lire la documentation complète sur git bisect ici.