Issues, tablero y la primera pull request

Antes de empezar. Con el portfolio publicado y el backend en desarrollo en Servidor, en esta sesión aprenderás a planificar requisitos técnicos mediante tareas (issues), estructurar el desarrollo mediante ramas de funcionalidad y validar los cambios a través de revisiones formales de código (code review) en pull requests.

---

Se explica

25 minutos · fundamentación metodológica y demostración técnica

Especificación de requisitos: estructura de una issue y criterios de aceptación

En ingeniería de software, la gestión eficaz de un proyecto depende de formular tareas con un alcance preciso y comprobable. Una tarea ambigua carece de valor operativo si no define con exactitud las condiciones que certifican su conclusión:

Formulación informal o ambigua

«Mejorar la cabecera», «Estilos generales», «Añadir proyectos», «Revisar detalles pendientes».

Especificación técnica como issue

«Añadir cabecera accesible con datos personales, titulación y enlace al repositorio». «Publicar sección de proyectos con ficha descriptiva del servicio CRUD y enlace a la demo».

Criterio diferencial

La especificación técnica define un alcance acotado y observable. Cualquier evaluador o miembro del equipo puede contrastar el resultado de forma independiente sin requerir aclaraciones adicionales del autor.

Cada issue técnica debe estructurarse atendiendo a tres directrices:

Ramas de funcionalidad (Feature Branches) en Git

Rama de funcionalidad (Feature branch)

En Git, una rama no es una duplicación física de archivos, sino una referencia ligera y móvil (un puntero de 41 bytes) hacia un commit específico dentro del grafo de historial (DAG). Al derivar una rama a partir de main, se crea una línea de desarrollo aislada que preserva intacta la versión de producción.

El desarrollo basado en ramas de funcionalidad (Feature Branch Workflow) aporta tres ventajas críticas:

• Aislamiento y estabilidad del entorno productivo: Cualquier cambio en curso, fallo temporal o refactorización permanece encapsulado sin alterar la versión estable publicada en main.
• Independencia y no bloqueo entre tareas: Si surge una corrección prioritaria o una tarea queda temporalmente bloqueada, es posible alternar a otra rama limpia derivada de main sin mezclar código incompleto.
• Trazabilidad semántica y auditoría: Cada rama vinculada a una issue convierte el historial de Git en una secuencia estructurada de aportaciones lógicas, facilitando el análisis retrospectivo y el mantenimiento.

Pull Request

Una solicitud formal de integración de una rama secundaria en la rama principal. No es una simple operación de fusión: constituye un espacio colaborativo y auditable donde se exponen las diferencias de código (diff), se ejecutan los pipelines de integración continua y se documenta la discusión técnica y la aprobación entre pares antes de autorizar la incorporación definitiva.

Definición de terminado (Definition of Done)

Definición de terminado (Definition of Done - DoD)

El conjunto explícito de condiciones de calidad que cualquier incremento de software debe satisfacer rigurosamente antes de ser considerado apto para producción. En este módulo se establecen cinco condiciones innegociables:

1. El desarrollo reside en una rama de funcionalidad identificada con el número de su issue correspondiente.
2. Se ha canalizado mediante una pull request que vincula formalmente el cierre de la tarea.
3. Todas las comprobaciones automáticas del pipeline de CI concluyen con estado favorable (verde).
4. Se cuenta con la aprobación formal de al menos un revisor por pares tras la inspección del código.
5. El cambio se encuentra efectivamente desplegado y operativo en la URL del entorno de producción.

La evaluación se focaliza en el cumplimiento de estas garantías metodológicas del ciclo de vida del software, con independencia de la complejidad visual del frontend en esta etapa inicial.

Gobernanza y protección de la rama principal (Branch Protection)

En desarrollo profesional, la integridad de la rama principal no se delega en la memoria o en acuerdos informales: se garantiza mediante directivas técnicas de la plataforma (Branch Rulesets).

Al activar la protección de main se aseguran tres garantías críticas:

