Directrices para el triaje de errores

Esta página describe el flujo de trabajo típico del equipo de triaje de errores, también conocido como "bugsquad", al manejar problemas y solicitudes de extracción en el repositorio de Godot en GitHub. Está destinado a evolucionar junto con el bugsquad, así que no dudes en proponer modificaciones a las siguientes directrices.

Gestión de problemas (issues)

GitHub propone varias características para gestionar problemas (issues):

  • Establecer una o varias etiquetas de una lista predefinida

  • Establecer un hito (milestone) de una lista predefinida

  • Hacer seguimiento del problema en el tablero del proyecto

  • Definir a un colaborador como "asignado" (assignee) entre los miembros de la organización Godot engine

Como la organización Godot engine en GitHub actualmente tiene un número limitado de colaboradores, no utilizamos asignaciones de manera extensa por ahora. Todos los colaboradores son bienvenidos a trabajar en cualquier problema, si es relevante, después de mencionarlo en el ticket del problema y/o discutir la mejor manera de resolverlo con otros desarrolladores.

Por el momento, tampoco utilizamos la función del tablero de proyectos.

En la medida de lo posible, tratamos de asignar etiquetas (y hitos, cuando sea relevante) tanto a los problemas como a las solicitudes de extracción (pull requests).

Etiquetas

Las siguientes etiquetas están actualmente definidas en el repositorio de Godot:

Categorías

  • Archived: Se refiere a problemas que son duplicados de otro problema o que son inválidos. Estos problemas también serán cerrados.

  • Breaks compat: Describe algo que solo puede solucionarse rompiendo la compatibilidad con proyectos existentes.

  • Bug: Describe algo que no está funcionando correctamente.

  • Cherrypick: Describe algo que se puede aplicar en una rama estable después de haber sido fusionado en la rama master.

  • Crash: Describe un error que hace que el motor se cierre inesperadamente. Esta etiqueta se utiliza solo para "crashes" (cierres abruptos) reales, no para bloqueos.

  • Confirmed: Ha sido confirmado por al menos otro colaborador aparte del reportador del error (normalmente para informes de Bugs). El propósito de esta etiqueta es permitir a los desarrolladores saber qué problemas siguen siendo reproducibles cuando desean seleccionar en qué trabajar. Por lo tanto, es una buena práctica agregar en un comentario en qué plataforma y qué versión o commit de Godot se pudo reproducir el problema; si un desarrollador mira el problema un año después, la etiqueta Confirmed puede no ser relevante.

  • Discussion: El problema no es consensual y requiere más discusión para definir qué exactamente se debe hacer para abordar el tema.

  • Documentation: Problema relacionado con la documentación. Principalmente para solicitar mejoras en la documentación de la API. Los problemas relacionados con la documentación de ReadTheDocs deben presentarse en el repositorio godot-docs.

  • Enhancement: Describe una mejora propuesta para una funcionalidad existente.

  • Feature proposal: Describe un deseo de que se implemente una nueva funcionalidad. Tenga en cuenta que el repositorio principal de Godot ya no acepta solicitudes de nuevas características. Por favor, use godot-proposals en su lugar.

  • For PR meeting: El problema necesita ser discutido en una reunión de solicitudes de extracción (pull request). Estas reuniones son públicas y se llevan a cabo en el Godot Contributors Chat.

  • Good first issue: El problema se asume que es fácil de solucionar, lo que lo convierte en una excelente opción para nuevos colaboradores que necesitan familiarizarse con el código base.

  • High priority: El problema es particularmente importante ya que puede evitar que las personas lancen sus proyectos o causar pérdida de datos.

  • Needs work: El pull request necesita trabajo adicional antes de que pueda ser fusionado.

  • Needs testing: El issue o pull request no ha sido completamente probado y necesita pruebas adicionales. Esto puede significar que necesita ser probado en diferentes configuraciones de hardware o software, o incluso que los pasos para reproducir el problema no están claros.

  • Performance: problemas que impactan directamente en el rendimiento del motor o del editor. También puede usarse para pull requests que mejoran el rendimiento o añaden opciones para dispositivos de baja gama. No debería usarse junto con Usabilidad.

  • PR bienvenidas / ¡Se busca héroe!: Las contribuciones para problemas con estas etiquetas son especialmente bienvenidas. Sin embargo, esto no significa que no puedas trabajar en problemas que no tengan estas etiquetas.

  • Regresión: el error apareció después de que se lanzara una versión estable que no presentaba el error.

  • Salvable: el pull request no puede ser fusionado debido a problemas de diseño o conflictos de fusión, y su autor ya no está activo. Sin embargo, todavía puede ser retomado por un colaborador externo para llevarlo a un estado que pueda ser fusionado. Para hacerlo, necesitas abrir un nuevo pull request basado en el pull request original.

  • Tracker: issue utilizado para rastrear otros problemas (como todos los problemas relacionados con el sistema de complementos).

  • Usabilidad: problemas que impactan directamente la usabilidad para los usuarios. No debe estar relacionado con Rendimiento.

