Last Updated: 2020-05-05

¿Qué es una incidencia?

A medida que un equipo de desarrollo de software avanza en la construcción de un proyecto determinado, se enfrentará a situaciones que pueden frenar o modificar el rumbo del producto en cuestión. Desde la administración y planeación del proyecto, es necesario hacer un seguimiento a todas estas situaciones, denominadas incidencias o issues (en inglés), para así poder tomar decisiones sobre el producto a nivel de código fuente, infraestructura o diseño. Una incidencia también puede estar relacionada con la necesidad de agregar una nueva funcionalidad o a una tarea pendiente del plan.

Importancia de un Issue Tracker

Un Issue Tracker es una herramienta de seguimiento de incidentes, que suele ser un paquete de software adaptable a cualquier tipo de proyecto y a cualquier contexto. El uso de estas herramientas se justifica en mantener un listado de incidentes en un mismo lugar para facilitar su administración a los clientes, que son, entre otros, compañías, empresas, grupos de trabajo.

Para las personas encargadas e involucradas en la construcción de un producto de software es muy importante conocer el plan de construcción del mismo y la retroalimentación que se brinda sobre su calidad. Así, pueden visualizar el rumbo que va guiando el proyecto y tomar decisiones para controlarlo. Además, hacer uso de herramientas para este propósito permite la centralización de la información relacionada con el estado del proyecto y la integración con otros componentes del stack tecnológico para automatizar y unificar los procesos de supervisión y desarrollo.

¿Qué aprenderá?

Al desarrollar este tutorial aprenderá:

• Cómo utilizar las funcionalidades de reporte de incidencias de GitHub.
• Opciones para reportar una incidencia en GitHub.
• Cómo configurar plantillas para una incidencia en GitHub.

Otras funcionalidades y particularidades de la plataforma serán mencionadas de manera superficial y, en algunos casos, serán obviadas. Los pasos fundamentales relacionados, por ejemplo, con la creación de una cuenta de usuario serán simplificados para centrar la concentración en el reporte de incidencias.

¿Qué construirá?

En el tutorial se dará una serie de instrucciones que le permitirán reportar una incidencia básica en la plataforma GitHub y configurar las opciones para una incidencia. Al final del tutorial usted deberá tener:

• Un repositorio de GitHub con plantillas para las incidencias.
• Una incidencia creada sobre un repositorio de GitHub.

¿Qué necesita?

• Conocimiento básico del concepto de una incidencia (además de la introducción brindada en este tutorial puede revisar el material en el libro del curso).
• Un navegador web (¡Cualquier navegador funciona!).
• Una cuenta de GitHub.

¿Qué es GitHub?

GitHub consiste en una plataforma abierta enfocada en el desarrollo de software que provee espacios en línea, denominados repositorios, para alojar los proyectos de software de los desarrolladores y las organizaciones; y permite conectarlos haciendo uso de Git.

Acceder a GitHub

GitHub es una amplia plataforma online. Para acceder, únicamente hay que ingresar, desde un navegador, a la página web oficial en el siguiente enlace: https://github.com

Sobre Git

Es el sistema manejador de versiones en el que se apoya GitHub. Git es un sistema que permite a los desarrolladores de software manejar repositorios centralizados que contienen los archivos propios de proyectos y se encarga de manejar adecuadamente las versiones ante los cambios que estos pueden sufrir por parte de uno o varios usuarios.

Funcionalidades de GitHub

La entidad fundamental de GitHub son los repositorios (ya que se basa en Git) que contienen los directorios con los archivos que los usuarios necesitan alojar y poner bajo un control de versiones. Sin embargo, hay muchas funcionalidades que giran alrededor de ellos además del manejo de versiones como, por ejemplo, vincularlos a proyectos u organizaciones; controlar los tableros de un proyecto y crear tarjetas en ellos; crear pull requests (o sugerir cambios significativos en el contenido del repositorio); y reportar incidencias relacionadas con un repositorio. Esta última funcionalidad es la que se aborda en este tutorial.

Para empezar, inicie sesión en una cuenta de GitHub. Podrá ver una página de bienvenida, y en la parte derecha de la barra superior, puede ver un botón con el símbolo "+". Al hacer clic en él, verá varias opciones desplegadas, entre las cuales se encuentra la opción "New repository". Esta le permite crear un repositorio.

Imagen 1. Página de bienvenida de GitHub y menú desplegable para crear contenido

Desde la misma barra superior, también puede acceder a la vista de todos los repositorios, desplegando el menú del icono del extremo derecho y seleccionando la pestaña "Your repositories". Por esta vía también puede crear el repositorio. Una vez allí, podrá ver un botón para crear su repositorio con el nombre "New" en la parte derecha de la pantalla, como se muestra a continuación:

Imagen 2. Pestaña de repositorios y otras opciones del perfil