1. Imposibilidad de alteración no auditada: Ninguna modificación puede incorporarse sin haber pasado por una pull request con su correspondiente revisión.
2. Inmutabilidad y preservación de la historia: Se bloquea la reescritura del historial (git push --force) y el borrado de la rama, protegiendo las evidencias temporales del proyecto.
3. Puerta de enlace para validación continua (CI): Establece la infraestructura técnica necesaria para supeditar la fusión a la superación de análisis de calidad y pruebas automatizadas (incorporados en la sesión 3).

---

Se trabaja

140 minutos · trabajo guiado sobre el proyecto base

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

Trabajo individual · Definición del alcance y backlog inicial

0 · Formulación preliminar de requisitos. Antes de abrir la plataforma, redacta de forma sintética seis requisitos funcionales que compondrán las primeras versiones de tu portfolio profesional (por ejemplo: cabecera semántica con datos personales, sección de proyectos vinculada al servicio backend de Servidor, listado de competencias técnicas o enlaces a perfiles profesionales). Cada requisito debe constituir una unidad de entrega independiente.

1 · Arquitectura de datos de GitHub Projects.

Tablero (GitHub Projects)

Una herramienta de gestión y seguimiento basada en metodologías ágiles (Kanban) que actúa como una capa de visualización sobre las tareas del repositorio. Es fundamental distinguir que los datos (las issues) residen en el repositorio Git; el tablero proporciona una vista estructurada según el ciclo de vida de cada elemento. Al ser una entidad asociada a la cuenta u organización, un mismo tablero puede sincronizar y proyectar tareas procedentes de múltiples repositorios.

2 · Creación y vinculación del tablero.

1. En la interfaz del repositorio, accede a la pestaña Projects.
2. Selecciona Link a project y, en el menú inferior desplegable, pulsa New project.
3. En el asistente de selección de plantillas, escoge la modalidad Board (visualización Kanban por columnas).
4. Asigna como nombre Portfolio y confirma mediante Create.

3 · Estructura de estados del ciclo de trabajo. El tablero se inicializa con tres columnas predeterminadas: Todo (pendiente), In Progress (en desarrollo) y Done (completado y verificado). Estas columnas representan los posibles valores del campo de estado (Status), permitiendo monitorizar visualmente el flujo de entrega de cada tarea.

4 · Automatización de transiciones de estado. Para sincronizar automáticamente el tablero con la actividad de Git: accede al menú de configuración del tablero (··· superior derecho) → Workflows y configura:

Límites de automatización en cuentas estándar de GitHub

Las cuentas individuales permiten un automatismo de adición automática por tablero. Esta restricción cubre adecuadamente las necesidades del portfolio. Cuando se integre el repositorio del backend en unidades posteriores, se valorará la creación de un tablero de coordinación global o la asignación de flujos específicos.

5 · Registro formal de issues en el repositorio. Accede a la pestaña Issues del repositorio y pulsa New issue. Registra cada uno de los seis requisitos planificados siguiendo la estructura estándar:

Ejemplo de especificación de issue:

Título

Añadir cabecera semántica con datos profesionales

Descripción y criterios de aceptación

Se muestra en la zona superior del documento el nombre completo, titulación académica y un hipervínculo funcional al repositorio de GitHub configurado para abrirse en una nueva pestaña (target="_blank" rel="noopener noreferrer").

6 · Priorización en el tablero. Regresa al tablero de Projects. Las seis issues deben figurar automáticamente en la columna Todo. Reordena las tarjetas verticalmente situando en primer lugar las dos tareas prioritarias que abordarás en esta sesión.

Bloque B · Configuración de directivas de protección en la rama principal

Procedimiento guiado · Implantación de políticas de gobernanza en Git

Las políticas de protección que se configuran a continuación en el repositorio del portfolio deben replicarse igualmente en el repositorio del backend desarrollado en Servidor, asegurando un estándar homogéneo de calidad.

1 · Definición del conjunto de reglas (Branch Ruleset). En GitHub, accede a Settings → Rules → Rulesets → New ruleset → New branch ruleset.

2 · Configuración de directivas de seguridad. Activa estrictamente las siguientes directivas:

Repositorios con despliegue en Azure Static Web Apps

Si se completó el bloque opcional de Azure en la sesión 1, el workflow generado por dicha plataforma ya incluye el evento pull_request. Una vez ejecutada la primera pull request del bloque C, su job de comprobación podrá ser seleccionado dentro de las comprobaciones requeridas del ruleset.

