Changelog - Registro de cambios y versionado semántico

Por Jose R. Zapata

Ultima actualización: 20/Feb/2026

¿Qué es un Changelog?

Un changelog (registro de cambios) es un archivo, generalmente llamado CHANGELOG.md, que contiene una lista cronológica y organizada de todos los cambios notables realizados en un proyecto entre cada versión o release.

A diferencia del historial de commits de Git (que registra cada cambio técnico), el changelog está pensado para ser leído por humanos o Agentes de IA: usuarios, colaboradores y stakeholders que necesitan entender rápidamente qué cambió en cada versión sin tener que revisar el código.

¿Por qué es importante mantener un Changelog?

• Comunicación clara: Informa a los agentes de IA, los usuarios y colaboradores sobre nuevas funcionalidades, correcciones y cambios importantes.
• Trazabilidad: Permite entender la evolución del proyecto versión a versión.
• Facilita las actualizaciones: Los usuarios pueden evaluar si deben actualizar y qué impacto tendrá en su uso.
• Documentación viva: Complementa la documentación técnica con un resumen ejecutivo de los cambios.

Keep a Changelog

Keep a Changelog es una convención ampliamente adoptada que define un formato estándar para escribir changelogs.

Principios Fundamentales

• Los changelogs son para humanos o Agentes de IA,
• Debe existir una entrada para cada versión.
• Los mismos tipos de cambios deben agruparse.
• Las versiones y secciones deben ser enlazables (por eso se usa Markdown).
• La versión más reciente va primero.
• Se muestra la fecha de publicación de cada versión.
• Se indica si el proyecto sigue el Versionado Semántico.

Estructura del Archivo

# Changelog

Todos los cambios notables de este proyecto se documentan en este archivo.

