Issues, tablero y la primera pull request

Antes de empezar. Necesitas el portfolio publicado en la sesión 1, su carpeta local y acceso a GitHub. El backend ya se ha iniciado en las sesiones 1–2 de Servidor, pero hoy practicarás el flujo de trabajo con cambios pequeños en el portfolio. Después aplicarás ese mismo método al código Java, sin repetir aquí su implementación.

Se explica

25 minutos · punto de partida, explicación y demostración

Especificación de una tarea y criterios de aceptación

Una issue es una tarea registrada en GitHub: describe qué quieres cambiar y permite seguir su estado. Sus criterios de aceptación indican cómo comprobar que has terminado. Se redactan antes de programar, para que quien revise el cambio sepa qué resultado esperar.

Descripción insuficiente

«Mejorar la cabecera». No indica qué información debe mostrar ni qué comportamiento debe tener.

Título de la issue

Añadir una cabecera con datos profesionales y enlace al repositorio.

Criterios de aceptación

La cabecera muestra tu nombre y titulación. Incluye un enlace cuyo texto es «Repositorio del portfolio». Al pulsarlo, se abre el repositorio correcto.

El alcance delimita lo que entra en la tarea. Añadir la cabecera y rehacer todas las páginas son cambios distintos: sepáralos para poder comprobar cada uno. La lista de tareas pendientes se denomina backlog; el tablero las organiza por estado.

Ramas de funcionalidad y pull requests

Una rama de funcionalidad (feature branch) permite registrar los commits de una tarea sin incorporarlos todavía a main. Git cambia los archivos de tu carpeta al cambiar de rama; no tienes que copiar el proyecto a otra carpeta. Antes de cambiar de rama, comprueba que no quedan modificaciones sin guardar en un commit.

Por ejemplo, partes del portfolio publicado en main, creas una rama para la cabecera y trabajas allí. El sitio público conserva su versión anterior hasta que integres el cambio y termine el despliegue.

Una pull request es una solicitud para integrar los cambios de una rama en otra. GitHub muestra las diferencias de código, llamadas diff, y permite añadir comentarios y revisiones. La rama base recibe el cambio; la rama compare contiene la propuesta. En esta práctica, la base siempre será main.

1. Issue: concretar el cambio
2. Rama: implementarlo y guardar commits
3. Pull request: mostrar la propuesta
4. Revisión: probarla y corregirla
5. Fusión: incorporarla a main
6. Despliegue: comprobar la URL pública

Definición de terminado

La definición de terminado (Definition of Done) reúne las condiciones comunes a todas las tareas. Los criterios de aceptación describen la cabecera concreta; esta definición describe el proceso que seguirá cualquier cambio:

1. La issue describe el resultado y la rama contiene solo los cambios necesarios.
2. La pull request enlaza la issue y explica cómo comprobar el resultado.
3. Tu pareja prueba la rama y deja una revisión; corriges lo necesario antes de fusionar.
4. Tras la fusión, compruebas que la issue se cierra y que el despliegue del portfolio termina correctamente.
5. Abres la URL pública y verificas el cambio real.

Hoy aún no hay un análisis automático del HTML en las pull requests. Lo añadirás en la sesión 3. El backend se comprueba ejecutándolo en local hasta que llegue su taller de despliegue; no necesita una URL pública para cerrar las tareas de esta semana.

Protección de la rama principal

Un conjunto de reglas (ruleset) permite a GitHub rechazar operaciones sobre una rama. Hoy exigirás una pull request para modificar main y bloquearás su borrado y los envíos forzados que reescriben el historial.

Se trabaja

140 minutos · trabajo guiado sobre el portfolio

Los tiempos son orientativos: 30 minutos para el tablero, 25 para la protección y 85 para implementar y revisar cambios. El bloque D es el procedimiento de revisión que usarás dentro del bloque C; forma parte de esos 85 minutos. El resultado esencial es una pull request completa. Si lo alcanzas antes, repite el recorrido con otra tarea.

Bloque A · Planificación en GitHub Projects y especificación de issues

1 · Define seis tareas pequeñas. Parte de lo que ya tiene tu portfolio. Puedes planificar una cabecera profesional, una presentación personal, una lista de competencias, una ficha del CRUD, enlaces de contacto y un pie de página. Si algo ya existe, describe una mejora concreta. La ficha del CRUD puede enlazar su repositorio y explicar su estado actual: todavía no hay una demo pública del backend.

2 · Crea el tablero. Desde tu perfil de GitHub, abre Projects → New project, elige Board, escribe Portfolio y confirma. Después, en la pestaña Projects del repositorio portfolio, usa Link a project para vincularlo si todavía no aparece. El tablero pertenece a tu cuenta; las issues se registran en el repositorio de GitHub y no se descargan mediante git clone.

