Halbierender Rückschritt¶
Halbierung ist ein Weg, um Rückschritte in Software zu finden. Nachdem Sie einen Fehler im Godot repository on GitHub gemeldet haben, werden Sie möglicherweise von einem Mitwirkenden gebeten, das Problem zu halbieren. Durch die Halbierung können Mitwirkende Fehler schneller beheben, da sie im Voraus wissen, welches Commit den Rückschritt verursacht hat. Ihre Bemühungen werden allgemein geschätzt :)
In der folgenden Anleitung wird erläutert, wie Sie einen Rückschritt durch Halbieren finden.
Was ist halbierend?¶
Godot-Entwickler verwenden das Versionskontrollsystem Git. Im Kontext von Git ist die Halbierung der Prozess der Durchführung für eine manuelle binäre Suche , um festzustellen, wann ein Rückschritt aufgetreten ist. Während es normalerweise für Fehler verwendet wird, können damit auch andere Arten unerwarteter Änderungen gefunden werden, z.B. Leistungsrückschritte.
Verwenden Sie offizielle Builds, um die Halbierung zu beschleunigen¶
Bevor Sie den bisect-Befehl von Git verwenden, empfehlen wir dringend, den Fehler 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 z. B. einen Fehler mit Godot 3.2 gemeldet haben, sollten Sie zunächst versuchen, den Fehler in Godot 3.1 zu reproduzieren (keine Patch-Version, siehe unten für den Grund). Wenn der Fehler dort nicht auftritt, versuchen Sie, ihn in Godot 3.2 beta 1 zu reproduzieren (was ungefähr in der Mitte aller verfügbaren Test-Builds liegt). Wenn Sie den Fehler mit Godot 3.2 beta 1 nicht reproduzieren können, dann versuchen Sie neuere Betas und RC-Builds. Wenn Sie es schaffen, den Fehler mit Godot 3.2 beta 1 zu reproduzieren, dann versuchen Sie ältere Alpha-Builds.
Warnung
Verwenden Sie für die Bisektion von Regressionen keine Patch-Versionen wie Godot 3.1.2. Verwenden Sie stattdessen das erste Release der Minor-Version wie Godot 3.1. Das liegt daran, dass Patch-Versionen aus einem separaten stable branch erstellt werden. Diese Art von Zweig folgt nicht der restlichen Entwicklung von Godot, die im master-Zweig stattfindet.
Der Befehl Git bisect¶
Wenn Sie einen Build gefunden haben, der den Fehler im obigen Testprozess nicht aufwies, können Sie nun damit beginnen, die Regression 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 Fehler zu reproduzieren.
Bemerkung
Bevor Sie eine Regression bisectieren, müssen Sie eine Build-Umgebung einrichten, um Godot aus dem Quellcode zu kompilieren. Lesen Sie dazu die Seite Kompilieren für Ihre Zielplattform. (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 Neuaufbau 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-Bisectierung" im GitHub Issue berichten, so dass ein anderer Mitwirkender von dort aus das Bisecting fortsetzen kann.
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 Fehler aufweist, während "gut" sich auf die Version bezieht, die den Fehler 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 den Pre-Release enthält, den Sie heruntergeladen haben und suchen Sie nach der Datei README.txt. Der Commit-Hash wird in diese Datei geschrieben.
Wenn Sie eine stabile Version als "guten" oder "schlechten" Build verwenden, benutzen Sie je nach Version einen der folgenden Commit-Hashes:
3.2-stable
3.1-stable
3.0-stable
Um auf den letzten Stand des Master-Zweigs zu verweisen, können Sie master anstelle eines Commit-Hashs verwenden.
Holen Sie 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>
Kompiliere Godot. Dies setzt voraus, dass Sie eine Build-Umgebung eingerichtet haben:
# <platform> is the platform you're targeting for regression testing,
# like "windows", "x11" or "osx".
$ scons platform=<platform> -j4
Da der Build von Godot eine Weile dauert, möchten Sie so viele CPU-Threads wie möglich für die Aufgabe verwenden. Dies wird durch den Parameter -j erreicht. Hier weist der Befehl 4 CPU-Threads zum Kompilieren von Godot zu.
Führen Sie die Binärdatei im Ordner bin / aus und versuchen Sie, den Fehler zu reproduzieren.
Wenn der Build immer noch den Fehler aufweist, führen Sie den folgenden Befehl aus:
$ git bisect bad
Wenn der Build den Fehler 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 builden, versuchen, den Fehler 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 Regressionen 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 die Regression aufgetreten ist. Schreiben Sie diesen Commit-Hash als Kommentar zu dem GitHub Issue, das Sie bisected 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.