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í.

Por ejemplo, si has informado de un error en Godot 3.2, debes intentar primero reproducir el error en Godot 3.1 (no una versión de parche, ver más abajo la razón). Si el error no ocurre allí, intenta reproducirlo en Godot 3.2 beta 1 (que está aproximadamente en el centro de todas las versiones de prueba disponibles). Si no puedes reproducir el error con Godot 3.2 beta 1, entonces prueba con versiones beta más recientes y versiones candidatas a lanzamiento (RC). Si logras reproducir el error con Godot 3.2 beta 1, entonces intenta con versiones alfa más antiguas.

Advertencia

Para bisectar regresiones, no utilices versiones de parche como Godot 3.1.2. En su lugar, utiliza la primera versión de la versión menor, como Godot 3.1. Esto se debe a que las versiones de parche se construyen a partir de una rama estable separada. Este tipo de rama no sigue el resto del desarrollo de Godot, que se realiza en la rama master.

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.

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:

3.2-stable
3.1-stable
3.0-stable

Para hacer referencia al estado más reciente de la rama master, puedes usar master en lugar de un identificador de commit.

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:

# <platform> is the platform you're targeting for regression testing,
# like "windows", "x11" or "osx".
$ scons platform=<platform> -j4

Dado que compilar Godot lleva tiempo, quieres dedicar tantos hilos de CPU como sea posible a la tarea. Eso es lo que hace el parámetro -j. Aquí, el comando asigna 4 hilos de CPU para compilar Godot.

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

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í.