# Notas de versión y changelog Convierte un conjunto de cambios integrados en lo que el lector necesita: una entrada para el registro y unas notas para quien sufre el cambio. ## Entregable Un documento Markdown, `release-notes.md`, con la estructura fijada en **Salida** más abajo. Lleva las dos formas: la sección 2 es la entrada que se añade al changelog del proyecto, y de la sección 4 en adelante es lo que se publica a los lectores. ## Entradas obligatorias - **El conjunto de cambios integrados** — los commits, fusiones o tickets incluidos en esta entrega, y el límite dentro del que caben. - **El identificador de versión** — cómo se llama esta entrega, aportado por quien nombra las versiones aquí. Nunca se inventa. - **El lector** — a quién se publican las notas: quienes ejecutan el software, quienes integran contra él, o ambos. Si falta el conjunto de cambios o el identificador de versión, detente e infórmalo. Unas notas montadas desde el recuerdo de lo que se estuvo haciendo omitirán exactamente el cambio que le rompe algo a alguien. ## Entradas opcionales - Los tickets o incidencias que cierran los cambios, y qué decían - Las notas de la entrega anterior, para mantener la terminología - Pasos de migración ya escritos por quienes hicieron el cambio - Decisiones de obsolescencia y la fecha prevista de retirada - Mediciones tomadas antes y después de un cambio de rendimiento - El canal donde se publican las notas y los límites de longitud que impone Las entradas opcionales ausentes reducen lo que las notas pueden afirmar. Sin mediciones se describe el cambio pero nunca se llama más rápido; sin fecha de retirada una obsolescencia se registra como prevista con `desconocido` al lado. ## Ejecución **1 — Tomar el conjunto de cambios del registro, no del recuerdo.** Lista cada cambio integrado dentro del límite. Cada entrada de la salida se traza hasta uno de ellos, y un cambio que llega a la salida sin nada detrás se elimina. **2 — Ordenar por lo que es.** Añadido, cambiado, corregido, eliminado, seguridad. Ordena por el efecto sobre el lector y no por el componente que se tocó: el lector busca qué le ha pasado a él, no en qué módulo ocurrió. **3 — Separar lo visible de lo interno.** Un cambio que el lector puede observar va a las notas. Una refactorización, una prueba o un cambio de compilación se registra como interno y se queda fuera de la sección del lector. Disfrazar un cambio interno de mejora visible es como unas notas de versión pierden a sus lectores. **4 — Subir los cambios incompatibles al principio.** Todo lo que deja de funcionar, cambia de forma o exige una acción va arriba del todo, con la acción detallada. Un paso de migración enterrado bajo una lista de novedades es un paso de migración que se va a pasar por alto. **5 — Escribir cada entrada como su efecto.** Declara qué es distinto para el lector y qué debe hacer al respecto, no qué función se editó. Cuando una entrada tenga un ticket o un cambio detrás, cítalo para que el lector pueda llegar más lejos. **6 — Afirmar solo lo que se midió.** Un cambio solo se puede llamar más rápido, más pequeño o más fiable si hay una medición detrás. Sin ella, describe qué cambió y deja el juicio al lector. **7 — Registrar las obsolescencias y lo que viene.** Qué queda obsoleto, qué lo sustituye y cuándo se retirará — `desconocido` donde no se haya decidido una fecha. Después contrasta cada entrada con el conjunto de cambios una última vez. ## Salida `release-notes.md`, en este orden: - **1. Identidad de la entrega** — el identificador tal como se aportó, la fecha y el límite del conjunto de cambios - **2. Entrada de changelog** — agrupada en `Añadido`, `Cambiado`, `Corregido`, `Eliminado`, `Seguridad`; una línea por cambio, cada una citando de dónde sale - **3. Cambios internos** — cambios sin efecto visible para el lector, registrados y fuera de la sección 4 - **4. Cambios incompatibles y acción necesaria** — qué deja de funcionar y los pasos exactos a dar; vacía solo si no hay ninguno, y lo declara - **5. Novedades** — por entrada: el efecto sobre el lector y qué puede hacer ahora - **6. Correcciones** — el síntoma que el lector habría visto, y que ya no está - **7. Obsolescencias** — qué queda obsoleto, su sustituto y la fecha de retirada o `desconocido` - **8. Afirmaciones sin verificar** — todo lo afirmado sin una medición ni un cambio trazable, listado en lugar de publicado ## Validación El documento está listo cuando se cumple todo esto: - Cada entrada de las secciones 2 y 4 a 7 se traza hasta un cambio del conjunto de entrada - Cada cambio del conjunto de entrada aparece una vez, en la sección 2 o en la 3 - La sección 4 va antes de la 5 y enuncia sus pasos como acciones que el lector ejecuta - Ninguna entrada afirma una mejora medible sin una medición aportada - El identificador de la sección 1 es el que se aportó, sin cambios - La sección 3 se usa para el trabajo interno en lugar de dejarlo fuera Falla la ejecución si una entrada de la salida no se traza a ningún cambio de la entrada, o si se afirma una mejora sin medición detrás. ## Gestión de fallos - **Sin conjunto de cambios** — detente. Informa de que unas notas de versión no se reconstruyen a partir de lo que la gente recuerda haber hecho. - **Sin identificador de versión** — produce el documento con la sección 1 marcada como `VERSIÓN SIN ASIGNAR` y nombra a quién le toca asignarla. No inventes un identificador ni incrementes el anterior. - **El efecto de un cambio sobre el lector no está claro** — lístalo en la sección 8 con la pregunta y pregúntale a quien lo hizo. No lo describas en vago para rellenar una línea. - **Un cambio incompatible sin ruta de migración** — regístralo en la sección 4, declara con claridad que no hay migración disponible y elévalo como bloqueante de la entrega. Un cambio incompatible sin ruta es una decisión, no una nota. - **Conjunto de cambios parcial** — produce el documento para el rango conocido, declara el límite en la sección 1 y márcalo como `INCOMPLETO — cubre solo `.