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.
Par exemple, si vous avez signalé un bogue contre Godot 3.2, vous devez d'abord essayer de reproduire le bogue dans Godot 3.1 (pas une version de correction, voir ci-dessous pour la raison). Si le bogue ne s'y produit pas, essayez de le reproduire dans Godot 3.2 beta 1 (qui se situe à peu près au milieu de toutes les versions de test disponibles). Si vous ne pouvez pas reproduire le bogue avec Godot 3.2 beta 1, essayez des versions bêta et RC plus récentes. Si vous parvenez à reproduire le bogue avec Godot 3.2 beta 1, essayez des versions alpha plus anciennes.
Avertissement
Pour bissecter une régression, n'utilisez pas les versions de patchs telles que Godot 3.1.2. Utilisez plutôt la première version de la version mineure comme Godot 3.1. En effet, les versions de correction sont construites à partir d'une branche stable distincte. Ce type de branche ne suit pas le reste du développement de Godot, qui est fait dans la branche master.
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à.
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 :
3.2-stable
3.1-stable
3.0-stable
Pour faire référence au dernier état de la branche master, vous pouvez utiliser master au lieu d'un hash de commit.
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 :
# <platform> is the platform you're targeting for regression testing,
# like "windows", "x11" or "osx".
$ scons platform=<platform> -j4
Comme la compilation de Godot prend du temps, vous voulez y consacrer autant de threads CPU que possible. C'est ce que fait le paramètre -j. Ici, la commande assigne 4 threads CPU à la compilation de Godot.
Exécutez le binaire situé dans le dossier bin/ et essayez de reproduire le bogue.
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.