3 · Activación de la directiva. Pulsa Create para persistir el conjunto de reglas.

4 · Verificación técnica del bloqueo en el entorno local. Comprueba empíricamente que la política de protección rechaza los intentos de subida directa a la rama principal:

git switch main
git pull
echo "prueba de proteccion" >> README.md
git commit -am "Verificar politica de proteccion en main"
git push

El servidor remoto de GitHub debe rechazar la operación con un error de protección de rama (GH006: Protected branch hook declined). Una vez constatado el rechazo, descarta el commit local y sincroniza el espacio de trabajo con el estado remoto:

git reset --hard origin/main

¿Cuál es el código de error y mensaje exacto devuelto por GitHub al rechazar el push?

¿Por qué el servidor rechaza la operación incluso tratándose del propietario del repositorio?

Bloque C · Recorrido completo del flujo de integración, dos veces

Práctica individual con revisión cruzada por pares

Organización para la revisión por pares (Peer Code Review). Trabaja en pareja estable durante el módulo: la revisión cruzada de código audita la calidad técnica y simula la dinámica de un equipo de desarrollo profesional; la trazabilidad de estas revisiones en GitHub forma parte de las evidencias evaluables. Intercambia con tu pareja el enlace al repositorio público para habilitar la inspección en local durante el Bloque D. En caso de número impar, se establece una rotación circular donde cada participante revisa al siguiente.

Sigue con atención el protocolo completo de diez pasos en la primera iteración. En la segunda, aplica el flujo asegurando cada comprobación técnica.

