Regressions-Bugs durch Bisecting finden

Bisecting (Halbierung) ist ein Weg, um Regressions-Bugs in Software zu finden. Nachdem Sie einen Bug im Godot-Repository in GitHub gemeldet haben, werden Sie möglicherweise von einem Mitwirkenden gebeten, Bisecting auf das Problem anzuwenden. Durch Bisecting können Mitwirkende Bugs schneller beheben, da sie im Voraus wissen, welches Commit den Regression-Bug verursacht hat. Ihre Bemühungen werden sehr geschätzt werden :)

In der folgenden Anleitung wird erläutert, wie Sie einen Regressions-Bug durch Bisecting finden.

Was ist Bisecting?

Godot-Entwickler verwenden das Versionskontrollsystem Git. Im Kontext von Git ist Bisecting der Prozess der Durchführung für eine manuelle binäre Suche , um festzustellen, wann ein Regressions-Bug aufgetreten ist. Während es normalerweise für Bugs verwendet wird, können damit auch andere Arten unerwarteter Änderungen gefunden werden, z.B. Performance-Regressions-Bugs.

Verwenden Sie offizielle Builds, um den Bisecting-Prozess zu beschleunigen

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.

Gefahr

Projektdateien können zwischen Godot-Versionen inkompatibel sein. Erstellen Sie eine Sicherungskopie Ihres Projekts, bevor Sie mit dem Bisecting-Prozess beginnen.

Wenn Sie vom ältesten zum neuesten Build wechseln, verringert sich dank der Abwärtskompatibilität in der Regel das Risiko, dass sich das Projekt nicht erfolgreich im Editor öffnen lässt. Versuchen Sie auch, Ihr Projekt auf das kleinste wiederholbare Beispiel zu reduzieren. Je kleiner das Projekt ist, desto wahrscheinlicher ist es, dass Sie es ohne Kompatibilitätsprobleme in neueren Engine-Versionen öffnen können.

Der Git-Befehl bisect

Wenn Sie einen Build gefunden haben, der den Bug im obigen Testprozess nicht aufwies, können Sie nun damit beginnen, den Regressions-Bug zu bisektieren. Das Git-Versionskontrollsystem bietet dafür einen eingebauten Befehl: git bisect. Das macht den Prozess halbautomatisch, da Sie nur die Engine bauen müssen, sie laufen lassen und versuchen, den Bug zu reproduzieren.

Bemerkung

Bevor Sie einen Regressions-Bug bisektieren, müssen Sie eine Build-Umgebung einrichten, um Godot aus dem Quellcode zu kompilieren. Lesen Sie dazu die Seite Kompilieren für Ihre Target-Plattform. (Zum Kompilieren von Godot aus dem Quellcode sind keine C++-Programmierkenntnisse erforderlich.)

Beachten Sie, dass das Kompilieren von Godot auf langsamer Hardware eine Weile dauern kann (bis zu einer Stunde für jeden vollständigen Rebuild auf einer langsamen Dual-Core-CPU). Das bedeutet, dass der gesamte Prozess bis zu mehrere Stunden dauern kann. Wenn Ihre Hardware zu langsam ist, möchten Sie vielleicht dort aufhören und die Ergebnisse Ihrer "Vor-Bisektierung" in der GitHub-Issue berichten, so dass ein anderer Mitwirkender von dort aus das Bisecting fortsetzen kann.

Ermitteln der 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.

Um auf den letzten Stand des Master-Branchs zu verweisen, können Sie master anstelle eines Commit-Hashes verwenden. Beachten Sie, dass sich master im Gegensatz zu getaggten Releases oder Snapshot-Commit-Hashes ständig verändern wird.

Bauen der Engine

Holen Sie sich Godots Quellcode mit Git. Sobald dies geschehen ist, verwenden Sie im Terminalfenster cd, um den Godot-Repository-Ordner zu erreichen, und geben Sie den folgenden Befehl ein:

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

Kompilieren Sie Godot. Dies setzt voraus, dass Sie eine Build-Umgebung eingerichtet haben:

scons

Starten der Engine

Führen Sie die Binärdatei im Ordner bin / aus und versuchen Sie, den Bug zu reproduzieren.

Bemerkung

Überprüfen Sie den Namen der Ausgabedatei in bin/, um sicherzustellen, dass Sie tatsächlich die Binärdatei ausführen, die Sie gerade kompiliert haben. Verschiedene Godot-Versionen werden Binärdateien mit unterschiedlichen Namen erzeugen.

Wenn der Build immer noch den Bug aufweist, führen Sie den folgenden Befehl aus:

git bisect bad

Wenn der Build den Bug nicht aufweist, führen Sie den folgenden Befehl aus:

git bisect good

Nachdem Sie einen der obigen Befehle eingegeben haben, wird Git zu einem anderen Commit wechseln. Sie sollten nun Godot erneut kompilieren, versuchen, den Bug zu reproduzieren, und dann je nach Ergebnis git bisect good oder git bisect bad eingeben. Dies müssen Sie mehrere Male wiederholen. Je länger der Commit-Bereich ist, desto mehr Schritte werden benötigt. 5 bis 10 Schritte reichen normalerweise aus, um die meisten Regressions-Bugs zu finden; Git wird Sie an die Anzahl der verbleibenden Schritte erinnern (im worst-case Fall).

Wenn Sie genügend Schritte durchgeführt haben, zeigt Git den Commit-Hash an, wo der Regression-Bug aufgetreten ist. Schreiben Sie diesen Commit-Hash als Kommentar zu der GitHub-Issue, die Sie bisektiert haben. Dies wird bei der Lösung des Problems helfen. Nochmals vielen Dank für Ihren Beitrag zu Godot :)

Siehe auch

Sie können die vollständige Dokumentation über git bisect hier lesen.