Cree un repositorio por una de las vías mencionadas antes. Al acceder a la vista para crear un nuevo repositorio, se muestra una pantalla donde debe llenar los campos correspondientes al nombre del repositorio, y opcionalmente, la descripción del mismo, además, podrá seleccionar un nivel de visibilidad, que permite controlar quién ve el repositorio; si se desea, también puede modificar la configuración de los archivos adicionales a nivel de proyecto según el tipo de proyecto. Por ejemplo, incluir un archivo README.md con información del repositorio. Esta pantalla se muestra a continuación:

Imagen 3. Formulario de creación de un repositorio

Para este tutorial, cree un repositorio con el nombre "ejemplo-issues", con visibilidad pública y los demás campos opcionales con su valor predeterminado. Cuando haya llenado la información, haga clic en el botón "Create repository". Ahora tiene su repositorio.

Una vez haya creado el repositorio, podrá ver unas instrucciones en pantalla para agregar contenido. Por lo pronto, las puede ignorar. También podrá ver, arriba de dicho contenido, varias pestañas que muestran información sobre el repositorio:

Imagen 4. Pestañas con información del repositorio

Puede explorar estas pestañas para familiarizarse mejor con su repositorio.

Reportar incidencias sobre un repositorio es una operación restringida a usuarios específicos según el rol que tienen y el nivel de visibilidad elegido. En un repositorio público cualquier persona puede realizar un reporte, mientras que en un repositorio privado, solo ciertos usuarios con acceso pueden hacerlo. No obstante, si el dueño del repositorio desactiva la opción de generar incidencias, ningún usuario podrá reportar incidencias.

Para crear una incidencia, diríjase a la pestaña "Issues" del repositorio y haga clic en el botón "New Issue", en la parte superior derecha del contenido para hacer el reporte. Si es la primera vez que reporta una incidencia estará vacío. Se mostrará un formulario para la incidencia que consiste, básicamente, en un título y una descripción, con opciones adicionales. La incidencia luego de ser creada, podrá recibir comentarios y etiquetas.

