Cómo escribir un registro de cambios (y notas de la versión) que los clientes lean
El mes pasado publicaste una docena de cosas. Tu registro de cambios dice «Corrección de errores y mejoras de rendimiento».
Los clientes que esperaban una de esas correcciones no tienen ni idea de que ya llegó. El cliente potencial que te compara con la competencia ve un producto que parece no haberse movido desde la primavera.
Así se escribe un registro de cambios que la gente lea de verdad. Escribe para el cliente, no para quien fusionó el código. Pon fecha a cada entrada. Agrupa los cambios en Novedades, Mejoras y Correcciones. Abre cada entrada con lo que alguien puede hacer ahora, añade una línea sobre por qué importa e indica dónde encontrarlo. Deja fuera todo lo que un cliente no puede ver y todo lo que aún no está en producción. Después, publica con un ritmo constante, aunque algunas semanas sean cortas.
Eso es casi todo. El resto de esta entrada es una plantilla, una serie de ejemplos malos y buenos y una rutina para pasar de los PR fusionados a las notas publicadas sin que se te coma el viernes.
Registro de cambios frente a notas de la versión: ¿cuál es la diferencia?
La gente usa las dos expresiones indistintamente, pero en realidad hay dos públicos.
Un registro de cambios para desarrolladores suele ser un CHANGELOG.md en el repositorio. Es para quienes se integran con tu API, tu SDK o tu biblioteca. Les importan los números de versión, los cambios incompatibles y las funciones obsoletas. Keep a Changelog es la referencia estándar aquí y sus convenciones son sensatas: lo más reciente primero, una sección por versión, cambios agrupados como Added, Changed, Deprecated, Removed, Fixed y Security, y una sección «Unreleased» arriba para el trabajo que está fusionado pero no publicado.
Las notas de la versión (o «novedades del producto», o una página pública de registro de cambios) son para los clientes que usan el producto. No les importa que hayas subido la versión de una dependencia. Quieren saber qué pueden hacer ahora que no podían hacer la semana pasada.
Si gestionas un producto SaaS, probablemente necesites más el segundo que el primero. Muchos equipos necesitan ambos, y no pasa nada: una misma lista de trabajo fusionado puede alimentar dos textos. Simplemente no publiques la versión para desarrolladores y la llames notas de la versión.
Una plantilla de notas de la versión que puedes copiar
Sirve para una actualización semanal o quincenal del producto, en una página de registro de cambios, en un widget dentro de la app o como correo.
## 6 October 2026
### New
**[What you can now do, in plain words]**
[One or two sentences: what it does and who it's for.]
Find it in **[Page > Section]**. [Link to help article]
### Improved
**[The thing that got better]**
[What's different from before, in terms the customer notices:
faster, fewer clicks, works on mobile, handles bigger files.]
### Fixed
- [Symptom the customer saw], now fixed.
- [Symptom the customer saw], now fixed.
### Heads up (only if needed)
**[Anything changing or going away]**
[What's happening, when, and what they need to do.]
Unas cuantas reglas que hacen que funcione:
- Los títulos describen el resultado, no el nombre de la función. «Exporta informes grandes sin que se agote el tiempo» es mejor que «Exportación CSV asíncrona».
- Las correcciones describen el síntoma. Los clientes recuerdan «los totales salían desfasados un día», no «la gestión de zonas horarias en el trabajo de agregación».
- Enlaza al artículo de ayuda de todo lo nuevo. El registro de cambios dice que algo existe y el artículo dice cómo usarlo. Si no has escrito uno, nuestra guía sobre cómo escribir artículos de centro de ayuda también incluye una plantilla para eso.
- Abre con el cambio que le importará a más gente, aunque no fuera el más difícil de construir.
Entradas de registro de cambios malas y buenas
El fallo más común es pegar mensajes de commit. Así se ve:
v2.14.0
- feat(export): csv async job
- fix: tz bug in reports
- refactor billing svc
- bump deps
- misc improvements
Todo lo que hay ahí es cierto. Nada de eso le sirve a un cliente. Dos entradas son ruido interno, una no significa nada («misc improvements») y los dos cambios reales están escritos para quien revisó el PR.
Esta es la misma versión, reescrita:
6 October
NEW: Big CSV exports run in the background
Exports over 10,000 rows no longer time out. Start the export
and we'll email you a link when the file is ready.
Find it in Reports > Export.
FIXED: Report dates now match your timezone
Daily totals were splitting at midnight UTC instead of your
local midnight, so some days looked short. They're correct now,
including for past reports.
Dos entradas en lugar de cinco. Cada una dice qué cambió, por qué le debería importar al lector y dónde mirar. La refactorización y la subida de dependencias han desaparecido porque ningún cliente las notará.
Unos cuantos pares más, porque el patrón tarda en convertirse en hábito:
| Mala | Buena |
|---|---|
| Añadido SSO | Inicia sesión con Okta o Google Workspace. Los administradores pueden activarlo en Ajustes > Seguridad. |
| Rendimiento mejorado | El panel carga mucho más rápido en cuentas grandes. Los proyectos con miles de elementos ya no se atascan en la primera carga. |
| Corregido un error de notificaciones | Ya no recibirás correos duplicados cuando alguien te mencione dos veces en un mismo comentario. |
| Endpoints v1 obsoletos | La API v1 dejará de funcionar el 1 de marzo. Pasa a la v2 antes de esa fecha. Esto es lo que cambia. |
Fíjate en que «mucho más rápido» es vago. Si tienes una cifra real que hayas medido, úsala. Si no, describe la experiencia en lugar de inventarte un porcentaje.
Cómo escribir un registro de cambios a partir de PR fusionados
La mayoría de los equipos no tiene problemas con la redacción. Los tiene con acordarse de lo que se publicó. Esta es una rutina que se sostiene.
1. Reúne. Lista todo lo fusionado desde la última entrada. Con la CLI de GitHub:
gh pr list --state merged \
--search "merged:>=2026-10-27" \
--json number,title,labels,mergedAt,url \
--limit 100
2. Filtra. Para cada PR hazte dos preguntas. ¿Puede un cliente ver o notar esto? ¿Está realmente en producción para él? Las refactorizaciones internas, los cambios de CI y las correcciones de pruebas se descartan. También lo que esté detrás de un flag de funcionalidad que no se haya activado. Anunciar trabajo al que los clientes todavía no pueden acceder es peor que no anunciarlo, porque recibirás tickets de «¿dónde está?».
3. Agrupa. Clasifica lo que queda en Novedades, Mejoras y Correcciones. Varios PR pequeños suelen sumar una sola entrada («Edición en bloque» podrían ser cuatro PR).
4. Reescribe. Convierte cada grupo en una entrada con la plantilla. Primero el beneficio, palabras sencillas, dónde encontrarlo.
5. Publica y enlaza. Publícalo, enlaza cada función nueva a su artículo de ayuda y compártelo donde tus clientes lo vean.
El truco que hace mucho más fácil el paso 4 es pedir la frase de cara al cliente en el momento del PR, mientras el autor aún recuerda lo que construyó. Añade una sección a .github/pull_request_template.md:
## Customer-facing change
<!-- One sentence a customer would understand, or "None". -->
<!-- e.g. "You can now export reports over 10,000 rows." -->
- [ ] Behind a feature flag (don't announce until it's on)
- [ ] Help articles checked
Esa última casilla importa. Cada cambio publicado que toca la interfaz puede dejar desactualizado un artículo de ayuda, y el registro de cambios es un buen momento para detectarlo. Tratamos ese aspecto en cómo mantener la documentación al día.
¿Con qué frecuencia debes publicar novedades del producto?
Ajústate a tu ritmo de publicación, dentro de lo razonable. Si publicas de forma continua, un resumen semanal o quincenal se lee mejor que una entrada por despliegue. Si publicas una vez al mes, publica una vez al mes.
Más importante que la frecuencia es la constancia. Un registro de cambios con tres entradas en enero y nada desde entonces les dice a los visitantes algo que probablemente no querías decir. Una semana corta no pasa nada. «Dos correcciones esta semana, una versión más grande la próxima» es mejor que el silencio.
Los grandes lanzamientos merecen más que una línea en el registro de cambios: un anuncio en condiciones, un correo, quizá un vídeo corto. El registro de cambios es el historial continuo, no todo el plan de marketing.
Dónde poner tu registro de cambios
- Una página pública en
/changelogo/updates. Buena para clientes potenciales y para el posicionamiento en buscadores. - Dentro de la app, como un enlace o widget de «Novedades». Es donde de verdad lo ven los usuarios actuales.
- Por correo, como resumen mensual para quienes lo hayan solicitado.
- En el repositorio, como
CHANGELOG.md, si hay desarrolladores que se integran contigo.
Herramientas específicas como Beamer, Headway, LaunchNotes o el registro de cambios de Canny gestionan bien la parte del widget y del correo. Muchos equipos simplemente usan una página en su sitio de documentación. La herramienta importa menos que el hábito.
Dónde encaja Ellie Docs
Aviso: es un problema para el que hemos construido algo. Ellie Docs vigila tus PR fusionados y redacta entradas de registro de cambios a partir de ellos, escritas para los clientes y no para los revisores. Retiene las entradas del trabajo sin publicar o protegido por un flag, para que no anuncies cosas que la gente no puede usar. Tú editas, descartas o publicas cada entrada. Nada sale por sí solo.

Como además mantiene tu centro de ayuda, el mismo PR que produce una entrada de registro de cambios produce una sugerencia de actualización para cualquier artículo que haya quedado desactualizado, mostrada como un diff que aceptas o descartas.

Si tu registro de cambios es ahora mismo una lista de títulos de commits, o no se ha tocado desde el lanzamiento, ese es el hueco que cubre. Si prefieres escribirlo a mano, la plantilla y la lista de comprobación de PR de arriba te llevarán la mayor parte del camino.
Algunas preguntas habituales
¿Debe un registro de cambios incluir correcciones de errores? Sí, las que los clientes notaron. La corrección de un error que alguien reportó es una de las cosas más leídas que puedes publicar, sobre todo si se lo dices a la persona que lo reportó. Omite las correcciones de cosas que nadie fuera del equipo llegó a ver.
¿Necesito números de versión? Para una API, un SDK o cualquier cosa que se instale, sí, y sigue el versionado semántico para que la gente pueda juzgar el riesgo de un vistazo. Para una aplicación web que se despliega de forma continua, las fechas son más claras. Los clientes no piensan en versiones.
¿Qué extensión debe tener una entrada del registro de cambios? Un título en negrita más de una a tres frases. Si necesitas más, escribe un artículo de ayuda o una entrada de blog y enlázala.
¿Quieres que redacten tu registro de cambios a partir de los PR que ya has fusionado? Prueba Ellie Docs gratis. Hay un plan gratuito y no hace falta tarjeta.