git-cliff — Cuando el Changelog se Escribe Solo y Tú Te Relajas
¿Recuerdas cómo al final de cada sprint o antes de un lanzamiento te sentabas pensando con temor: "¿Otra vez con el Changelog..."? Repasando commits, intentando recordar lo que realmente se hizo, y cómo formularlo para que quede claro tanto para usuarios como para compañeros. ¿Te suena familiar, verdad? Escribir un Changelog manualmente no solo es tedioso, sino que también es propenso a errores, omisiones e inconsistencias. Y después de todo, el Changelog es la cara de tu proyecto, su historial de desarrollo que ayuda a los usuarios a entender qué hay de nuevo y a los desarrolladores a rastrear los cambios.
Afortunadamente, en el mundo del código abierto existen soluciones que nos liberan de esta rutina. Hoy hablaremos de uno de estos proyectos — git-cliff. No es solo otro generador de Changelog, sino un verdadero cuchillo suizo para quienes valoran la automatización, la flexibilidad y el orden en su historial de Git.
¿Qué es git-cliff y quién lo necesita?
git-cliff es una herramienta de alto rendimiento escrita en Rust que genera automáticamente archivos Changelog basados en tu historial de commits de Git. Su característica principal es la integración profunda con el concepto de Conventional Commits, pero no te limita con marcos estrictos y te permite configurar literalmente cada aspecto de la salida.
¿A quién le será útil? Prácticamente a cualquier desarrollador o equipo que:
- Está cansado de la rutina: No más horas invertidas escribiendo Changelogs manualmente.
- Busca el orden: Quiere que su Changelog siempre esté actualizado, completo y consistente.
- Usa Conventional Commits:
git-cliffes perfecto para proyectos que siguen este estándar. - Necesita flexibilidad: ¿Los generadores estándar no encajan?
git-cliffte permite configurar todo hasta el más mínimo detalle. - Trabaja con CI/CD: La herramienta se integra fácilmente en pipelines para la generación automática de Changelogs en cada lanzamiento.
Características Clave: ¿Por Qué Amamos git-cliff?
git-cliff se distingue de otras herramientas gracias a varias características poderosas. Analicémoslas en detalle.
1. Generación Inteligente Basada en el Historial de Git
En el núcleo de git-cliff está el análisis inteligente de tu historial de Git. No solo muestra una lista de commits, sino que los agrupa por tipo (por ejemplo, feat, fix, chore), determina automáticamente las versiones, y puede incluso vincular commits a los issues o pull requests correspondientes. Esto produce no solo una lista de cambios, sino un documento significativo y estructurado.
2. Soporte Completo para Conventional Commits y Más
Si ya usas Conventional Commits (por ejemplo, feat: add new feature, fix: resolve bug), entonces git-cliff se convertirá en tu mejor amigo. Entiende esta especificación de forma nativa y la usa para categorizar los cambios. ¿Pero qué pasa si tu proyecto usa su propio formato de commit único? ¡Sin problema!
git-cliff te permite crear parsers personalizados basados en expresiones regulares. Esto significa que puedes enseñarle a entender cualquier formato de commit usado en tu proyecto. Esta es una característica increíblemente poderosa que convierte a git-cliff en una herramienta universal.
3. Flexibilidad Increíble de Plantillas y Configuración
Imagina poder controlar cada byte de la salida de tu Changelog. Con git-cliff, esto es una realidad. Puedes definir una plantilla personalizada usando sintaxis de Jinja2 para que el Changelog luzca exactamente como lo necesitas. ¿Quieres Markdown? ¿AsciiDoc? ¿JSON? Sin problema. Puedes configurar:
- Formato de títulos y subtítulos
- Agrupación de commits
- Visualización de autores
- Enlaces a issues y PRs
- ¡Y mucho más!
Toda esta magia se configura a través de un simple y claro archivo cliff.toml.
# Пример части конфигурации cliff.toml
[changelog]
body = "Full Changelog: {url}/compare/{from}...{to}"
[git]
conventional_commits = true
filter_unconventional = false
[git.commit_parsers]
# Кастомный парсер для коммитов, если Conventional Commits недостаточно
"^(?P<type>\w+)(?:\((?P<scope>.*)\))?!?:\s(?P<subject>.*)" = {
group = "{type}",
default_scope = "other"
}
[changelog.release]
format = "## {{version}} ({{timestamp | date(format='%Y-%m-%d')}})"
4. Listo para Automatización y CI/CD
git-cliff es una herramienta de línea de comandos, lo que lo convierte en un candidato ideal para integrarse en tus procesos de CI/CD. Puedes configurar GitHub Actions, GitLab CI, o cualquier otro sistema para generar Changelogs automáticamente en cada push a main o al crear una nueva etiqueta de versión. Esto asegura que tu Changelog siempre esté actualizado y no requiera intervención manual.
Detalles Técnicos: Bajo el Capó — Rust
git-cliff está escrito en Rust, lo cual en sí mismo es una gran noticia. Esto significa que la herramienta:
- Es rápida: Rust es conocido por su rendimiento, lo cual es crítico para repositorios grandes con historiales largos.
- Es confiable: El lenguaje proporciona seguridad de memoria y alta estabilidad.
- Es multiplataforma: Obtienes un único binario que funciona en todas partes, sin dependencias.
La configuración se realiza a través de un archivo cliff.toml, que permite un control muy granular sobre el comportamiento del generador. Este es el elemento central donde defines las reglas de parsing, la estructura de salida y otros parámetros.
Aplicación Práctica: ¿Cómo Funciona?
Veamos cómo git-cliff puede ayudar en el trabajo diario.
Generación Local de Changelog
La forma más sencilla de comenzar es generar un Changelog localmente. Digamos que quieres obtener un Changelog para la última versión:
git cliff --output CHANGELOG.md
Este comando analizará tu historial de Git y creará o actualizará el archivo CHANGELOG.md en la raíz de tu proyecto. Puedes especificar un rango de versiones si quieres obtener un Changelog solo para un período específico:
git cliff --tag 1.0.0 --output CHANGELOG.md
Integración en CI/CD para Lanzamientos Automáticos
Aquí es donde git-cliff realmente brilla. Puedes agregarlo a tu pipeline para que el Changelog se genere automáticamente en cada lanzamiento. Por ejemplo, en GitHub Actions podría verse así:
name: Release
on:
push:
tags:
- 'v[0-9]+.[0-9]+.[0-9]+'
jobs:
generate-changelog:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
with:
fetch-depth: 0
- name: Generate Changelog
uses: orhun/git-cliff-action@v2
with:
config: cliff.toml
output: CHANGELOG.md
args: --latest --prepend
- name: Commit and Push Changelog
run: |
git config user.name github-actions
git config user.email [email protected]
git add CHANGELOG.md
git commit -m "docs: update changelog [skip ci]"
git push
Este ejemplo muestra cómo cuando se crea una nueva etiqueta de versión, git-cliff actualiza automáticamente CHANGELOG.md, y luego los cambios se confirman y empujan al repositorio. Esto automatiza completamente el proceso, liberándote del trabajo manual.
Trabajando con Monorepositorios
git-cliff también sabe cómo trabajar con monorepositorios, lo cual es un punto doloroso común para muchos equipos. Gracias a la configuración flexible y las capacidades de filtrado de rutas, puedes generar Changelogs separados para cada subproyecto en un monorepo manteniendo la consistencia general.
Conclusión: ¿Deberías Probar git-cliff?
¡Absolutamente sí! git-cliff no es solo una herramienta, es una filosofía de orden y automatización en la gestión de lanzamientos. Resuelve un problema real que muchos desarrolladores enfrentan, ofreciendo una flexibilidad y rendimiento sin precedentes gracias a Rust.
Si tú:
- Valoras tu tiempo y quieres automatizar tareas rutinarias.
- Buscas la limpieza y consistencia en tu historial de Git y Changelog.
- Usas o planeas usar Conventional Commits.
- Buscas una herramienta confiable y rápida que se integre fácilmente en CI/CD.
Entonces git-cliff es algo que deberías probar. Te ayudará a concentrarte en escribir código en lugar de documentación, haciendo que el proceso de lanzamiento sea fluido y predecible. ¡Consulta el sitio web del proyecto y la documentación para aprender más y comenzar a usar esta excelente herramienta hoy!
Proyectos relacionados