Cuando trabajamos en proyectos de software, uno de los ficheros más útiles para el equipo y para los usuarios es el changelog o registro de cambios. En él deberíamos documentar cómo evoluciona el proyecto, qué se añade, qué se corrige y qué se elimina en cada versión.
Existen muchas formas de estructurar este archivo, pero uno de los estándares más extendidos y utilizados es Keep a Changelog, que define un conjunto reducido de categorías oficiales. Además de otras categorías no oficiales pero muy comunes que se utilizan para dar más detalle o adaptarse a las necesidades de cada equipo.
En esta guía te presento todas ellas, tanto en inglés como su equivalente en castellano para aquellos que quieren mantener el archivo en castellano, con definiciones claras y ejemplos prácticos de cuándo usarlas. No vamos a justificar por qué seguir un estándar: nos centraremos en qué categorías existen, qué significan y cómo aplicarlas de forma consistente.
Tabla de contenidos
Categorías oficiales de Keep a Changelog
El estándar Keep a Changelog define seis categorías principales. Estas son las únicas oficiales, y si quieres mantener un changelog simple y universalmente entendible, son las que deberías utilizar siempre.
Added (Añadido)
Los cambios en los que se debe usar esta categoría son:
- Para cualquier cosa nueva que se incorpora al proyecto.
- No solo se refiere a grandes funcionalidades, sino también a detalles más pequeños: nuevos parámetros de configuración, nuevas APIs, nuevos mensajes de log, nuevas opciones de comandos, etc.
Por ejemplo:
### Added - Added `--verbose` option to the `deploy` command. - Added support for PostgreSQL 16. ### Añadido - Se añadió la opción `--verbose` al comando `deploy`. - Se añadió soporte para PostgreSQL 16.
Changed (Cambiado o Modificado)
Esta categoría se puede usar para los siguientes tipos de cambios:
- Cuando algo que ya existía cambia de comportamiento.
- Puede ser un cambio en la API, en la interfaz de usuario, en la lógica de negocio o en la forma en que se calculan los resultados.
Algunos ejemplos se muestran a continuación:
### Changed - Changed default timeout from 30s to 60s. - Changed password validation rules. ### Cambiado - Se modificó el tiempo de espera por defecto de 30s a 60s. - Se modificaron las reglas de validación de contraseñas.
Deprecated (Obsoleto o En desuso)
La categoría Deprecated se puede utilizar en las siguientes situaciones:
- Cuando algo aún existe, pero ya no se recomienda usarlo.
- Es una advertencia al usuario: “funciona hoy, pero en el futuro desaparecerá”.
- Muy útil para dar tiempo a migrar hacia alternativas.
Por ejemplo, en los siguientes casos:
### Deprecated - Deprecated support for Python 3.8 (will be removed in the next major release). - Deprecated `legacy_mode` configuration option. ### Obsoleto - Se marcó como obsoleto el soporte para Python 3.8 (se eliminará en la próxima versión principal). - Se declaró obsoleta la opción de configuración `legacy_mode`.
Removed (Eliminado)
Los cambios en los que se puede usar esta categoría son:
- Cuando algo que existía ya no está disponible.
- Puede ser una función, un endpoint, una opción de configuración, un campo en la base de datos, etc.
Algunos ejemplos de cambios en los que se puede utilizar esta etiqueta son:
### Removed - Removed `legacy_mode` option (deprecated in v1.4.0). - Removed support for Internet Explorer 11. ### Eliminado - Se eliminó la opción `legacy_mode` (obsoleta desde la versión 1.4.0). - Se eliminó el soporte para Internet Explorer 11.
Fixed (Corregido)
La categoría Fixed se aplica a los cambios que corrigen errores, es decir, para los siguientes casos:
- Para documentar errores o bugs solucionados.
- Lo más común en cualquier changelog.
Algunos posibles ejemplos de esta categoría son:
### Fixed - Fixed crash when uploading large files. - Fixed incorrect calculation of interest rates. ### Corregido - Se corrigió un fallo que provocaba un cierre al subir archivos grandes. - Se corrigió un error en el cálculo de las tasas de interés.
Security (Seguridad)
Los casos en los que se debe usar esta categoría para etiquetar un cambio son:
- Para cambios relacionados con la seguridad.
- Puede ser un parche de vulnerabilidad, una mejora en las políticas de cifrado, o el endurecimiento de la autenticación.
Algunos ejemplos de este tipo de mensajes son los que se muestra a continuación:
### Security - Patched SQL injection vulnerability in user login. - Upgraded OpenSSL to 3.0.11 for critical security fixes. ### Seguridad - Se corrigió una vulnerabilidad de inyección SQL en el login de usuarios. - Se actualizó OpenSSL a la versión 3.0.11 para solucionar fallos críticos de seguridad.
Resumen de las oficiales
En la siguiente tabla se muestra un resumen de las categorías oficiales del estándar Keep a Changelog y sus principales casos de uso:
| Inglés | Castellano | Uso principal |
|---|---|---|
| Added | Añadido | Algo nuevo incorporado |
| Changed | Cambiado/Modificado | Algo existente que cambia |
| Deprecated | Obsoleto/En desuso | Aún existe pero se desaconseja |
| Removed | Eliminado | Algo que ya no está disponible |
| Fixed | Corregido | Errores o bugs solucionados |
| Security | Seguridad | Cambios de seguridad y vulnerabilidades |
Categorías no oficiales pero comunes
Aunque las anteriores son las únicas definidas por el estándar, en la práctica muchos equipos utilizan otras categorías para ser más expresivos. No son oficiales, pero están muy extendidas y pueden ayudarte a organizar mejor tu changelog.
Features (Novedades o Nuevas funcionalidades)
Esta categoría suele emplearse para etiquetar grandes cambios en la aplicación. Algunos de las situaciones en las que se puede usar son:
- Para destacar funcionalidades grandes y visibles para el usuario.
- Diferencia clave con Added: Features es de nivel alto (lo que el cliente nota), Added es más granular (lo que el desarrollador añade).
Por ejemplo, algunos cambios que se pueden incluir en esta categoría son:
### Features - Introduced a new dashboard for administrators. - Added support for exporting reports in PDF. ### Novedades - Nueva interfaz de panel para administradores. - Nueva opción de exportar informes en PDF.
Improved (Mejorado)
Cuando se incluyen una mejora incremental que no cambia el comportamiento se puede recurrir a esta categoría. Así se puede emplear en los siguientes casos:
- Para mejoras incrementales que no son exactamente un cambio (Changed) ni una corrección (Fixed).
- Ejemplos: rendimiento, usabilidad, claridad de mensajes.
Por ejemplo:
### Improved - Improved caching mechanism for faster response times. - Improved error messages during login. ### Mejorado - Se mejoró el mecanismo de caché para tiempos de respuesta más rápidos. - Se mejoraron los mensajes de error durante el inicio de sesión.
Docs (Documentación)
En el estándar oficial no existe una categoría para documentación, por eso es habitual que se use esta cuando existen cambios que solo afectan a la documentación. Por ejemplo:
### Docs - Updated API usage examples. - Added migration guide for version 2.0. ### Documentación - Se actualizaron los ejemplos de uso de la API. - Se añadió la guía de migración para la versión 2.0.
Refactored (Refactorizado)
Tampoco existe una etiqueta en el estándar para cuando solo se produce una refactorización del código. Por eso la existencia de esta categoría no oficial. El caso en el que se puede usar es:
- Para cambios en el código interno que no alteran la funcionalidad.
Por ejemplo:
### Refactored - Refactored user authentication module for clarity. - Simplified database connection handling. ### Refactorizado - Se refactorizó el módulo de autenticación de usuarios para mayor claridad. - Se simplificó la gestión de la conexión a la base de datos.
Performance (Rendimiento)
Esta categoría se puede usar para indicar mejoras específicas en la velocidad o eficiencia. Por ejemplo:
### Performance - Reduced memory usage by 30%. - Optimized SQL queries for report generation. ### Rendimiento - Se redujo el uso de memoria en un 30%. - Se optimizaron las consultas SQL para la generación de informes.
Tests (Pruebas)
Esta categoría se puede usar cuando:
- Para cambios relacionados con los tests automatizados o manuales.
Algunos posibles mensajes a incluir en esta categoría pueden ser:
### Tests - Added unit tests for the new billing module. - Improved integration tests for API endpoints. ### Pruebas - Se añadieron pruebas unitarias para el nuevo módulo de facturación. - Se mejoraron las pruebas de integración de los endpoints de la API.
Build (Compilación)
Una categoría que se puede usar para:
- Para cambios en el proceso de compilación o dependencias.
Por ejemplo:
### Build - Updated Node.js to version 20. - Migrated build system from Webpack to Vite. ### Compilación - Se actualizó Node.js a la versión 20. - Se migró el sistema de compilación de Webpack a Vite.
CI (Integración continua)
Esta categoría se puede usar en los mensajes:
- Para cambios en pipelines, workflows, o configuraciones de CI/CD.
Como los ejemplos que se muestran a continuación:
### CI - Added GitHub Actions workflow for linting. - Updated pipeline to run tests in parallel. ### Integración continua - Se añadió un workflow de GitHub Actions para el linting. - Se actualizó el pipeline para ejecutar pruebas en paralelo.
Misc (Varios o Miscelánea)
Finalmente, también hay equipos que usan esta categoría para cambios menores que no encajan en otra categoría. Por ejemplo:
### Misc - Updated project logo. - Corrected typos in UI labels. ### Varios - Se actualizó el logotipo del proyecto. - Se corrigieron errores tipográficos en etiquetas de la interfaz.
Resumen de las categorías no oficiales
Al igual que en el caso de las categorías oficiales, en la siguiente tabla se muestra un resumen de las categorías no oficiales que se pueden emplear y su principal caso de uso:
| Inglés | Castellano | Uso principal |
|---|---|---|
| Features | Novedades | Funcionalidades grandes, visibles para el usuario |
| Improved | Mejorado | Mejoras incrementales |
| Docs | Documentación | Cambios en docs |
| Refactored | Refactorizado | Cambios internos en el código |
| Performance | Rendimiento | Mejoras de velocidad o eficiencia |
| Tests | Pruebas | Cambios en tests |
| Build | Compilación | Cambios en dependencias o scripts de build |
| CI | Integración continua | Cambios en pipelines o workflows |
| Misc | Varios | Cambios menores o misceláneos |
Conclusiones
En esta entrada, se han repasado las categorías oficiales del estándar Keep a Changelog y algunas de las no oficiales. Lo que la convierte en una guía útil para estandarizar los mensajes en los equipos. En resumen, se ha visto:
- Las categorías oficiales de Keep a Changelog (Added, Changed, Deprecated, Removed, Fixed, Security) son suficientes para un changelog claro y universal.
- Las categorías no oficiales son útiles para dar más matices, sobre todo en proyectos grandes o con equipos distribuidos.
Entre las categorías es importante resaltar una la existencia de una distinción clave entreFeatures y Added:
Features → lo que el usuario nota (nivel alto).
- Added → lo que el desarrollador añade (nivel bajo).
Con esta guía tienes un mapa completo de todas las categorías habituales en changelogs, tanto en inglés como en castellano. Ahora puedes elegir cuáles usar en tu proyecto y mantener un registro de cambios claro, coherente y útil para todos.
Nota: La imagen de este artículo fue generada utilizando un modelo de inteligencia artificial.
Deja una respuesta