1 · Selección y asignación de la tarea. En el tablero del proyecto, selecciona la primera issue de la columna Todo. Desplázala a In Progress y asígnatela en el campo Assignees para reflejar la autoría. Anota el identificador numérico de la issue (por ejemplo, #3).

2 · Creación de la rama de característica (feature branch). El nombre de la rama debe incorporar como prefijo el número de la issue correspondiente para garantizar la trazabilidad entre el gestor de tareas y el historial de Git:

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

Ejecuta siempre esta secuencia estricta: sitúate en main, descarga la última versión sincronizada desde el remoto con git pull y bifurca la rama a partir de dicho estado. El modificador -c (abreviatura de create) instruye a git switch para crear la rama y cambiar el puntero activo a ella en una única operación. Verifica mediante git status o en la barra de estado del editor que te encuentras en la nueva rama antes de realizar cualquier modificación.

3 · Desarrollo atómico. Implementa con precisión técnica exclusivamente lo estipulado en los criterios de aceptación de la issue. Si identificas anomalías secundarias o posibles mejoras accesorias, no las incorpores en este cambio: regístralas como nuevas issues en el tablero para mantener la atomicidad del cambio.

4 · Confirmación y publicación en el remoto. Registra los ficheros modificados y redacta un mensaje de confirmación descriptivo en modo imperativo:

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

El argumento -u (equivalente a --set-upstream) vincula la rama local con la rama homónima en el repositorio remoto origin. Este enlace de seguimiento sólo debe configurarse en la primera publicación; en envíos sucesivos sobre esta rama, bastará ejecutar git push.

5 · Apertura de la pull request. Tras el empuje, la interfaz de GitHub mostrará la sugerencia Compare & pull request. Si no se visualiza, navega a la pestaña Pull requests → New pull request, seleccionando base main y compare 3-cabecera-con-nombre.

6 · Notificación y solicitud de revisión. Proporciona a tu evaluador el enlace directo a la pull request. En flujos de trabajo sin despliegues efímeros automáticos, el código en revisión reside únicamente en la rama remota de GitHub y la producción continúa sirviendo la rama main; el revisor deberá sincronizar la rama en su entorno local para inspeccionarla (procedimiento detallado en el Bloque D).

Despliegues de previsualización efímeros (Preview Deployments)

En plataformas de alojamiento avanzadas (o entornos como Azure Static Web Apps o Vercel), la apertura de una pull request desencadena un pipeline CI/CD que aprovisiona una URL de previsualización temporal. Dicho entorno efímero se destruye automáticamente al cerrar o fusionar la PR, permitiendo la verificación funcional sin descargas locales previas.

7 · Ejecución de la revisión por pares. Tu evaluador ejecuta el protocolo de inspección del Bloque D sobre la solicitud. De forma paralela, procede a auditar la suya.

8 · Fusión mediante Squash and merge. Tras obtener la aprobación formal en la revisión, pulsa Merge pull request. Selecciona rigurosamente la estrategia Squash and merge: esta operación condensa la totalidad de confirmaciones de la rama de característica en una única confirmación atómica en main, preservando un historial lineal, legible y bisectable en la rama principal. A continuación, pulsa Delete branch para depurar la referencia remota ya integrada.

9 · Verificación de efectos secundarios automáticos. Inspecciona que se desencadenen los cuatro eventos sistémicos esperados:

10 · Limpieza y sincronización local. Antes de iniciar una nueva iteración de desarrollo, restablece el entorno local:

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

Segunda iteración: ejecuta el ciclo completo para una nueva issue

Bloque D · Auditoría técnica y revisión de código (Code Review)

Actividad colaborativa: auditoría cruzada de solicitudes de incorporación

La revisión de código por pares (Peer Code Review) constituye un filtro de calidad esencial en el ciclo de vida del software, cuyo propósito es garantizar el cumplimiento de los requisitos técnicos, evitar la propagación de defectos a ramas productivas y fomentar la transferencia de conocimiento entre miembros del equipo.

Descarga y verificación en el entorno local. Si el repositorio no dispone de entornos de despliegue efímeros con URL de previsualización, es imperativo inspeccionar el artefacto en local. En la primera ocasión, clona el repositorio del autor en un directorio independiente ajeno a tu espacio de trabajo principal:

cd ..
git clone https://github.com/USUARIO-DEL-AUTOR/portfolio.git portfolio-auditoria
cd portfolio-auditoria

Posteriormente, para inspeccionar cualquier rama sometida a revisión, sincroniza las referencias remotas y conmuta a la rama indicada en la pull request:

git fetch origin
git switch 3-cabecera-con-nombre

Abre a continuación el fichero index.html en el navegador web local para contrastar visualmente el comportamiento frente a los criterios de aceptación. Una vez finalizada la verificación, regresa a la rama principal con git switch main.

Durante la auditoría de una pull request se evalúan sistemáticamente tres dimensiones técnicas:

Aprobación deficiente

«Revisado y conforme 👍»

Petición formal de modificaciones (Request changes)

«El criterio de aceptación exige que el enlace externo se abra en una nueva pestaña mediante target="_blank" y rel="noopener". La implementación actual navega en el mismo contexto. Se requieren cambios.»

Aprobación técnica documentada (Approve)

«Rama 3-cabecera-con-nombre descargada y validada en local. La cabecera semántica incorpora correctamente la identidad y la titulación académica requeridas. Criterios de aceptación satisfechos.»

Criterio diferenciador

Una revisión profesional explicita qué elementos técnicos han sido auditados y valida el cumplimiento de las condiciones pactadas, aportando valor al ciclo de entrega.

Emisión formal del veredicto. En la pestaña Files changed, selecciona el botón Review changes situado en el extremo superior derecho:

---

Cierre

15 minutos · comprobación del resultado

Soluciones de autoevaluación

1 · Carece de criterios de aceptación verificables: sin una definición precisa del estado final esperado, la tarea no es estimable ni auditable en una revisión de código.

2 · Se ubica en el cuerpo de la pull request e instruye al motor de GitHub para clausurar automáticamente la issue correspondiente y transicionar su estado a Done una vez formalizada la fusión.

3 · Porque la regla Require status checks to pass no puede activarse hasta disponer de un pipeline de CI (integración continua) que valide las pull requests. La integridad actual del código recae exclusivamente en la auditoría humana.

4 · Garantiza que la nueva rama derive del último estado estable desplegado en producción, evitando arrastrar confirmaciones espurias de ramas de trabajo precedentes.

5 · git fetch origin para actualizar el catálogo de ramas remotas y git switch nombre-de-rama para posicionar el entorno local en dicha rama antes de examinarla en el navegador.