El contenido puede ser muy variado e incluir, por ejemplo, enlaces a lugares específicos de los archivos (en particular, del código fuente, como se explica en el siguiente enlace: https://help.github.com/es/github/managing-your-work-on-github/opening-an-issue-from-code), imágenes, listas de tareas (para mayor detalle consultar en este enlace: https://help.github.com/es/github/managing-your-work-on-github/about-task-lists), menciones a usuarios, referencias a pull requests u otras incidencias, archivos y contenido en markdown. Puede explorar todas estas opciones con los botones que se encuentran en la parte superior del campo de texto relacionado con la descripción de la incidencia. La parte de la interfaz que contiene dichas opciones es un listado horizontal con varios símbolos, como se ve en la siguiente imagen:

Imagen 5. Opciones de formato del contenido de una incidencia

Uno de los aspectos más importantes y que más resalta de GitHub es la posibilidad de vincular las incidencias con distintos conceptos relevantes para el proyecto. Se pueden vincular a un pull request para indicar que una propuesta de cambio en el código puede resolver dicha situación. También se pueden vincular a un commit para indicar que el cambio realizado en el código modificó el estado de la incidencia. Esto permite un mejor seguimiento del proyecto en su totalidad, ya que unifica varias formas de reportar el estado del mismo.

Para este tutorial, agregue un título a su incidencia y en el contenido incluya un ejemplo de cada una de las opciones, como se muestra a continuación:

Imagen 6. Formulario de creación de una incidencia

Desde acá, podrá previsualizar el renderizado de su incidencia. Para esto, haga clic en el tab "Preview".

Luego de estudiar todas las posibilidades que tiene para incluir contenido en su incidencia, publique la incidencia en el repositorio haciendo clic en el botón "Submit new issue".

Ahora podrá ver el detalle de la incidencia que creó, como se muestra a continuación, y, si lo desea, modificar su contenido, su estado o dar una respuesta:

Imagen 7. Resultado de una incidencia creada

Proyecto propio

Cuando un usuario decide crear una incidencia sobre un repositorio del cual es dueño, tiene acceso a todas las características de GitHub para reportar incidencias. Esto incluye la asignación de la incidencia a un miembro (delegación de responsabilidad), la agregación de etiquetas propias del repositorio (etiquetar la incidencia por categorías) y la vinculación a los tableros de seguimiento de proyectos (projects y milestones) o a pull requests. Las opciones para configurar se muestran en un panel lateral a la derecha de los campos de creación de una incidencia, como se ve a continuación:

Imagen 8. Panel lateral de configuración de la incidencia

Proyecto colaborativo

Crear incidencias sobre un proyecto colaborativo que no pertenece al usuario actual a veces implica limitación en las funcionalidades, dado que los roles, como se mencionó anteriormente, restringen la libertad que se tiene para modificar cierta información del proyecto. Existe la posibilidad de que un usuario no pueda crear incidencias sobre un repositorio ajeno si el dueño decidió limitar esta operación a ciertos roles, si el repositorio es privado o si se desactivan las incidencias. Si no se han desactivado las incidencias, pero su rol le restringe los privilegios sobre el repositorio, no se cuenta con el panel lateral de configuración que se menciona en el apartado inmediatamente anterior, pero la funcionalidad básica de reportar un suceso relacionada al proyecto sigue existiendo. Para comprobar esto, diríjase al siguiente repositorio e intente crear una incidencia https://github.com/monitor177/ejemplo-issues/issues. Note la parte derecha del formulario. Podrá ver que las opciones que aparecían anteriormente en su repositorio ya no están disponibles.

Agregar una plantilla

Para categorizar mejor y establecer un formato para las incidencias que se crean sobre su proyecto, puede agregar plantillas que corresponden a tres grandes categorías: Bug report (para reportar un problema con el proyecto), Feature request (para sugerir o solicitar una adición de funcionalidades en el proyecto) y Tracking issue (para marcar el seguimiento de alguna secuencia de tareas).

Para configurar sus plantillas, acceda, en la parte superior de su repositorio, a la pestaña "Settings". Al desplazarse a la parte inferior de las configuraciones en el centro de la pantalla, encontrará una con el nombre de "Issues", como se ve en la siguiente imagen:

Imagen 9. Apartado de incidencias en la configuración

Haga clic en el botón "Set up templates" para configurar las plantillas del repositorio. Podrá ver que en el momento no tiene ninguna y en el centro de la pantalla hay un botón desplegable con el nombre "Add template: select", como se ve a continuación:

Imagen 10. Botón de agregación de plantillas al repositorio

Al hacer clic, se desplegarán las plantillas por defecto indicadas anteriormente y una opción para agregar una plantilla personalizada vacía. Si lo desea, puede explorar las opciones en detalle. Para este tutorial, seleccione el tipo bug report. Sobre la plantilla creada, al hacer clic en el botón "Preview and edit" se mostrará el detalle de la plantilla y, junto al nombre, podrá ver un ícono de un lápiz para editar. A continuación se muestra el contenido que debería ver:

Imagen 11. Visualización de la plantilla agregada

Haga clic en el ícono para editar y verá los campos relacionados al nombre, la información de la plantilla, su contenido y otras opciones adicionales. Edite la información del contenido para eliminar la sección "Desktop" y cambiar el nombre de la sección "Smartphone" por "Environment". Posteriormente, configure las etiquetas en la sección "Labels" para que la plantilla siempre incluya la etiqueta bug. A continuación puede ver la información de la plantilla a crear:

Imagen 12. Formulario de edición de la plantilla

Arriba de dicho contenido, en la parte derecha podrá ver un botón denominado "Propose changes". Haga clic en él para guardar los cambios. Esto le mostrará dos campos de texto para brindar información sobre los cambios realizados y efectuarlos; puede dejar la información que se muestra por defecto y hacer clic en el botón "Commit changes".

Imagen 13. Formulario para guardar los cambios

Ahora que creó una plantilla, todos los usuarios podrán hacer uso de ella al momento de reportar incidencias, siguiendo un formato que usted ha indicado. Puede comprobar que la plantilla quedó correctamente configurada y crear una incidencia de ejemplo a partir de ella. Para esto, diríjase nuevamente a la pestaña "Issues", y al momento de crear una incidencia, podrá ver la plantilla, como se muestra a continuación:

Imagen 14. Plantillas mostradas al momento de crear una incidencia

Nota: si desea crear incidencias sin formato, posteriormente deberá hacer clic en el enlace del texto "Open a blank issue".

Haga clic en el botón "Get started" correspondiente a su plantilla. Podrá ver que el mismo formulario de creación de la incidencia se ha llenado con información por defecto que corresponde a la estructura. Agregue un título a la incidencia y podrá ver la siguiente pantalla:

Imagen 15. Formulario de creación de una incidencia a partir de la plantilla

Finalmente, haga clic en el botón "Submit new issue" y podrá ver el detalle de su incidencia creada.

Bloquear la creación de incidencias

Anteriormente se mencionó que algunos repositorios podrían tener bloqueada la funcionalidad de reportar incidencias. Es posible que en algún proyecto usted no desee admitir incidencias de ningún usuario. Para esto, diríjase nuevamente a la pestaña "Settings" y en la sección con el nombre "Issues", mostrada en el apartado de incidencias de la configuración, haga clic en la casilla para desmarcarla. Esto causará que la pestaña "Issues" desaparezca de su repositorio, como se puede ver a continuación:

Imagen 16. Pestaña de configuraciones y otras pestañas del repositorio

Si lo desea, revierta los cambios volviendo a marcar la casilla correspondiente en las configuraciones para poder hacer uso de esta funcionalidad en su repositorio.

¡Felicidades!

Al completar este tutorial usted pudo familiarizarse mejor con el reporte de incidencias en un repositorio de GitHub.

Ahora maneja las funcionalidades básicas para rastrear incidencias en GitHub y será capaz de realizar un seguimiento adecuado a un proyecto de desarrollo de software apoyándose de una de las herramientas más utilizadas en el campo.

Créditos

Versión 1.0 - Mayo 30, 2020