3 · Comprueba los estados. Utiliza Todo para tareas pendientes, In Progress para la que estás realizando y Done para tareas cerradas. Las columnas muestran el campo Status. Si aparecen otros nombres, identifica o configura esos tres estados antes de continuar.

4 · Configura las automatizaciones. Una automatización (workflow) es una regla que ejecuta una acción cuando ocurre un evento. Prepararás tres: incorporar al tablero las issues que crees en portfolio, asignarles el estado pendiente y actualizar su estado cuando se cierren. Estas reglas se configuran en GitHub Projects; no necesitas crear un archivo de GitHub Actions.

Abre la configuración del proyecto. Entra en el tablero Portfolio que acabas de crear. En la esquina superior derecha del proyecto, pulsa ··· y selecciona Workflows. En la lista Default workflows encontrarás las reglas siguientes.

A · Añadir las issues al tablero

1. Selecciona Auto-add to project y pulsa Edit, arriba a la derecha.
2. En Filters, selecciona tu repositorio portfolio. Comprueba también el propietario si aparece más de un repositorio con ese nombre.
3. En el campo de filtro situado junto al repositorio, escribe is:issue is:open. La primera parte selecciona issues y la segunda exige que estén abiertas; juntas seleccionan únicamente issues abiertas.
4. Pulsa Save and turn on workflow para guardar y activar la regla.

B · Asignar el estado inicial

1. En la lista de reglas, selecciona Item added to project y pulsa Edit.
2. En la acción que establece el estado, selecciona Status → Todo. El campo Status indica en qué columna se muestra la tarjeta; Todo significa pendiente.
3. Pulsa Save and turn on workflow.

Añadir una issue al tablero y asignarle un estado son operaciones distintas. La regla A incorpora la tarjeta al proyecto y la regla B la sitúa en Todo.

C · Actualizar el estado al cerrar una issue

1. Selecciona Item closed.
2. Comprueba que la regla está activada y que su acción asigna Status → Done. Si ya está configurada así, puedes dejarla como está.
3. Si necesitas cambiarla o activarla, pulsa Edit, selecciona Done como estado de destino y guarda con Save and turn on workflow.

Esta regla actúa cuando se cierra una issue del proyecto, incluido el cierre automático al fusionar una pull request vinculada. Lo practicarás más adelante en esta sesión.

Resumen de las reglas

Activa las tres reglas antes de crear las tareas. La incorporación automática se aplica cuando una issue se crea o se actualiza y cumple el filtro. Activar la regla no incorpora por sí solo las issues que ya existían. Puedes consultar las instrucciones de GitHub sobre automatizaciones de Projects e incorporación automática.

Comprueba el resultado con la primera tarea. En el paso 5, crea la primera issue desde el repositorio portfolio y vuelve al tablero. Debe aparecer en Todo sin que la añadas ni le asignes el estado manualmente. Compruébalo antes de crear las otras cinco. Cuando completes esa tarea y se cierre su issue al fusionar la pull request, verifica que pasa a Done; mantenla abierta mientras esté pendiente.

La issue no aparece o su tarjeta no tiene estado

• No aparece: actualiza la página del tablero. Si sigue faltando, revisa en Auto-add to project el propietario y el repositorio seleccionados, el filtro is:issue is:open y que hayas guardado y activado la regla. Comprueba que la issue esté abierta.
• La creaste antes de activar la regla: añádela al proyecto mediante su enlace, como se indica en el paso 5. La activación no importa automáticamente las issues existentes.
• Aparece sin estado: revisa que Item added to project esté activado y asigne Todo. Para corregir la tarjeta ya añadida, ábrela y selecciona Todo en su campo Status; después comprueba la automatización con la siguiente issue.
• La issue está cerrada pero la tarjeta no pasa a Done: revisa Item closed. Corrige el estado de esa tarjeta manualmente y comprueba el comportamiento en el siguiente cierre.

5 · Registra las seis issues. En Issues → New issue del repositorio, escribe para cada una un título y dos o tres criterios comprobables, siguiendo el ejemplo de la explicación. Créala y observa el número que GitHub le asigna. Regresa al tablero y verifica su incorporación. Si falta una issue que creaste antes de activar el flujo, añádela mediante su enlace desde la opción de añadir elementos del tablero.

6 · Prioriza. Coloca primero la cabecera, si falta, o una mejora pequeña de esta. Reserva una segunda tarea para repetir el proceso. Deja las demás pendientes: no tienes que implementar las seis hoy.

Bloque B · Configuración de la protección de main

