Búsqueda de regresiones mediante bisección

La bisección es una forma de encontrar regresiones en el software. Después de reportar un error en el repositorio de Godot en GitHub, es posible que un colaborador te pida biseccionar el problema. La bisección permite a los colaboradores solucionar los errores más rápido, ya que pueden conocer de antemano qué commit causó la regresión. ¡Tu esfuerzo será muy apreciado! :)

La guía a continuación explica cómo encontrar una regresión mediante la bisección.

¿Qué es Visual Scripting?

Los desarrolladores de Godot utilizan el sistema de control de versiones Git. En el contexto de Git, la bisección es el proceso de realizar una búsqueda binaria manual para determinar cuándo apareció una regresión. Aunque normalmente se utiliza para buscar errores, también puede usarse para encontrar otros tipos de cambios inesperados, como regresiones de rendimiento.

Usando compilaciones oficiales para acelerar la bisección

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.

Peligro

Project files may be incompatible between Godot versions. Make a backup of your project before starting the bisection process.

Pasar de la compilación más antigua a la más reciente generalmente reduce el riesgo de que el proyecto no se abra correctamente en el editor, gracias a la retrocompatibilidad. Intente reducir tu proyecto al mínimo ejemplo repetible. Cuanto más minimalista sea el proyecto, más probable será que pueda abrirlo sin problemas de compatibilidad en las versiones más recientes del motor.

El comando "Git bisect"

Si has encontrado una compilación que no muestra el error durante el proceso de prueba mencionado anteriormente, ahora puedes comenzar a bisectar la regresión. El sistema de control de versiones Git ofrece un comando incorporado para esto: git bisect. Esto hace que el proceso sea semi-automatizado, ya que solo tienes que compilar el motor, ejecutarlo e intentar reproducir el error.

Nota

Antes de bisectar una regresión, necesitas configurar un entorno de compilación para compilar Godot desde el código fuente. Para hacerlo, lee la página de Compilar para tu plataforma de destino. (Compilar Godot desde el código fuente no requiere conocimientos de programación en C++)

Ten en cuenta que compilar Godot puede llevar bastante tiempo en hardware lento (hasta una hora para cada reconstrucción completa en una CPU lenta de doble núcleo). Esto significa que el proceso completo puede tardar varias horas. Si tu hardware es demasiado lento, es posible que desees detenerte allí y reportar los resultados de tu "pre-bisecting" en el problema de GitHub para que otro colaborador pueda continuar bisectando desde ese punto.

Determine the 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.

To refer to the latest state of the master branch, you can use master instead of a commit hash. Note that unlike tagged releases or snapshot commit hashes, master is a perpetually moving target.

Build the engine

Obtener el código fuente de Godot utilizando Git. Una vez hecho esto, en la ventana de la terminal, utiliza cd para navegar hasta la carpeta del repositorio de Godot y ejecuta el siguiente 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>

Compila Godot. Esto asume que has configurado un entorno de compilación:

scons

Run the engine

Ejecuta el archivo binario que se encuentra en la carpeta bin/ y trata de reproducir el error.

Nota

Double-check the output file name in bin/ to make sure you're actually running the binary you've just compiled. Different Godot versions will output binaries with different names.

Si el compilado sigue presentando el error, ejecuta el siguiente comando:

git bisect bad

Si el compilado no presenta el error, ejecuta el siguiente comando:

git bisect good

Después de ingresar uno de los comandos anteriores, Git cambiará a un commit diferente. Ahora debes compilar Godot nuevamente, intentar reproducir el error y luego ingresar git bisect good o git bisect bad según el resultado. Tendrás que repetir esto varias veces. Cuanto más amplio sea el rango de commits, más pasos serán necesarios. Por lo general, de 5 a 10 pasos son suficientes para encontrar la mayoría de las regresiones; Git te recordará el número de pasos restantes (en el peor de los casos).

Una vez que hayas completado suficientes pasos, Git mostrará el commit en el que apareció la regresión. Escribe este hash de commit como un comentario en la página del problema en GitHub donde hiciste el bisect. Esto ayudará a resolver el problema. ¡Gracias de nuevo por contribuir a Godot! :)

Ver también

Puedes leer la documentación completa sobre git bisect aquí.