Traducción de Mastering Issues. 2014.02.07.
- Introducción
- Etapas, Etiquetas e Asignaciones
- Notificaciones, @menciones, y referencias
- Búsqueda
- Resúmenes y Reportes
- Otros usos para los Issues
Los Issues son una forma genial de administrar tus tareas, mejoras y bugs de tus proyectos. Son como un tipo de email — excepto que pueden ser compartidos y debatidos con el resto de tu equipo. La mayoría de los proyectos de software tienen un software administrador de bugs o algo parecido. El administrador de GitHub es llamado Issues, y tiene su propia sección en cada repositorio.
Por ejemplo, demos un vistazo a la sección de Issues de Bootstrap:
El administrador de issue de GitHub es especial debido a que se concentra en la colaboración, referencias y contiene un formateo de texto excelente. Un issue típico en GitHub se ve más o menos así:
- El título y la descripción describen de que se trata el issue.
- Las etiquetas (Labels) coloreadamente-resaltadas ayudan a organizar y filtrar tus issues (como las etiquetas en Gmail).
- Las etapas (Milestone) actúan como contenedores de issues. Esto es útil para asociar ciertos issues con características especificas o fases del proyecto (ejem. Sprint Semanal 9/5-9/16 o Envío 1.0)
- Un asignado (Assignee) es responsable de trabajar en el issue en un momento dado.
- Los comentarios permiten a cualquiera con acceso al repositorio dar su opinión.
Una vez que tengas un montón de issues, podría serte difícil encontrar en el que quieres trabajar. Las etapas, etiquetas, y asignaciones son una genial característica para filtrar y organizar tus issues.
Puedes cambiar o agrear una etapa (milestone), una asignación (assignee), y etiquetas (labels) dando un clic en el icono de engrane correspondiente en la barra lateral derecha.
Si no ves los botones de edición, es porque no tienes permiso para modificar ese issue. Puedes pedirle al dueño del repositorio que te agregue como colaborador para tener acceso.
Las Etapas son grupos de issues que corresponden a un proyecto, una característica, o un periodo de tiempo. Las personas utilizan esto de muchas maneras diferentes en el desarrollo de software. Algunos ejemplos:
- Lanzamiento Beta — Archivos con bugs que necesitas arreglar antes de poder lanzar la beta de tu proyecto. Es una idea genial para asegurarte que no estas olvidando nada.
- Sprint de Octubre — Lista de issues en los que quieres trabajar en Octubre. Una forma genial de enfocar tu esfuerzo cuando hay mucho que hacer.
- Re-diseño — Lista de issues relacionados al re-diseño de tu proyecto. Una forma genial de coleccionar ideas en las que podrías trabajar.
Las etiquetas son una forma de organizar diferentes tipos de issues. Los issues pueden tener tantas etiquetas como quieras, y puedes filtrarlas por una o por varias.
Cada issue tiene un asignado — una persona que es la responsable para llevar el issue en buena dirección. Las asignaciones son seleccionadas de la misma manera que las etapas, a través de la barra gris en la parte superior de un issue.
Utilizando @menciones y referencias dentro de un issue, puedes notificar a otros usuarios o equipos en GitHub, y puede hacer llamados desde o otros issues. Esto provee una forma flexible de llamar a las personas correctas para que se involucren en resolver un issue efectivamente, y es fácil de aprender a utilizar. Funcionan en todos los campos de texto dentro de GitHub — son parte de nuestra sintaxis de formateo llamada GitHub Flavored Markdown.
Si quieres conocer más, puedes dar un vistazo a la Guía de Maestría en Markdown.
Las notificaciones son la forma de mantenerte al día con tus Issues. Puedes utilizarlas para saber que hay de nuevo en issues o en repositorios, o simplemente para saber cuando alguien necesita de tu ayuda.
Hay dos formas de recibir las notificaciones: vía email, y vía web. Puedes configurar cómo deseas recibir las notificaciones en tus opciones. Si tu plan es recibir un motón de notificación, te recomendamos que las recibas vía web y email para participar, y notificaciones web para Observar.
Con esta configuración, recibirás emails sólo cuando seas mencionado, así que visita la interfaz web para mantenerte al día con los repositorios en los que estás interesado.
Puedes tener acceso a tus notificaciones a través de la pantalla de notificaciones. Esta pantalla es genial para escanear muchas notificaciones a la vez y marcar cuando las has leído o callar una conversación. Intenta utilizar los atajos del teclado para mayor rapidez — presiona ? en la página para ver los atajos del teclado que están disponibles.
Callar conversaciones hará que no muestre más mensajes de no-leído hasta que seas @mencionado de nuevo. Esto hace que callar sea un estrategia genial para conversaciones en las que no estás tan interesado (preparativos de un sub-sistema en los que no estas muy familiarizado). Si marcas un issue como leído, este se mantendrá así hasta que alguien comente en esa conversación nuevamente.
GitHub también sincroniza el estado de leído/no-leído de las notificaciones vía email — si ya leíste una notificación en tu cliente de correo, éste se marcara como leído en la interface web (asegúrate de que tu cliente de correo despliegue las imágenes si quieres que ésta función opere).
Las @menciones son la forma de referirse a otros usuarios en GitHub dentro de los issues de GitHub. Dentro de la descripción o en cualquier comentario de un issue, incluye el @nombre-de-usuario de otro usuario de GitHub para enviarle una notificación. Esto funciona muy similar a como lo hace Twitter con sus @menciones.
Nos gusta utilizar la sintaxis \cc (una abreviación de copia al carbón) para incluir personas en un issue:
Parece que el nuevo widget no funciona en Safari. Cuando lo probé y cree el widget, Safari fallo. Este funciona en la versión 10.8, pero no en la versión 10.9. ¿Podría ser una bug del navegador?
/cc @kneath @jresig
Es una forma genial si sabes a que usuarios deseas incluir, pero muchas veces estamos trabajando con varios equipos y realmente no sabemos quien está disponible para ayudarnos. Las @menciones también funcionan para Equipos dentro de una organización en GitHub. Si creas un Equipo llamado browser-bugs dentro de la organización @acmeinc, puedes referirte a ese equipo con la @mención:
/cc @acmeinc/browser-bugs
Esto enviará una notificación a cada miembro del equipo browser-bugs.
Muchas veces los issues dependen de otros issues, o al menos se relacionan entre sí y quieres que estén conectados. Puedes referirte a un issue escribiendo un hashtag seguido del número del issue.
Hey @kneath, Creo que el problema comenzó en #42
Cuando haces esto, nosotros creamos un evento dentro del issue #42 que se ve algo así:
¿Un issue en otro repositorio? Solo incluye el repositorio antes del nombre, así: kneath/proyecto-de-ejemplo#42.
Una de las cosas más interesantes de utilizar Issues en GitHub es la referencia a issues directamente desde los commits. Incluye un número de issue dentro de un mensaje de un commit.
Anteponiendo en tus commits la palabra "Fixes", "Fixed", "Fix", "Closes", "Closed" o "Close" cuando el commit se merge (funcione) con el master, automáticamente ese issue se cerrará.
Las referencias hacen posible conectar el trabajo que se está haciendo con el bug que se esta tratando, y son una forma genial de añadir visibilidad dentro del historial de tu proyecto.
Arriba de cada página se encuentra el campo de búsqueda que te permite hacer búsquedas entre los issues.
- Todos los issues mensionados en la barra lateral
- ...que estén abiertos (da un vistazo a los links de la barra lateral a mano izquierda para filtrar los abiertos o cerrados)
- Asignados a @mdo
- O buscar entre todos los issues de GitHub dando clic en el link de la barra lateral
Vista la página de búsqueda avanzada para aprender otras formas de buscar entre los issues: utilizando fechas de creación o actualización, etiquetas, autores, numero de comentarios, por dueño de repositorios, y más.
Fuera de las sección de Issues, hay otras dos páginas que te ayudarán a resumir que pasa con los issues a través de un repositorio y a través de todos tus repositorios.
Si estás buscando un listado de todos tus issues a través de muchos proyectos, el Dashboard de Issues puede ser una gran herramienta. El dashboard funciona muy similar a la sección de issues, pero agrupa los issues de forma diferente:
- Todos los issues en repositorios que eres dueño o en los que colaboras.
- Issues asignados a ti.
- Issues que tu has creado.
Si utilizas organizaciones, cada organización tendrá su propio dashboar de Issues que separa cada Issue dentro de la organización.
Dentro de cada repositorio está una sección llamada Pulse (Pulso) — El Pulso es un snapshot de todo lo que paso en el repositorio hace una semana ( día, ó 3 meses, etc).
Es una forma genial de ponerse al día con los repositorios para cuando has esta fuera y no quieres recibir notificaciones regularmente como cuando estas observando un repositorio.
Los Issues son geniales para rastrear todo tipo de cosas — y GitHub es un lugar genial para compartir de manera fácil y de colaborar con tus issues. Aquí hay unos de nuestros favoritos:
- Rastrear bugs desde tu casa incluyendo algunas gemas como la puerta está colgada incorrectamente
- Rastrear bugs para proyectos open source
- Pedir recetas (o talvés tengas una buena receta de pizza sin gluten)
Ahora felicítate a ti mismo — eso fue mucho que leer. La administración de Issues es una de las herramientas más poderosas que está a disposición de cualquier desarrollador. Supongo que todo lo que queda es arreglar tus bugs.