Antes de empezar. El portfolio supera ya las comprobaciones del pipeline. En esta sesión se cierra una versión identificada y se verifica si una persona ajena al proyecto es capaz de comprenderlo y utilizarlo.
Evaluación inicial · sin apuntes
- Una persona accede a tu repositorio sin conocer el proyecto. ¿Cuánto tiempo necesita para determinar qué es y verlo en funcionamiento?
- El portfolio actual y el de dentro de dos meses serán distintos. ¿Mediante qué mecanismo se identifica de forma inequívoca el estado de hoy?
- Si hubiera que acreditar dieciocho horas de trabajo distribuidas en seis semanas, ¿qué evidencias lo demostrarían?
Se explica
25 minutos · explicación conceptual y demostración técnica
El README como punto de entrada del repositorio
A un repositorio público acceden dos perfiles de visitante: quien evalúa el uso del proyecto y quien evalúa profesionalmente a su autor. Ambos consultan el mismo documento, le dedican menos de un minuto y abandonan si en ese intervalo no identifican qué están consultando.
README de ejercicio académico
«Proyecto de la primera evaluación del módulo de Proyecto Intermodular. Alumno: … Curso: 2.º DAW.» Está redactado para el docente, que ya dispone de esa información. Para cualquier otro lector carece de contenido informativo.
README de producto profesional
Qué es el proyecto, enlace a la versión en funcionamiento, con qué tecnologías está construido y cómo se publica. Está redactado para quien no conoce ni el proyecto ni a su autor y decide en menos de un minuto si continúa la lectura.
La estructura acordada consta de seis apartados. Un documento extenso no cumple su función, porque no se lee.
| Apartado | Contenido | Defecto habitual |
|---|---|---|
| Título y descripción | Qué es el proyecto, en una línea y sin adjetivación | Consignar el nombre del módulo en lugar del proyecto |
| Enlace a la versión publicada | La URL pública, en posición destacada | Situarlo al final del documento u omitirlo |
| Captura | Una imagen de la interfaz real | Omitirla, lo que obliga a abrir el enlace para valorar el proyecto |
| Arquitectura y tecnologías | Relación breve y verificable de lo empleado | Ampliar la relación con tecnologías de uso marginal |
| Procedimiento de despliegue | Qué lo desencadena, qué proceso lo ejecuta y cuál es el destino | Redactarlo presuponiendo conocimiento previo del repositorio |
| Validaciones del pipeline | Las cuatro comprobaciones, con una frase cada una | Omitirlo, con la consiguiente pérdida del elemento más diferenciador |
El apartado con mayor valor diferencial
El último. Un sitio web personal es un producto habitual en cualquier promoción; un repositorio en el que cada cambio ha superado una pull request que impedía la fusión ante marcado inválido, enlaces no resolubles o una puntuación de accesibilidad inferior a 90 constituye una evidencia metodológica infrecuente. Esa información no es deducible desde el exterior del repositorio: debe documentarse de forma explícita.
La versión como referencia inmutable
Etiqueta (tag)
Referencia asignada a un commit determinado. A diferencia de una rama, que avanza conforme se incorporan nuevos commits, una etiqueta es inmutable: v1.0.0 identifica hoy y de forma indefinida el mismo estado del proyecto.
Release
Publicación de una etiqueta acompañada de un título y unas notas que describen su contenido. La etiqueta es una referencia del sistema de control de versiones; la release es el documento dirigido a las personas.
Sin un esquema de versionado, la única forma de referirse a un estado del proyecto consiste en una referencia temporal imprecisa o en el identificador hexadecimal de un commit. El versionado permite afirmar que una demostración concreta correspondió a la versión 1.0 y recuperar ese estado de forma exacta.
Versionado semántico
El esquema empleado es el versionado semántico (Semantic Versioning 2.0.0), convención adoptada de forma generalizada en la distribución de software.
- Estructura
MAYOR.MENOR.PARCHE, por ejemplo1.4.2. Cada posición responde a un criterio distinto y su incremento transmite información al consumidor del software.- Incremento del parche
- Corrección de un defecto sin incorporación de funcionalidad: un enlace no resoluble, un contraste insuficiente, una errata. De
1.0.0a1.0.1. - Incremento de la versión menor
- Incorporación de funcionalidad nueva que mantiene la compatibilidad con la anterior. Una sección adicional del portfolio: de
1.0.1a1.1.0. - Incremento de la versión mayor
- Modificación incompatible con la versión precedente (breaking change). Es una situación infrecuente en un sitio estático, pero habitual en el diseño de la API de la segunda evaluación.
- Reinicio de las posiciones inferiores
- Al incrementar una posición, las situadas a su derecha se restablecen a cero: de
1.4.2, al añadir una sección, se pasa a1.5.0y no a1.5.2.
La versión que se publica en esta sesión es la 1.0.0, y no porque el desarrollo haya concluido, sino porque el producto satisface íntegramente el alcance comprometido. Un proyecto que nunca alcanza la versión 1.0 refleja la ausencia de una decisión sobre su alcance.
Criterios de auditoría del rastro de desarrollo
Los criterios de evaluación de diciembre son públicos, dado que corresponden a la aplicación de la definición de terminado de la UD1 sobre seis semanas de trabajo.
- Distribución temporalCommits y pull requests repartidos entre las semanas del periodo, sin concentración en fechas próximas a la entrega.
- TrazabilidadCada pull request referencia la issue que resuelve, y cada issue se cierra desde la pull request correspondiente.
- ControlesNinguna fusión con comprobaciones en estado fallido y ningún commit directo sobre la rama principal.
- RevisiónRevisiones propias registradas en el repositorio de la pareja asignada, con indicación de qué se verificó.
- CierreUna versión publicada con notas comprensibles sin acceso al código fuente.
La sesión incluye la auditoría de ese rastro en un repositorio ajeno, procedimiento que constituye la forma más eficaz de aprender a evaluar el propio.
Se trabaja
140 minutos · trabajo práctico guiado sobre el proyecto base
Bloque A · Redacción del README
Trabajo individual: issue, rama y pull request
1 · Issue. «Escribir el README del portfolio», con el siguiente criterio de aceptación: una persona que desconoce el proyecto comprende qué es, accede a la versión en funcionamiento y deduce cómo se publica, sin formular ninguna consulta.
2 · Captura. Antes de redactar, genera una captura del portfolio en su estado actual y almacénala en el repositorio, por ejemplo en docs/portada.png. Controla su peso: el job de calidad de la UD2 penaliza los recursos de tamaño desproporcionado.
3 · Redacción de los seis apartados. Sin contenido de relleno y sin fórmulas de disculpa. Expresiones como «es un proyecto sencillo hecho para clase» degradan la percepción del trabajo y esa valoración corresponde a quien lee.
Redacción del apartado de despliegue para un lector externo
Formulación insuficiente: «Se ejecuta el workflow de despliegue», que no aporta información a quien desconoce el repositorio. Formulación adecuada: «Cada cambio incorporado a main se publica de forma automática en GitHub Pages mediante GitHub Actions. Con anterioridad a su incorporación, cada pull request debe superar cuatro comprobaciones automáticas y la revisión de otra persona». Dos frases permiten comprender el procedimiento completo sin consultar ningún archivo.
4 · Insignias de estado. Una línea situada bajo el título que refleja en tiempo real el resultado del pipeline:
No constituye un elemento decorativo: es el primer indicador que consulta un lector con criterio técnico.
5 · Pull request, revisión y fusión. Conforme al procedimiento establecido. La revisión de la pareja asignada resulta aquí especialmente pertinente, dado que corresponde exactamente al perfil de lector para el que se redacta el documento: solicítale que identifique qué apartados no ha comprendido.
Lista de verificación del bloque A
- Los seis apartados, en el orden establecido y sin apartados adicionales.
- La URL pública visible sin necesidad de desplazamiento vertical.
- La captura se renderiza correctamente en el repositorio y su ruta resuelve.
- La pareja de revisión ha identificado los apartados no comprendidos y se han corregido.
Bloque B · Publicación de la versión 1.0.0
Trabajo individual, desde main actualizada
1 · Creación de la etiqueta. Se asigna sobre main, con el README ya fusionado:
git switch main
git pull
git tag -a v1.0.0 -m "Primera version publica del portfolio"
git push origin v1.0.0La opción -a genera una etiqueta anotada, que constituye un objeto propio del repositorio con autoría, fecha y mensaje, frente a la etiqueta ligera, que es únicamente un puntero. El envío de la etiqueta requiere una instrucción específica: git push sin argumentos no transfiere las etiquetas al repositorio remoto.
2 · Creación de la release. En GitHub: pestaña Releases → Draft a new release → en Choose a tag, selecciona v1.0.0 → título v1.0.0 · Portfolio publicado.
3 · Redacción de las notas. La opción Generate release notes produce un borrador a partir de las pull requests fusionadas. Ese borrador constituye material de partida, no el documento final: sobre él se redactan tres o cuatro líneas que respondan al criterio que interesa a quien consulta una release, esto es, qué permite hacer esta versión que la anterior no permitía.
Notas generadas automáticamente
«Merge pull request #12 from usuario/12-seccion-proyectos». La información es exacta, pero solo resulta interpretable para quien participó en el desarrollo.
Notas redactadas
«Primera versión pública. Portfolio con presentación, proyectos y contacto, publicado automáticamente en cada cambio. Toda incorporación supera cuatro comprobaciones: validez del marcado, disponibilidad de los enlaces, formato y una puntuación mínima de accesibilidad de 90.»
4 · Publicación mediante Publish release, y verificación de que la versión figura en la portada del repositorio.
Bloque C · Auditoría por pares del repositorio
Por parejas, cada persona sobre el repositorio de la otra
El objeto de esta auditoría no es una pull request concreta, sino seis semanas de desarrollo en conjunto. Recorre el repositorio de tu pareja conforme a la siguiente relación de criterios y registra la evidencia concreta, no la valoración general.
| Criterio | Ubicación de la evidencia | Dato que se registra |
|---|---|---|
| Distribución temporal | Pestaña Insights → Commits, o el listado de pull requests con sus fechas | Número de semanas distintas con actividad registrada |
| Trazabilidad | Cada pull request cerrada | Cuántas referencian la issue que resuelven y cuántas no |
| Cumplimiento de los controles | Historial de main |
Existencia de commits que no procedan de una fusión |
| Calidad del README | Lectura del documento sin conocimiento previo del proyecto | Qué apartados resultan incomprensibles, con la cita literal |
| Release | Pestaña Releases | Si las notas resultan interpretables sin acceso al código |
Procedimiento de comunicación de los hallazgos. Mediante la apertura de issues en el repositorio auditado. La condición de colaborador no es necesaria: el repositorio es público. Se abre una issue por hallazgo, con el formato establecido para las propias, esto es, título con verbo en infinitivo y cuerpo con la descripción de lo observado y su ubicación.
Naturaleza de una auditoría técnica
Una auditoría no consiste en un inventario de defectos. Se registran las incidencias susceptibles de corrección y también los elementos correctamente resueltos, dado que quien recibe el informe necesita conocer qué debe conservar. Un informe que únicamente consigna deficiencias se interpreta como una descalificación y se desatiende en su totalidad; un informe que no consigna ninguna evidencia el auditor no ha realizado la revisión.
- Semanas distintas con actividad en el repositorio auditado
- Pull requests sin issue asociada
- Apartados no comprendidos del README, con la cita literal
- El elemento mejor resuelto del repositorio auditado, y su fundamento
Bloque D · Respuesta a la auditoría recibida
Trabajo individual, sobre el repositorio propio
El repositorio propio contiene ahora issues abiertas por una persona externa al desarrollo. Es la primera vez que se produce esta situación y corresponde exactamente a la dinámica de un entorno profesional.
- Lee la totalidad de las issues antes de responder a ninguna.
- Las aceptadas se incorporan al tablero y se resuelven conforme al flujo de integración establecido.
- Las no aceptadas se cierran acompañadas de un comentario que motive la decisión. «No procede» no constituye una respuesta; «la captura ocupa 800 KB de forma deliberada porque el presupuesto de calidad no penaliza ese peso y la nitidez de la imagen es relevante en este contexto» sí lo es.
- Si se han incorporado correcciones, publica la versión
v1.0.1repitiendo el procedimiento del bloque B. Se trata de un incremento de parche: corrección sin funcionalidad nueva.
v1.0.0 publicada con notas redactadas, y la auditoría del repositorio de la pareja completada con sus issues abiertas.v1.0.1.Cierre
15 minutos · comprobación del resultado
Trabajo esperado de la unidad
- README de seis apartados, incorporado mediante pull request y revisado.
v1.0.0etiquetada y publicada como release, con notas de elaboración propia.- Una auditoría completada sobre el repositorio de la pareja asignada, con sus issues correspondientes.
- La totalidad de las issues recibidas, atendidas.
- El primer proyecto de la evaluación, cerrado.
Autoevaluación conceptual · sin consulta de apuntes
- ¿A qué destinatario se dirige un README y qué apartado aporta mayor valor diferencial?
- ¿Qué diferencia existe entre una etiqueta y una rama?
- Se ha corregido un enlace no resoluble. ¿Qué versión corresponde publicar?
- Se ha incorporado una sección nueva sobre la versión
1.2.3. ¿Qué versión corresponde publicar? - ¿Por qué es posible abrir una issue en el repositorio de otra persona sin ser colaborador?
- ¿Qué procedimiento corresponde ante una issue de la auditoría con la que no se coincide?
Ver respuestas
1 · A una persona que no conoce el proyecto ni a su autor. El apartado de mayor valor diferencial es el de las validaciones del pipeline, por tratarse de una evidencia metodológica infrecuente.
2 · La rama avanza conforme se incorporan commits; la etiqueta identifica un commit determinado y es inmutable.
3 · Un incremento de parche: 1.0.1. Corrección sin funcionalidad nueva.
4 · 1.3.0. Se incrementa la versión menor y la posición del parche se restablece a cero.
5 · Porque el repositorio es público. La escritura sobre el código requiere permisos; la apertura de una issue, no.
6 · Se cierra acompañada de un comentario que motive la decisión. El cierre sin justificación no es un procedimiento admisible.
Antes de la sesión 7
- El portfolio dispone de una release publicada y de un README validado por la pareja de revisión.
- Las issues de la auditoría están cerradas, resueltas o motivadas.
- Una propuesta escrita sobre qué datos gestionará el CRUD del segundo proyecto: en la sesión 7 comienza su desarrollo y el flujo de integración pasa a aplicarse sin explicación previa.