1 · Crea el conjunto de reglas. En el repositorio del portfolio, abre Settings → Rules → Rulesets → New ruleset → New branch ruleset y configura:

Activa Restrict deletions, Block force pushes y Require a pull request before merging, con Required approvals: 0. Mantén Require status checks to pass desactivado: aún no has creado el check de HTML. Pulsa Create y vuelve a abrir el ruleset para comprobar lo guardado.

2 · Comprueba el bloqueo con un cambio de prueba. Abre una terminal en la carpeta del portfolio y ejecuta git status. Antes de continuar, debe indicar que no hay cambios pendientes. Si los hay, termina de registrarlos en su rama; no los descartes para realizar esta prueba.

git switch main
git pull --ff-only
git switch -c prueba-proteccion-main

Añade al final del README una línea que diga «Prueba temporal de protección», guarda y ejecuta:

git add README.md
git commit -m "Comprobar proteccion de main"
git push origin HEAD:main

HEAD:main intenta enviar el commit actual directamente a la rama remota main, sin pull request. El resultado esperado es un rechazo por las reglas, por ejemplo GH013 o GH006, acompañado de un mensaje que exige una pull request. Un error de contraseña o de conexión no demuestra que la protección funcione.

Tras el rechazo, ejecuta git switch main. El commit de prueba queda conservado únicamente en la rama local prueba-proteccion-main, y tu README vuelve a la versión anterior. Puedes dejar esa rama sin utilizar; no hace falta borrar cambios ni ejecutar git reset --hard.

Si el envío directo se acepta

La protección no está funcionando como se esperaba. Revisa que el ruleset esté activo, que incluya main y que no haya excepciones en Bypass list. No repitas el envío. Actualiza tu main local con git switch main y git pull --ff-only; elimina la línea temporal mediante una nueva rama y una pull request siguiendo el bloque C. No reviertas el historial con un envío forzado.

3 · Aplica las mismas reglas al backend. En GitHub, abre el repositorio que contiene pom.xml y src/, y configura el mismo ruleset. Comprueba su nombre para no confundirlo con portfolio. A partir de las sesiones 3–4 de Servidor, sus cambios también se publican mediante ramas y pull requests. No copies el workflow de Pages al backend: una aplicación Java requiere otro despliegue, que se trabajará más adelante.

¿Qué mensaje demuestra que GitHub rechazó el envío por la protección de main?

¿Dónde ha quedado el commit de prueba después de volver a main?

¿Qué parte de la revisión sigue dependiendo de tu actuación con la configuración actual?

Bloque C · Recorrido completo de una tarea y segunda iteración

Trabaja con una pareja de revisión: cada persona desarrolla en su repositorio y revisa el de la otra. Intercambia los enlaces de los repositorios públicos. Si trabajas en un grupo de tres, cada persona revisa a la siguiente.

1 · Selecciona la issue. Asígnatela mediante Assignees y mueve su tarjeta a In Progress. Anota su número. En los ejemplos se utiliza 3: sustitúyelo por el número real en la rama y en Closes #3. GitHub comparte la numeración entre issues y pull requests, por lo que los números pueden no ser consecutivos entre tareas.

2 · Prepara la rama. En la carpeta del portfolio, comprueba con git status que no quedan cambios pendientes y ejecuta:

git switch main
git pull --ff-only
git switch -c 3-cabecera-con-nombre

-c crea la rama y cambia a ella. --ff-only actualiza main sin crear una fusión local inesperada. Si Git informa de historias divergentes, revisa los commits pendientes antes de continuar. Comprueba con git branch --show-current que estás en la rama de la tarea.

3 · Implementa y comprueba. Modifica únicamente lo acordado en la issue. En el ejemplo, agrupa el nombre, la titulación y el enlace en un header dentro del body. Conserva el resto de la página. Guarda, abre index.html en el navegador y verifica cada criterio. Si encuentras otra mejora, regístrala como tarea separada.

4 · Guarda y publica la rama. Revisa los cambios con git diff y registra los archivos modificados:

git add index.html
git commit -m "Anadir cabecera con nombre y titulacion"
git push -u origin 3-cabecera-con-nombre

Si tu tarea modifica otros archivos, añádelos también por su nombre. -u configura el seguimiento de la rama remota; los siguientes envíos de esta misma rama se realizan con git push.

5 · Abre la pull request. En GitHub, pulsa Compare & pull request o Pull requests → New pull request. Comprueba base: main y compare: tu rama. Escribe un título descriptivo y una descripción con el cambio, los pasos para probarlo y Closes #3, usando el número real. Publica la pull request y comparte su enlace con tu pareja. Si no puedes seleccionarla en Reviewers, puede acceder mediante el enlace y revisar el repositorio público.

