Up to date

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

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¶

Antes de usar el comando bisect de Git, recomendamos encarecidamente intentar reproducir el error con una versión oficial anterior (o más reciente). Esto reduce en gran medida el rango de commits que potencialmente necesitan ser compilados desde el código fuente y probados. Puedes encontrar binarios de versiones oficiales, así como versiones alfa, beta y candidatas a lanzamiento aquí.

If you have experience with Godot 3.x and can reproduce an issue with Godot 4.0, we recommend trying to reproduce the issue in the latest Godot 3.x version (if the feature exhibiting the bug is present in 3.x). This can be used to check whether the issue is a regression in 4.0 or not.

If the issue is present in 3.x, then you'll need to check whether the issue occurs in older 3.x versions as well.
If the issue is not present in 3.x, then you can try older 4.0 alphas and betas to determine when the regression started.

Advertencia

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

Going from the oldest to the newest build generally reduces the risk of the project not being able to successfully open in the editor, thanks to backwards compatibility. Try to reduce your project to the smallest repeatable example too. The more minimal the project is, the more likely you'll be able to open it without compatibility issues in newer engine versions.

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¶

Para comenzar el bisecting, primero debes determinar los identificadores de los commits (hashes) de la compilación "mala" y "buena". "Mala" se refiere a la compilación que muestra el error, mientras que "buena" se refiere a la versión que no muestra el error. Si estás utilizando una compilación de prelanzamiento como la compilación "buena" o "mala", navega hacia el mirror de descargas, ve a la carpeta que contiene el prelanzamiento que descargaste y busca el archivo "README.txt". El identificador del commit estará escrito dentro de ese archivo.

Si estás utilizando una versión estable como la compilación "buena" o "mala", usa uno de los siguientes identificadores de commit según la versión:

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

You can also use this Bash function to retrieve the Git commit hash of a pre-release build (add it to your $HOME/.bashrc or similar):

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

Example usage:

$ gd_snapshot_commit 4.0 beta4

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

Nota

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