Triage de tickets

Django utiliza Trac para gestionar el trabajo en la base de código. Trac es un jardín comunitario donde se recogen los errores que las personas han encontrado y las características que Django ha decidido agregar. Al igual que en cualquier jardín, a veces hay malezas que arrancar y a veces flores y verduras que necesitan ser cosechadas. Necesitamos tu ayuda para distinguir una cosa de la otra, y al final, todos nos beneficiamos juntos.

Al igual que todos los jardines, podemos aspirar a la perfección, pero en realidad no existe tal cosa. Incluso en el jardín más impecable hay aún caracoles e insectos. En un jardín comunitario también hay personas útiles que – con las mejores intenciones – fertilizan las malezas y envenenan las rosas. Es tarea de la comunidad como un todo autogestionarse, minimizar los problemas y educar a quienes se integran en la comunidad para que puedan convertirse en miembros valiosos y contribuyentes.

De manera similar, si bien nos esforzamos por que Trac sea una representación perfecta del estado de progreso de Django, reconocemos que esto no sucederá. Al distribuir la carga de mantenimiento de Trac a la comunidad, aceptamos que habrá errores. Trac es «principalmente preciso», y damos permisos para el hecho de que en ocasiones estará equivocado. Eso está bien. Somos perfeccionistas con plazos.

Nosotros nos basamos en la comunidad para seguir participando, mantener los tickets lo más precisos posible y elevar problemas para su discusión en el **Django Forum**_ cuando haya confusión o desacuerdo.

Django es un proyecto de comunidad, y cada contribución ayuda. No podemos hacer esto sin tú.

Flujo de triaje

Desafortunadamente, no todos los informes en el seguimiento de tickets proporcionan todos los detalles requeridos. Un número de tickets han propuesto soluciones, pero esas no necesariamente cumplen con todos los requisitos adheriéndose a las directrices para contribuir.

Una forma de ayudar es realizar la triage de las solicitudes que han sido creadas por otros usuarios.

La mayoría del flujo de trabajo se basa en el concepto de las etapas de triage de un ticket. Cada etapa describe dónde en su vida un ticket dado está en cualquier momento. Junto con una docena de banderas, esta característica nos dice fácilmente qué y quién cada ticket está esperando a.

Dado que una imagen vale más que mil palabras, comencemos por allí:

Flujo de trabajo de triaje de tickets de Django

Tenemos dos roles en este diagrama:

  • Mergers: personas con acceso a los commits que son responsables de tomar la decisión final para fusionar un cambio.

  • Triadores de tickets: cualquier persona de la comunidad de Django que elija involucrarse en el proceso de desarrollo de Django. Nuestra instalación de Trac está intencionalmente dejada abierta al público, y cualquier persona puede triar tickets. Django es un proyecto comunitario, y animamos a la triage por parte de la comunidad.

Por ejemplo, aquí vemos el ciclo de vida de un ticket promedio:

  • Alice crea un ticket y envía una solicitud de extracción incompleta (sin pruebas, implementación incorrecta).

  • Bob revisa la solicitud de extracción, marca el ticket como «Aceptado», «necesita pruebas» y «la corrección necesita mejorar», y deja un comentario explicando a Alice cómo podría mejorarse la corrección.

  • Alice actualiza la solicitud de extracción, agregando pruebas (pero sin cambiar la implementación). Ella elimina los dos banderines.

  • Charlie revisa la solicitud de extracción y vuelve a establecer el «banderín de corrección necesita mejorar» con otro comentario sobre cómo mejorar la implementación.

  • Alice actualiza la solicitud de extracción, corrigiendo la implementación. Ella elimina la bandera «patch needs improvement».

  • Daisy revisa la solicitud de extracción y marca el ticket como «Listo para comprobar».

  • Jacob, un integrante del equipo de fusiones, revisa la solicitud de extracción y la fusiona.

Algunos tickets requieren mucho menos retroalimentación que este, pero entonces algunos tickets requieren muchísimo más.

Etapas de triaje

A continuación, describimos con mayor detalle las diversas etapas a través de las cuales un ticket puede pasar durante su vida útil.

No revisado

El ticket no ha sido revisado por nadie que se sintiera calificado para emitir un juicio sobre si el ticket contenía una cuestión válida o debía cerrarse por alguna de las diversas razones.

Aceptado

