Notas de versión de software: qué son y qué incluir
6 min de lectura
Las notas de versión de software son el documento que acompaña a una versión y que le dice al lector qué cambió, a quién afecta y qué debe hacer, si es que debe hacer algo. Se escriben una vez por versión y las leen quienes deciden si actualizar, quienes comprueban si ya se corrigió un problema que les afectó y quienes dan soporte al producto. Las buenas son cortas, concretas para esa versión y sinceras sobre lo que se rompe.
| Tipo | Lector | Qué cubre | Dónde vive |
|---|---|---|---|
| Para clientes | Usuarios del producto | Funciones nuevas, correcciones, cambios de comportamiento | En la app, en una página de changelog, en un email |
| Para desarrolladores | Quienes llaman a tu API o SDK | Breaking changes, deprecaciones, endpoints nuevos | Documentación de la API, un changelog para desarrolladores |
| Enterprise o TI | Administradores que despliegan las actualizaciones | Problemas conocidos, requisitos del sistema, pasos de migración | Un documento de notas por versión |
| Internas | Soporte, ventas, QA | Qué se entregó, qué decir a los clientes, qué es arriesgado | Un canal interno o un wiki |
¿Qué son las notas de versión de software?
Son un resumen fechado y versionado de una sola versión. Una nota de versión responde tres preguntas para un lector que no estuvo en la sala: qué es distinto, si le afecta y si tiene que actuar. El historial completo del proyecto es el changelog, y el registro de commits es para quienes escribieron el código.
Los mismos datos pueden aparecer en una entrada del changelog y en las notas de versión. La diferencia está en la selección y la audiencia: el changelog lista todos los cambios relevantes, mientras que las notas de versión abren con los que el lector notará y los explican. Changelog vs notas de versión traza la línea con detalle.
¿Qué deben incluir las notas de versión de software?
Incluye la versión y la fecha, un resumen de un párrafo y luego los cambios agrupados según lo que el lector puede hacer con ellos. Para cada cambio, di qué es distinto en los términos del lector, a quién afecta y si hace falta alguna acción.
Un conjunto completo tiene estas partes:
- Número de versión y fecha de lanzamiento. Usa el formato de tus tags, para que el lector pueda relacionar las notas con una compilación.
- Un resumen. Dos o tres frases: para qué sirve esta versión y si actualizar exige algo al lector.
- Funciones nuevas y mejoras. Lo que el lector ya puede hacer, no lo que el código ahora contiene.
- Correcciones. El síntoma que desapareció y la versión en la que empezó.
- Breaking changes y deprecaciones. Qué deja de funcionar, cuándo y qué usar en su lugar. Ponlos primero si los hay.
- Problemas conocidos. Todo lo que se entregó y sabes que no está bien, con una solución provisional si existe.
- Requisitos y pasos de actualización. Plataformas compatibles, versiones mínimas, comandos de migración.
Deja fuera las refactorizaciones, las actualizaciones de dependencias sin efecto visible y los tickets internos. Si un lector no puede notar el cambio, su sitio es el historial de git. Cómo escribir notas de versión cubre la redacción y el orden.
¿Cómo es una nota de versión de software?
Aquí tienes una breve para una herramienta de línea de comandos inventada. Importa más la forma que el contenido.
## 2.4.0 (2026-10-08)
Exportaciones más rápidas y un breaking change en el archivo de
configuración. Actualizar requiere editar una línea de `tool.yml`.
### Breaking
- `output:` en `tool.yml` ahora es `export.path:`. Las configs
antiguas fallan con "unknown key". Renombra la clave; nada más
cambia.
### Novedades
- Las exportaciones se escriben en disco por partes, así que los
archivos de más de 100 MB ya no agotan el tiempo de espera.
### Corregido
- La búsqueda vuelve a funcionar con consultas que contienen un
guion. Fallaba desde la 2.3.0.
### Problemas conocidos
- Las rutas de Windows de más de 260 caracteres siguen fallando.
Usa un directorio de salida más corto por ahora.El breaking change va primero, con el texto exacto del error que verá el lector, porque la gente busca los mensajes de error. La corrección nombra la versión en la que se rompió, para que el lector pueda relacionarla con el momento en que empezó su problema. El problema conocido trae una solución provisional, que es mejor que el silencio. Ejemplos de notas de versión tiene más redacciones para cada tipo de entrada.
¿En qué se diferencian las notas de versión según la audiencia?
Mantén una única fuente de verdad y escribe una versión por audiencia. Los hechos no cambian, pero sí el nivel de detalle. Los clientes quieren el beneficio en una línea, los administradores quieren los requisitos y los problemas conocidos, los desarrolladores quieren nombres y versiones exactos, y soporte quiere saber qué responder cuando llegue un ticket.
En los productos con API, la versión para desarrolladores es la que exige más cuidado, porque un cambio que para ti es una corrección menor puede ser una caída para quien llama a la API. Changelog de API y breaking changes cubren a esa audiencia. Para la versión interna, notas de release internas describe lo que necesitan soporte y ventas y los clientes no.
¿Dónde se publican las notas de versión de software?
Publícalas donde el lector ya está cuando se hace la pregunta. En una app móvil, es la ficha de la tienda, donde la plataforma ofrece un campo de notas de versión para cada versión; Apple documenta cómo añadir notas de versión a las compilaciones. En un producto web, es una página de changelog enlazada desde la app. En una librería, es la página de la release y un archivo en el repositorio, como se describe en notas de release de GitHub.
Mantén cada versión en una URL estable para que soporte pueda enlazarla, y conserva las versiones antiguas. Quien está en la 2.2 necesita también las notas de la 2.3 y la 2.4. Si quieres una estructura de partida, la plantilla de notas de versión te da encabezados para copiar.
¿Qué extensión deben tener las notas de versión?
La que necesite el cambio y ni una línea más. Una versión de parche puede ser de tres líneas. Una versión mayor con migración necesita una página y, probablemente, una guía de migración aparte enlazada desde las notas. La prueba es si un lector que lee solo la primera pantalla sabe si la versión le afecta. Si no lo sabe, sube el resumen y recorta el resto. Buenas prácticas de notas de versión enumera lo que se sostiene y lo que es pura costumbre.
FAQ
¿Qué son las notas de versión de software? Son un resumen versionado de lo que cambió en una versión de un software, escrito para quienes lo usan o le dan soporte. Cubren funciones nuevas, correcciones, breaking changes y todo lo que el lector debe hacer.
¿Cuál es la diferencia entre las notas de versión y un changelog? Un changelog es el registro completo y continuo de los cambios relevantes. Las notas de versión son un mensaje sobre una sola versión, seleccionado y reescrito para lectores que deciden si actualizar. Muchos equipos publican la entrada del changelog de una versión como sus notas de versión.
¿Quién escribe las notas de versión de software? Normalmente el product manager, un redactor técnico o el ingeniero que entregó el cambio, con alguien que revise el tono. El mejor resultado llega cuando la persona más cercana al cambio hace el borrador y una segunda lo edita pensando en el lector.
¿Las versiones menores necesitan notas de versión? Sí, breves. Incluso una versión de parche debe decir qué se corrigió y si el lector tiene que actuar. Una nota de una línea es mejor que nada, porque “correcciones de errores y mejoras” no le dice nada al lector.
Las afirmaciones técnicas de este artículo no se han revisado de forma independiente. Si algo está mal, avísanos y lo corregiremos.