6 · Revisa antes de fusionar. Sigue ahora el bloque D para probar la rama de tu pareja. La URL pública todavía muestra main; por eso la revisión del cambio se realiza en local. Espera también su revisión sobre tu pull request.

7 · Atiende las correcciones. Si te piden cambios, edita en la misma rama, comprueba el resultado, crea otro commit y ejecuta git push. La pull request se actualiza automáticamente; no abras otra. Solicita una nueva revisión del resultado corregido.

8 · Fusiona. Cuando la revisión confirme los criterios, elige Squash and merge en el desplegable del botón de fusión y confirma. Esta opción reúne los commits de la tarea en uno nuevo en main. Pulsa Delete branch para eliminar la rama remota ya integrada.

9 · Comprueba el resultado. La issue debe cerrarse, su tarjeta pasar a Done y Actions iniciar el despliegue. Espera a que termine y abre la URL pública. Si el despliegue falla, la tarea aún necesita atención: anota el fallo y corrígelo mediante otra pull request; que la tarjeta esté en Done no demuestra que la web funcione.

10 · Sincroniza tu copia local.

git switch main
git pull --ff-only
git branch -d 3-cabecera-con-nombre

Si Git no permite borrar la rama tras Squash and merge

El squash crea un commit nuevo, por lo que Git puede no reconocer los commits originales como integrados. Puedes conservar la rama y seguir trabajando desde main. Si quieres eliminarla, comprueba primero en GitHub que la pull request está fusionada, que no quedan commits adicionales sin publicar y que main contiene el resultado. Solo después usa git branch -D nombre-de-la-rama, sustituyendo el nombre: esta opción fuerza el borrado de esa rama local.

Bloque D · Revisión de código por pares

Este bloque se realiza cuando llegas al paso 6 del bloque C. Necesitas el enlace a la pull request de tu pareja y el nombre de su rama, que aparece en la cabecera de la solicitud.

1 · Lee la propuesta. Abre la issue enlazada y la pestaña Files changed de la pull request. Identifica qué criterios debes comprobar y qué archivos han cambiado.

2 · Descarga la rama para probarla. Desde la carpeta de tu propio portfolio, ejecuta una sola vez esta clonación, sustituyendo USUARIO-DEL-AUTOR por la cuenta de tu pareja:

cd ..
git clone https://github.com/USUARIO-DEL-AUTOR/portfolio.git portfolio-auditoria
cd portfolio-auditoria
git fetch origin
git switch 3-cabecera-con-nombre

Sustituye también el nombre de rama por el de la pull request que revisas. En las siguientes revisiones de esa persona, entra directamente en portfolio-auditoria, ejecuta git fetch origin y cambia a la rama correspondiente. Si ya la habías descargado y recibió correcciones, actualízala con git pull --ff-only.

3 · Comprueba el cambio. Abre el index.html de esa carpeta de auditoría en el navegador. Verifica nombre, titulación y destino del enlace, o los criterios de la tarea que corresponda. No modifiques el código de tu pareja en esta copia: comunica los problemas en la pull request.

4 · Registra la revisión. En Files changed → Review changes, selecciona:

Una revisión útil sería: «He abierto la rama en local. Aparecen nombre y titulación, pero el enlace lleva a otro repositorio. Debe abrir el portfolio de esta cuenta». Tras la corrección, vuelve a probar y registra la aprobación. Una frase como «todo bien» no explica la comprobación realizada.

5 · Vuelve a tu proyecto. En la terminal de auditoría, ejecuta git switch main y después cd ../portfolio. Comprueba con git remote -v que has regresado a tu repositorio antes de continuar tu tarea. Cada persona debe terminar con una revisión recibida y otra realizada.

Cierre

15 minutos · comprobación del resultado

Ver respuestas

1 · El criterio describe un resultado concreto, como el destino de un enlace. La definición de terminado establece las comprobaciones comunes a todas las tareas.

2 · En la descripción de la pull request, con el número real. La issue se cierra cuando la pull request se fusiona en la rama predeterminada; el tablero actualiza su estado si está activo el flujo correspondiente.

3 · Exige una pull request y bloquea el borrado y los envíos forzados a main. Con cero aprobaciones obligatorias, eres responsable de obtener y atender la revisión antes de fusionar.

4 · La URL pública muestra la versión ya desplegada desde main, que todavía no incluye la propuesta.

5 · El cierre de la issue, el estado del tablero, el resultado del despliegue y el funcionamiento real de la URL pública.

En la sesión 3 añadirás un check de HTML a las pull requests. La comprobación de enlaces y formato llegará en la sesión 4, y los umbrales de calidad en la 5.