Up to date

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

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¶

Avant d'utiliser la commande "bisect" de Git, nous vous recommandons fortement d'essayer de reproduire le bug avec une version officielle plus ancienne (ou plus récente). Cela réduit considérablement le nombre de commits qui doivent potentiellement être construits à partir des sources et testés. Vous pouvez trouver les binaires des versions officielles, ainsi que les alphas, les bêtas et les candidats aux versions ici.

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.

Avertissement

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.

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 Compilation 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¶

Pour commencer à bissecter, vous devez d'abord déterminer les hashs de commit (identifiants) des "mauvaises" et "bonnes" constructions. "bad" se réfère à la version qui présente le bogue, tandis que "good" se réfère à la version qui ne présente pas le bogue. Si vous utilisez une pré-version comme "bonne" ou "mauvaise" version, naviguez dans le miroir de téléchargement, allez dans le dossier qui contient la pré-version que vous avez téléchargée et cherchez le fichier README.txt. Le hachage du commit est écrit à l'intérieur de ce fichier.

Si vous utilisez une version stable comme "bonne" ou "mauvaise" compilation, utilisez l'un des hashs de commit suivants selon la version :

1.1-stable
1-stable
0.3-stable
0.2-stable
0.1-stable
0-stable
5.2-stable
5.1-stable
5-stable
4.5-stable
4.4-stable
4.3-stable
4.2-stable
4.1-stable
4-stable
3.4-stable
3.3-stable
3.2-stable
3.1-stable
3-stable
2-stable
1-stable
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¶

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 :)

Note

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