Individuare regressioni tramite bisezione

La bisezione (bisecting) è un modo per individuare regressioni nel software. Dopo aver segnalato un bug nel repository di Godot su GitHub, un collaboratore potrebbe chiedere di bisezionare il problema. La bisezione permette ai collaboratori di correggere i bug più velocemente, poiché possono sapere in anticipo quale commit ha causato la regressione. L'impegno sarà ampiamente apprezzato :)

La guida seguente spiega come trovare una regressione tramite bisezione.

Che cos'è la bisezione?

Gli sviluppatori di Godot utilizzano il sistema di controllo versioni Git. Nel contesto di Git, la bisezione (bisecting) è il processo di esecuzione manuale di una ricerca binaria per determinare quando è comparsa una regressione. Sebbene sia tipicamente utilizzata per i bug, si può utilizzare anche per individuare altri tipi di cambiamenti imprevisti, come le regressioni delle prestazioni.

Utilizzare build ufficiali per velocizzare la bisezione

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.

Pericolo

I file di progetto potrebbero essere incompatibili tra le diverse versioni di Godot. Effettuare un backup del progetto prima di iniziare il processo di bisezione.

Passare dalla build più vecchia a quella più recente generalmente riduce il rischio che il progetto non si possa aprire correttamente nell'editor, grazie alla retrocompatibilità. Cercare anche di ridurre il proprio progetto al più piccolo esempio ripetibile. Più il progetto è minimale, maggiori saranno le probabilità di poterlo aprire senza problemi di compatibilità nelle versioni più recenti del motore.

Il comando "git bisect"

Se una build è stata individuata che non ha presentato il bug nel processo di test descritto in precedenza, si può iniziare a bisecare la regressione. Il sistema di controllo versioni Git offre un comando integrato per questo: git bisect. Ciò rende la procedura semi-automatica, poiché sarà necessario solo compilare il motore, eseguirlo e provare a riprodurre il bug.

Nota

Prima di bisecare una regressione, è necessario configurare un ambiente di compilazione per compilare Godot da sorgente. Per farlo, consultare la pagina Compilazione per la propria piattaforma di destinazione. (La compilazione di Godot da sorgente non richiede conoscenze di programmazione in C++.)

Si noti che la compilazione di Godot può richiedere un po' di tempo su hardware lento (fino a un'ora per ogni ricostruzione completa su una CPU dual-core lenta). Ciò significa che l'intero processo può richiedere fino a diverse ore. Se l'hardware è troppo lento, è consigliabile fermarsi qui e segnalare i risultati della "pre-bisecting" sul problema su GitHub in modo che un altro collaboratore possa continuare la bisezione da lì.

Determinare gli hash dei commit

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.

Per fare riferimento allo stato più recente del branch master, è possibile utilizzare master invece di un hash di commit. Si noti che, a differenza delle release taggate o degli hash di commit snapshot, master è un obiettivo in continuo movimento.

Compilare il motore

Ottienere il codice sorgente di Godot usando Git. Una volta fatto, nella finestra del terminale, utilizzare cd per raggiungere la cartella del repository di Godot e inserire il seguente comando:

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

Compilare Godot. Ciò presuppone che si abbia configurato un ambiente di compilazione:

scons

Eseguire il motore

Avviare l'eseguibile situato nella cartella bin/ e provare a riprodurre il bug.

Nota

Controllare attentamente il nome del file di output in bin/ per assicurarsi di avviare effettivamente l'eseguibile appena compilato. Versioni diverse di Godot produrranno eseguibili con nomi diversi.

Se la compilazione ancora presenta il bug, eseguire il seguente comando:

git bisect bad

Se la compilazione non presenta il bug, eseguire il seguente comando:

git bisect good

Dopo aver inserito uno dei comandi precedenti, Git passerà a un commit diverso. Ora si dovrebbe compilare nuovamente Godot, provare a riprodurre il bug, poi digitare git bisect good o git bisect bad a seconda del risultato. Si dovrà ripetere questa operazione più volte. Più lungo è l'intervallo di commit, più passaggi saranno necessari. Di solito, da 5 a 10 passaggi sono sufficienti per trovare gran parte delle regressioni; Git ricorderà il numero di passaggi rimanenti (nel caso peggiore).

Una volta completati sufficienti passaggi, Git mostrerà l'hash del commit in cui è comparsa la regressione. Scrivere questo hash del commit come commento alla pagina del problema su GitHub a cui è stata effettuata questa operazione. Ciò aiuterà a risolvere il problema. Grazie ancora per aver contributo a Godot :)

Vedi anche

È possibile leggere la documentazione completa su git bisect qui.