Las categorías se utilizan para la triage general de los problemas. Se pueden combinar de alguna manera cuando sea relevante, por ejemplo, un problema puede tener las etiquetas Enhancement y Usability al mismo tiempo si se trata de un problema para mejorar la usabilidad. O Feature proposal y Discussion si es una propuesta de función no consensuada, o una que no es lo suficientemente precisa para trabajar en ella.

Tópicos

  • 2D: se refiere a problemas específicos de 2D. Debe combinarse con una de las siguientes etiquetas y no debe combinarse con 3D.

  • 3D: se refiere a problemas específicos de 3D. Debe combinarse con una de las siguientes etiquetas y no debe combinarse con 2D.

  • Assetlib: se refiere a problemas relacionados con la biblioteca de activos (asset library).

  • Audio: se refiere a características relacionadas con el audio (nivel bajo y alto).

  • Buildsystem: se refiere a problemas de construcción, ya sea relacionados con el sistema de construcción SCons o con peculiaridades del compilador.

  • Codestyle: se refiere al estilo de programación utilizado dentro del código fuente.

  • Core: cualquier cosa relacionada con el motor principal (core). Es posible que se divida aún más en el futuro, ya que es un tema bastante extenso.

  • Editor: se refiere a problemas en el editor (principalmente la interfaz de usuario).

  • GDNative: se refiere al módulo GDNative.

  • GDScript: se refiere a GDScript.

  • GUI: se refiere a nodos GUI (Control).

  • Import: se refiere al sistema de importación de recursos.

  • Input: se refiere al sistema de entrada (input).

  • Mono: se refiere a las vinculaciones (bindings) de C# / Mono.

  • Navigation: se refiere al sistema de navegación (que incluye A* y navmeshes).

  • Network: se refiere a temas relacionados con la red (networking).

  • Physics: se refiere al motor de físicas (2D/3D).

  • Plugin: se refiere a problemas encontrados al escribir complementos (plugins).

  • Porting: se refiere a plataformas específicas o a la exportación de proyectos.

  • Rendering: se refiere a los motores de renderizado 2D y 3D.

  • Shaders: se refiere al lenguaje de sombreado de Godot o a los sombreadores visuales.

  • Tests: se refiere a las pruebas unitarias.

  • Thirdparty: se refiere a bibliotecas de terceros utilizadas en Godot.

  • VisualScript: se refiere a problemas con el lenguaje de secuencias visuales (no shaders visuales).

  • XR: se refiere a la Realidad Aumentada o Realidad Virtual.

Las issues típicamente corresponderán a un solo tema, aunque no es impensable ver issues que encajen en dos categorías. La idea general es que habrá equipos de colaboradores especializados para cada tema, para que puedan centrarse en las issues etiquetadas con el tema de su equipo.

Plataformas

Android, HTML5, iOS, Linux, macOS, Windows, UWP

Por defecto, se asume que una determinada issue se aplica a todas las plataformas. Si se utiliza una de las etiquetas de plataforma, entonces esa etiqueta se considera exclusiva y la suposición anterior ya no se aplica (por lo tanto, si es un bug exclusivo de Android y Linux, selecciona esas dos plataformas).

Etiquetas de documentación

En el repositorio de la documentación, usaremos las siguientes etiquetas:

  • Bug: Información incorrecta en una página existente. No se debe usar para información que falta.

  • Class reference: El problema se refiere a la referencia de clase, no a una página de documentación.

  • Discussion: El problema no es consensual y requiere más discusión para definir qué exactamente se debe hacer para abordar el tema.

  • Enhancement: Nueva información que debe agregarse en una página existente de documentación.

  • Nueva página: Se debe crear una nueva página de documentación.

  • ¡Se busca un héroe!: Las contribuciones para los problemas con estas etiquetas son especialmente bienvenidas. Sin embargo, esto no significa que no puedas trabajar en problemas que no tengan estas etiquetas.

  • Organización: El problema implica mover páginas o reorganizar el contenido.

  • Redirección: se necesita crear una redirección en el backend de Read the Docs. Solo los administradores pueden hacer esto.

  • Salvable: el pull request no puede ser fusionado debido a problemas de diseño o conflictos de fusión, y su autor ya no está activo. Sin embargo, todavía puede ser retomado por un colaborador externo para llevarlo a un estado que pueda ser fusionado. Para hacerlo, necesitas abrir un nuevo pull request basado en el pull request original.

  • Topic:Mono: el problema está relacionado con el soporte de C# en Godot.

  • Topic:Website: el problema está relacionado con la interfaz o el funcionamiento de Sphinx/Read the Docs en el sitio web, no con el contenido de la documentación.

Hitos

Los hitos o etapas corresponden a versiones futuras planificadas de Godot para las cuales existe una hoja de ruta establecida. Los problemas que encajan en dicha hoja de ruta deben ser archivados bajo el hito correspondiente; si no se ajustan a ninguna hoja de ruta actual, deben dejarse sin hito. Como regla general, un problema corresponde a un hito determinado si se refiere a una característica nueva en el hito, o a un error crítico que no puede ser aceptado en ninguna versión estable futura, o cualquier cosa en la que Juan quiera trabajar en este momento. :)

Los colaboradores son libres de elegir problemas independientemente de su hito asignado; si se propone una solución para un error que no se consideró urgente y, por lo tanto, no tiene un hito asignado, probablemente aún sería muy bienvenida.