La gran zona gris! El significado absoluto de «aceptado» es que la cuestión descrita en el ticket es válida y está en alguna etapa de ser trabajada. Más allá de eso, hay varias consideraciones:

  • Aceptado + Sin Banderas

    El ticket es válido, pero todavía no se ha presentado una corrección para él. A menudo esto significa que puedes empezar a escribir una solución de forma segura. Esto es generalmente más cierto en el caso de los errores aceptados que las características aceptadas. Un ticket para un error que ha sido aceptado significa que la cuestión ha sido verificada por al menos un triador como un error legítimo - y probablemente debería ser corregido si es posible.

    Para nuevas características, los tickets aceptados solo deben existir después de que la idea haya pasado por el proceso apropiado para sugerir nuevas características <requesting-features>` y haya recibido aprobación de la comunidad y del Consejo Directivo, o ha sido aceptada en un DEP.

  • Aceptado + Tiene Corrección

    El ticket está esperando a que las personas revisen la solución suministrada. Esto significa descargar la corrección y probarla, verificar que contiene pruebas y documentación, ejecutar el conjunto de pruebas con la corrección incluida y dejar retroalimentación en el ticket.

  • Aceptado + Tiene Corrección + Necesita…

    Esto significa que el ticket ha sido revisado y se ha encontrado que necesita más trabajo. «Necesita pruebas» y «Necesita documentación» son autoexplicativos. «La corrección necesita mejorar» generalmente estará acompañada de un comentario en el ticket explicando qué es necesario para mejorar el código.

Listo Para Revisión

El ticket fue revisado por cualquier miembro de la comunidad distinto a la persona que suministró la corrección y se encontró que cumplía con todos los requisitos para una contribución comprometida. Ahora necesita un integrador dar una revisión final antes de ser comprometido.

Hay muchos solicitudes de extracción. Puede llevar un tiempo que tu corrección se revise. Consulta la FAQ sobre contribuciones de código <new-contributors-faq> para algunas ideas aquí.

Someday/Maybe

Esta etapa no se muestra en el diagrama. Se utiliza con moderación para seguir el rastro de cambios a largo plazo.

Estas tarjetas son poco comunes y, en general, menos útiles ya que no describen problemas concretos y acciones posibles.

Otros atributos de triaje

Un número de banderas, que aparecen como casillas de verificación en Trac, se pueden establecer en una tarjeta:

Tiene parche

Esto significa que la tarjeta tiene una solución asociada. Estas serán revisadas para asegurarse de que cumplan con las directrices documentadas <writing-code/submitting-patches>.

Los siguientes tres campos (Necesita documentación, Necesita pruebas, El parche necesita mejorar) solo se aplican si se ha suministrado un parche.

Necesita documentación

Esta bandera se utiliza para las tarjetas con parches que necesitan documentación asociada. La documentación completa de las características es un requisito previo antes de que podamos comprobarlas en el código base.

Necesitan pruebas

Esto marca la revisión como necesaria de pruebas unitarias asociadas. Una vez más, esto es una parte requerida de una contribución válida.

La revisión necesita mejoras

Este flag significa que aunque el ticket tiene una solución, no está aún listo para su inclusión en la base de código. Esto podría significar que la revisión ya no se aplica limpiamente, hay un defecto en la implementación o que el código no cumple con nuestros estándares.

Pegas fáciles

Los tickets que requerirían cambios pequeños y fáciles.

Tipo

Los tickets deben ser categorizados por tipo entre:

  • Nueva característica

    Para agregar algo nuevo.

  • Bug

    Cuando una cosa existente está rota o no se comporta como se espera.

  • Cleanup/optimization

    Cuando nada está roto pero algo podría ser más limpio, mejor, más rápido, más fuerte.

Componente

Los tickets deben clasificarse en componentes que indican a qué área del código base de Django pertenecen. Esto hace que los tickets estén mejor organizados y sean más fáciles de encontrar.

Gravedad

El atributo de gravedad se utiliza para identificar bloqueadores, es decir, problemas que deben resolverse antes de liberar la próxima versión de Django. Normalmente, esos problemas son bugs que causan regresiones en versiones anteriores o potencialmente causan pérdidas de datos graves. Este atributo se utiliza muy raramente y la mayoría de los tickets tienen una gravedad de «Normal».

Versión

Es posible utilizar el atributo versión para indicar en qué versión se identificó el bug informado.

UI/UI

Esta bandera se utiliza para los tickets relacionados con preguntas de interfaz de usuario y experiencias del usuario. Por ejemplo, esta bandera sería adecuada para características que interactúen con el usuario en formularios o la interfaz administrativa.

Cc

Puedes agregar tu nombre de usuario o dirección de correo electrónico a este campo para recibir notificaciones cuando se realicen nuevas contribuciones al ticket.

Palabras clave

Con este campo puedes etiquetar un ticket con varias palabras clave. Esto puede ser útil, por ejemplo, para agrupar varios tickets sobre el mismo tema. Las palabras clave pueden estar separadas por comas o espacios. La búsqueda de palabras clave encuentra la cadena de caracteres en cualquier parte de las palabras clave. Por ejemplo, al hacer clic en un ticket con la palabra clave «form» se mostrarán tickets similares etiquetados con palabras clave que contengan cadenas como «formset», «modelformset» y «ManagementForm».

Cierre de Tickets

Cuando un ticket ha completado su ciclo útil, es hora de cerrarlo. Cerrar un ticket es una gran responsabilidad, aunque. Tienes que estar seguro de que el problema está realmente resuelto, y debes tener en cuenta que el reportador del ticket puede no estar contento con que se cierre su ticket (a menos que esté resuelto!). Si no estás seguro de cerrar un ticket, deja un comentario con tus pensamientos en lugar de eso.

Si cierras un ticket, siempre asegúrate de lo siguiente:

  • Estás seguro de que el problema está resuelto.

  • Dejar un comentario explicando la decisión de cerrar el ticket.

  • Si hay alguna forma en que puedan mejorar el ticket para volver a abrirlo, hárselo a conocer.

  • Si el ticket es una duplicado, hacer referencia al ticket original. Además, se debe cruzar-referenciar el ticket cerrado dejando un comentario en el original – esto permite acceder a más información relacionada sobre el error reportado o la característica solicitada.

  • Sé amable. Nadie gusta que su ticket sea cerrado. Puede ser frustrante o incluso desalentador. La mejor forma de evitar que las personas se desanimen de contribuir a Django es ser amable y ofrecer sugerencias sobre cómo podrían mejorar este ticket y otros en el futuro.

Un ticket puede resolverse de varias maneras:

  • resuelto

    Se utiliza una vez que se ha incorporado un parche a Django y el problema está resuelto.

  • inválido

    Se utiliza si el ticket se encuentra incorrecto. Esto significa que el problema en el ticket es en realidad el resultado de un error del usuario, o describe un problema con algo distinto de Django, o no es un informe de errores ni una solicitud de características (por ejemplo, algunos nuevos usuarios envían consultas de soporte como tickets).

  • no se resolverá

    Used cuando alguien decide que la solicitud no es apropiada para su consideración en Django. A veces, un ticket se cierra como «wontfix» con una solicitud al reportero de iniciar una discusión en el Django Forum si ellos sienten diferente a la razón proporcionada por la persona que cerró el ticket. Otras veces, una discusión precede la decisión de cerrar un ticket. Siempre utilice el foro para obtener un consenso antes de reabrir tickets cerrados como «wontfix».

  • duplicado

    Se utiliza cuando otro ticket cubre el mismo problema. Al cerrar los tickets duplicados, mantenemos toda la discusión en un lugar, lo que ayuda a todos.

  • worksforme

    Se utiliza cuando el ticket no contiene suficiente detalle para replicar el bug original.

  • needsinfo

    Se utiliza cuando el ticket no contiene suficiente información para replicar el problema reportado, pero potencialmente todavía es válido. El ticket debe ser reabierto cuando se proporcione más información.

Si crees que el ticket fue cerrado por error – porque aún estás teniendo el problema, o ha surgido en otro lugar, o los triadores han cometido un error – por favor reabre el ticket y proporciona más información. De nuevo, no reabran tickets que hayan sido marcados como «wontfix» y llevuen el tema al Django Forum en su lugar.

¿Cómo puedo ayudar con la triage?

El proceso de triaje está impulsado principalmente por miembros de la comunidad. Realmente, CUALQUIERA puede ayudar.

To get involved, start by creando una cuenta en Trac. Si tienes una cuenta pero has olvidado tu contraseña, puedes resetearla utilizando la página de reseteo de contraseña.

Luego, puedes ayudar con:

  • Cerrar los «tickets no revisados» como «inválido», «funciona correctamente», o «duplicado», o «no se fijará».

  • Cerrar los «tickets no revisados» como «necesita información» cuando la descripción es demasiado escasa para ser acciónable.

  • Corregir las banderas «Necesita pruebas», «Necesita documentación», o «Tiene parche» para tickets donde están configuradas incorrectamente.

  • Establecer la bandera «Piquitos fáciles» para tickets que son pequeños y relativamente sencillos.

  • Establecer el tipo de tickets que aún no han sido categorizados.

  • Verificar si los «tickets antiguos» todavía son válidos. Si un ticket no ha tenido ninguna actividad en mucho tiempo, es posible que el problema haya sido resuelto pero el ticket todavía no se ha cerrado.

  • Identificar tendencias y temas en los tickets. Si hay muchos informes de errores sobre una parte particular de Django, puede indicar que debemos considerar refactorizar esa parte del código. Si una tendencia está emergiendo, deberías señalarla para su discusión (referenciando los tickets relevantes) en el Foro de Django.

  • Verificar si las soluciones presentadas por otros son correctas. Si lo son y también contienen documentación y pruebas adecuadas, entonces mueve las a la etapa «Listo para revisión». Si no lo son, deja un comentario explicando por qué y establece las banderas correspondientes («Parche necesita mejora», «Necesita pruebas» etc.).

Nota

La página de Informes contiene enlaces a muchas consultas útiles de Trac, incluyendo varias que son útiles para la clasificación de tickets y la revisión de propuestas tal como se sugiere arriba.

Puedes encontrar también más contributors nuevos.

Sin embargo, sí solicitamos lo siguiente de todos los miembros de la comunidad en general que trabajan en la base de datos del ticket:

  • Por favor, no promociones tus propios tickets a «Listo para revisión». Puedes marcar los tickets de otras personas que has revisado como «Listo para revisión», pero deberías obtener al menos la revisión de otro miembro de la comunidad sobre un parche que hayas presentado.

  • Por favor, no reviertas una decisión sin publicar un mensaje en el **foro de Django**_ para encontrar consenso.

  • Si tienes dudas sobre si debes realizar un cambio, no lo hagas pero en su lugar deja un comentario con tus inquietudes en la tarea, o publica un mensaje en el **foro de Django**_. Está bien estar seguro, pero tu aportación sigue siendo valiosa.

Dividir una regresión

Una regresión es un error que se encuentra en alguna versión más reciente de Django pero no en una versión anterior. Una pieza de información extremadamente útil es el commit que introdujo la regresión. Saber qué commit causó el cambio en el comportamiento ayuda a identificar si el cambio fue intencional o si fue un efecto secundario inadvertido. Aquí se muestra cómo determinarlo.

Escribe una prueba de regresión para la suite de pruebas de Django relacionada con el problema. Por ejemplo, simularemos que estamos depurando una regresión en las migraciones. Una vez escrita la prueba y confirmado que falla en la rama principal más reciente, colócala en un archivo separado que puedas ejecutar de forma independiente. Para nuestro ejemplo, simularemos que creamos tests/migrations/test_regression.py, que se puede ejecutar con:

$ ./runtests.py migrations.test_regression

La siguiente marca el punto actual en la historia como «malo» ya que la prueba falla:

$ git bisect bad
You need to start by "git bisect start"
Do you want me to do it for you [Y/n]? y

Ahora necesitamos encontrar un punto en la historia de Git antes de que se introdujera el regresivo (es decir, un punto donde la prueba pasa). Utiliza algo como git checkout HEAD~100 para comprobar una revisión anterior (100 commits antes, en este caso). Comprueba si la prueba falla. Si es así, marca ese punto como «malo» (git bisect bad), luego comprueba una revisión anterior y recheca.

$ git bisect good
Bisecting: X revisions left to test after this (roughly Y steps)
...

Ahora estamos listos para la parte divertida: utilizar git bisect run para automatizar el resto del proceso:

$ git bisect run tests/runtests.py migrations.test_regression

Deberías ver que git bisect utiliza una búsqueda binaria para comprobar revisiones entre los commits buenos y malos hasta encontrar el primer «mal» commit donde la prueba falla.

Ahora, informa tus resultados en el ticket de Trac, e incluye la prueba de regresión como adjunto. Cuando alguien escriba una solución para el bug, ya tendrán tu prueba como punto de partida.

« previous | up | next »