Up to date

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

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¶

Bevor Sie den bisect-Befehl von Git verwenden, empfehlen wir dringend, den Bug mit einer älteren (oder neueren) offiziellen Version zu reproduzieren. Das reduziert die Bandbreite der Commits, die potentiell aus dem Quellcode gebaut und getestet werden müssen, erheblich. Sie können Binärdateien von offiziellen Versionen, sowie Alphas, Betas und Release Candidates hier finden.

Wenn Sie Erfahrung mit Godot 3.x haben und ein Problem mit Godot 4.0 reproduzieren können, empfehlen wir, das Problem in der neuesten Godot 3.x-Version zu reproduzieren (wenn das Feature, das den Bug aufweist, in 3.x vorhanden ist). Auf diese Weise lässt sich überprüfen, ob es sich bei dem Problem um einen Regressions-Bug in 4.0 handelt oder nicht.

Wenn das Problem in 3.x vorhanden ist, müssen Sie prüfen, ob das Problem auch in älteren 3.x-Versionen auftritt.
Wenn das Problem nicht in 3.x auftritt, können Sie ältere 4.0 Alphas und Betas ausprobieren, um festzustellen, wann der Regressions-Bug begann.

Warnung

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¶

Um mit dem Bisecting zu beginnen, müssen Sie zunächst die Commit-Hashes (Identifier) des "schlechten" und "guten" Builds ermitteln. "Schlecht" bezieht sich auf den Build, der den Bug aufweist, während "gut" sich auf die Version bezieht, die den Bug nicht aufweist. Wenn Sie einen Pre-Release-Build als "guten" oder "schlechten" Build verwenden, durchsuchen Sie den Download-Mirror, gehen Sie in den Ordner, der Ihren heruntergeladenen Pre-Release enthält und suchen Sie nach der Datei README.txt. Der Commit-Hash wird in diese Datei geschrieben.

Wenn Sie ein stable Release als "guten" oder "schlechten" Build verwenden, benutzen Sie je nach Version einen der folgenden Commit-Hashes:

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

Sie können auch diese Bash-Funktion verwenden, um den Git-Commit-Hash eines Pre-Release-Builds abzurufen (fügen Sie ihn zu Ihrer $HOME/.bashrc oder ähnlichem hinzu):

gd_snapshot_commit() {
    curl -s https://downloads.tuxfamily.org/godotengine/$1/$2/README.txt \
        | grep 'from commit' \
        | sed 's/^Built from commit \(.*\)\.$/\1/'
}

Anwendungsbeispiel:

$ gd_snapshot_commit 4.0 beta4

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

Bemerkung

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