El formato está basado en [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
y este proyecto sigue [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added
- Nuevo endpoint para predicción batch

## [1.2.0] - 2026-02-15

### Added
- Modelo XGBoost para predicción de churn
- Pipeline de feature engineering automatizado
- Documentación de métricas del modelo

### Changed
- Mejorar rendimiento del preprocesamiento de datos en un 40%

### Fixed
- Corregir error de división por cero en cálculo de precision

## [1.1.0] - 2026-01-20

### Added
- Endpoint de health check para servicio de inferencia
- Tests de integración para pipeline de datos

### Deprecated
- Endpoint /predict/v1 será removido en v2.0.0

## [1.0.0] - 2025-12-01

### Added
- Pipeline completo de extracción, transformación y carga de datos
- Modelo baseline de clasificación
- API REST para servicio de predicción
- Documentación inicial del proyecto

Categorías de Cambios

Keep a Changelog define las siguientes categorías:

Lo que NO debe ir en un Changelog

• Cambios internos que no afectan al usuario (refactorizaciones menores, cambios de estilo de código).
• Cada commit individual (para eso está git log).
• Información duplicada que ya está en la documentación.
• Mensajes genéricos como “varias correcciones” o “mejoras de rendimiento” sin especificar cuáles.

Versionado Semántico (Semantic Versioning)

El Versionado Semántico (SemVer) es un sistema de numeración de versiones que comunica el tipo e impacto de los cambios realizados. Se usa en conjunto con el changelog para que los usuarios entiendan rápidamente la magnitud de cada release.

Formato

MAJOR.MINOR.PATCH

Ejemplo: 2.4.1

Reglas Clave

• La versión 0.y.z es para desarrollo inicial. Cualquier cosa puede cambiar en cualquier momento.
• La versión 1.0.0 define la API pública. A partir de aquí, el número de versión comunica el tipo de cambios.
• Cuando se incrementa MAJOR, MINOR y PATCH se reinician a 0 (ej. 1.4.2 → 2.0.0).
• Cuando se incrementa MINOR, PATCH se reinicia a 0 (ej. 1.4.2 → 1.5.0).

Ejemplos en Ciencia de Datos

# PATCH: corrección de bug (1.2.0 → 1.2.1)
- Corregir error en normalización de features

# MINOR: nueva funcionalidad compatible (1.2.1 → 1.3.0)
- Agregar nuevo modelo de predicción de churn
- Agregar endpoint /predict/batch

# MAJOR: cambio incompatible (1.3.0 → 2.0.0)
- Cambiar formato de entrada del modelo de CSV a Parquet
- Remover endpoint /predict/v1
- Cambiar esquema de la base de datos de features

Pre-release y Metadatos

SemVer también permite indicadores adicionales:

# Pre-release (versiones de prueba)
2.0.0-alpha.1    # Primera versión alpha
2.0.0-beta.3     # Tercera versión beta
2.0.0-rc.1       # Release candidate

# Metadatos de build (informativos, no afectan precedencia)
2.0.0+20260220   # Build con fecha
2.0.0+exp.sha.abc123  # Build experimental con hash

Buenas Prácticas

1. Mantener la Sección [Unreleased]

Registra los cambios a medida que se van integrando, no esperes al momento del release. Esto evita olvidar cambios importantes y facilita la preparación de cada versión.

2. Un Changelog por Repositorio

Cada repositorio debe tener su propio CHANGELOG.md en la raíz del proyecto.

3. Ser Consistente

Usa siempre el mismo formato, las mismas categorías y el mismo nivel de detalle. La consistencia facilita la lectura y la automatización.

4. Incluir Enlaces

Enlaza cada versión al diff correspondiente en GitHub/GitLab para que los usuarios puedan ver los cambios completos:

## [1.2.0] - 2026-02-15

### Added
- Modelo XGBoost para predicción de churn

[1.2.0]: https://github.com/usuario/proyecto/compare/v1.1.0...v1.2.0
[1.1.0]: https://github.com/usuario/proyecto/compare/v1.0.0...v1.1.0

5. Escribir para tu Audiencia

Piensa en quién lee el changelog. En un proyecto de ciencia de datos, tu audiencia puede incluir:

• Científicos de datos: Les interesa saber sobre nuevos modelos, cambios en features y métricas.
• Ingenieros de datos: Les importan cambios en pipelines, formatos de datos y dependencias.
• Stakeholders de negocio: Quieren entender el impacto funcional de los cambios.
• DevOps/MLOps: Necesitan saber sobre cambios en infraestructura, despliegue y configuración.

Changelog y Agentes de Programación con IA

Al igual que con los commits bien estructurados, el changelog es una fuente de contexto valiosa para los agentes de programación con IA.

¿Cómo usan los agentes el Changelog?

• Entender el estado del proyecto: Al leer la sección [Unreleased], el agente sabe qué cambios están en progreso y qué ya fue integrado, evitando trabajo duplicado.
• Generar Pull Requests con contexto: El agente puede referenciar versiones anteriores y explicar cómo el PR se relaciona con la evolución del proyecto.
• Detectar breaking changes: Al analizar el historial de versiones MAJOR, el agente puede advertir cuando un cambio propuesto podría romper compatibilidad.
• Mantener el changelog actualizado: Los agentes pueden agregar automáticamente entradas al changelog basándose en los commits de una rama, respetando el formato Keep a Changelog.
• Preparar releases: Pueden mover los cambios de [Unreleased] a una nueva versión, asignar el número de versión correcto según SemVer y generar los enlaces de comparación.

Herramientas Útiles

• auto-changelog: Genera changelogs automáticamente desde el historial de commits.
• commitizen: Genera changelogs y bumps de versión basados en conventional commits.
• release-please: Automatiza releases y changelogs en GitHub.
• standard-version: Versionado y changelog automático siguiendo SemVer.

Referencias

• https://keepachangelog.com/en/1.0.0/
• https://semver.org/spec/v2.0.0.html
• https://www.conventionalcommits.org
• https://commitizen-tools.github.io/commitizen/

Jose R. Zapata

• https://joserzapata.github.io/
• https://www.linkedin.com/in/jose-ricardo-zapata-gonzalez/