Por qué un changelog bien escrito vale oro
El changelog es la primera cosa que mira un dev cuando algo se rompió tras un update. Si tu changelog dice "varios bugfixes y mejoras", el dev tiene que leer cada commit para entender qué cambió. Si dice "Fixed: race condition en creación de usuarios con mismo email", el dev sabe en 2 segundos si tu fix afecta su caso. Esa diferencia de tiempo, multiplicada por miles de usuarios, es valor real.
El estándar Keep a Changelog (keepachangelog.com) define seis categorías: Added, Changed, Deprecated, Removed, Fixed, Security. Mantener esa nomenclatura permite parsear changelogs automáticamente: GitHub Releases, Dependabot y herramientas de upgrade pueden extraer breaking changes y vulnerabilidades sin que el humano los marque manualmente.
Combiná Keep a Changelog con Semantic Versioning: versiones MAJOR.MINOR.PATCH cambian según el tipo de entrada. Si agregás un Removed o un Changed que rompe API, MAJOR sube. Si solo agregás Added retrocompatible, MINOR sube. Si solo hay Fixed, PATCH sube. Esa relación entre changelog y versión hace que automatizaciones tipo semantic-release calculen versiones desde commits sin intervención humana.
Cómo escribir entradas de changelog que sirvan
Regla #1: siempre desde la perspectiva del usuario, no del dev. "Refactor del módulo de auth" no le dice nada al usuario. "Login ahora soporta Google y Microsoft" sí. El usuario no necesita saber cómo lo hiciste, solo qué cambió en su experiencia. Si el cambio es solo interno y no tiene impacto observable, probablemente no merece entrada en changelog público.
Regla #2: incluir contexto suficiente para que un dev externo entienda el impacto. "Fixed: bug en checkout" es inútil. "Fixed: pérdida de carrito al cambiar de moneda durante checkout en Safari iOS" permite a un dev externo verificar si su sistema tenía ese bug específico. Mencioná navegador, OS, versión, condiciones específicas cuando son relevantes.
Regla #3: linkear a issues, PRs o commits cuando aporta valor. Vue.js, React y VS Code linkean cada entrada a su PR/issue. Eso permite ver el código exacto del cambio. Para changelog interno (empresa), podés linkear a Jira o Linear. Para open source público, GitHub references. La trazabilidad genera confianza en los releases.
Errores típicos en changelogs reales
Error #1: changelog generado solo por commits sin curación. Herramientas como conventional-changelog generan automáticamente desde commits, pero si tus commits son "fix typo", "wip", "ggg", el changelog resulta basura. La generación automática solo sirve si tu equipo ya escribe commits descriptivos siguiendo Conventional Commits.
Error #2: mezclar versiones en una sola entrada. "Versión 2.0-2.5: muchos cambios..." no sirve a nadie. Cada release debería tener su sección clara con fecha y versión. Si tu changelog tiene 6 meses sin update, perdiste el hábito y los cambios ya no son rastreables. Un changelog requiere disciplina por release, no batch al final.
Error #3: poner cambios internos como si fueran públicos. "Updated internal logger" no le importa al usuario externo a menos que cambie su comportamiento. Si tu librería tiene API pública y privada, separá changelog público (lo que afecta integradores) de changelog interno (refactors, deps internas). Stripe, Twilio y Atlassian tienen este split: público vs interno.
Automatización: changelog desde commits
Si tu equipo sigue Conventional Commits (feat:, fix:, docs:, etc.), podés automatizar el changelog con semantic-release, release-please (Google) o changesets (popular en monorepos). Estas herramientas leen commits desde el último tag, los categorizan, calculan la próxima versión y generan changelog formato Keep a Changelog automáticamente.
El flujo típico: dev hace PR con commit "feat(auth): add Google OAuth", merge a main dispara CI, semantic-release detecta el feat: y bumpea MINOR, genera entrada en CHANGELOG.md, crea tag git y release en GitHub. Todo sin intervención manual. Next.js, Prisma y Vercel SDK usan este flujo en producción.
Para proyectos donde la curación humana importa (productos consumer, no librerías), changesets permite que cada PR agregue manualmente entrada de changelog en archivo .md aparte. Cuando se hace release, las entradas se mergean. Esto da control sobre el lenguaje (perspectiva usuario, no commit técnico) y evita que cambios menores ensucien el changelog público. shadcn/ui y tRPC usan changesets exitosamente.