Mantenga un changelog

No dejes que tus amigos usen el registro de git en los changelogs.

Versión 1.0.0
# Changelog
All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [1.0.0] - 2017-06-20
### Added
- New visual identity by [@tylerfortune8](https://github.com/tylerfortune8).
- Version navigation.
- Links to latest released version in previous versions.
- "Why keep a changelog?" section.
- "Who needs a changelog?" section.
- "How do I make a changelog?" section.
- "Frequently Asked Questions" section.
- New "Guiding Principles" sub-section to "How do I make a changelog?".
- Simplified and Traditional Chinese translations from [@tianshuo](https://github.com/tianshuo).
- German translation from [@mpbzh](https://github.com/mpbzh) & [@Art4](https://github.com/Art4).
- Italian translation from [@azkidenz](https://github.com/azkidenz).
- Swedish translation from [@magol](https://github.com/magol).
- Turkish translation from [@karalamalar](https://github.com/karalamalar).
- French translation from [@zapashcanon](https://github.com/zapashcanon).
- Brazilian Portugese translation from [@Webysther](https://github.com/Webysther).
- Polish translation from [@amielucha](https://github.com/amielucha) & [@m-aciek](https://github.com/m-aciek).
- Russian translation from [@aishek](https://github.com/aishek).
- Czech translation from [@h4vry](https://github.com/h4vry).
- Slovak translation from [@jkostolansky](https://github.com/jkostolansky).
- Korean translation from [@pierceh89](https://github.com/pierceh89).
- Croatian translation from [@porx](https://github.com/porx).
- Persian translation from [@Hameds](https://github.com/Hameds).
- Ukrainian translation from [@osadchyi-s](https://github.com/osadchyi-s).

### Changed
- Start using "changelog" over "change log" since it's the common usage.
- Start versioning based on the current English version at 0.3.0 to help
translation authors keep things up-to-date.
- Rewrite "What makes unicorns cry?" section.
- Rewrite "Ignoring Deprecations" sub-section to clarify the ideal
  scenario.
- Improve "Commit log diffs" sub-section to further argument against
  them.
- Merge "Why can’t people just use a git log diff?" with "Commit log
  diffs"
- Fix typos in Simplified Chinese and Traditional Chinese translations.
- Fix typos in Brazilian Portuguese translation.
- Fix typos in Turkish translation.
- Fix typos in Czech translation.
- Fix typos in Swedish translation.
- Improve phrasing in French translation.
- Fix phrasing and spelling in German translation.

### Removed
- Section about "changelog" vs "CHANGELOG".

## [0.3.0] - 2015-12-03
### Added
- RU translation from [@aishek](https://github.com/aishek).
- pt-BR translation from [@tallesl](https://github.com/tallesl).
- es-ES translation from [@ZeliosAriex](https://github.com/ZeliosAriex).

## [0.2.0] - 2015-10-06
### Changed
- Remove exclusionary mentions of "open source" since this project can
benefit both "open" and "closed" source projects equally.

## [0.1.0] - 2015-10-06
### Added
- Answer "Should you ever rewrite a change log?".

### Changed
- Improve argument against commit logs.
- Start following [SemVer](https://semver.org) properly.

## [0.0.8] - 2015-02-17
### Changed
- Update year to match in every README example.
- Reluctantly stop making fun of Brits only, since most of the world
  writes dates in a strange way.

### Fixed
- Fix typos in recent README changes.
- Update outdated unreleased diff link.

## [0.0.7] - 2015-02-16
### Added
- Link, and make it obvious that date format is ISO 8601.

### Changed
- Clarified the section on "Is there a standard change log format?".

### Fixed
- Fix Markdown links to tag comparison URL with footnote-style links.

## [0.0.6] - 2014-12-12
### Added
- README section on "yanked" releases.

## [0.0.5] - 2014-08-09
### Added
- Markdown links to version tags on release headings.
- Unreleased section to gather unreleased changes and encourage note
keeping prior to releases.

## [0.0.4] - 2014-08-09
### Added
- Better explanation of the difference between the file ("CHANGELOG")
and its function "the change log".

### Changed
- Refer to a "change log" instead of a "CHANGELOG" throughout the site
to differentiate between the file and the purpose of the file — the
logging of changes.

### Removed
- Remove empty sections from CHANGELOG, they occupy too much space and
create too much noise in the file. People will have to assume that the
missing sections were intentionally left out because they contained no
notable changes.

## [0.0.3] - 2014-08-09
### Added
- "Why should I care?" section mentioning The Changelog podcast.

## [0.0.2] - 2014-07-10
### Added
- Explanation of the recommended reverse chronological release ordering.

## [0.0.1] - 2014-05-31
### Added
- This CHANGELOG file to hopefully serve as an evolving example of a
  standardized open source project CHANGELOG.
- CNAME file to enable GitHub Pages custom domain
- README now contains answers to common questions about CHANGELOGs
- Good examples and basic guidelines, including proper date formatting.
- Counter-examples: "What makes unicorns cry?"

[Unreleased]: https://github.com/olivierlacan/keep-a-changelog/compare/v1.0.0...HEAD
[1.0.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.3.0...v1.0.0
[0.3.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.2.0...v0.3.0
[0.2.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.1.0...v0.2.0
[0.1.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.8...v0.1.0
[0.0.8]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.7...v0.0.8
[0.0.7]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.6...v0.0.7
[0.0.6]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.5...v0.0.6
[0.0.5]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.4...v0.0.5
[0.0.4]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.3...v0.0.4
[0.0.3]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.2...v0.0.3
[0.0.2]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.1...v0.0.2
[0.0.1]: https://github.com/olivierlacan/keep-a-changelog/releases/tag/v0.0.1

¿Qué es un registro de cambios (changelog)?

Un registro de cambios, «changelog» de ahora en adelante, es un archivo que contiene una lista cronológicamente ordenada de los cambios más destacables para cada versión de un proyecto.

¿Por qué mantener un changelog?

Para facilitar a los usuarios y colaboradores ver exactamente qué cambios reseñables se han realizados entre cada versión del proyecto.

¿Quién necesita un changelog?

Las personas. Ya sean consumidores o desarrolladores, los usuarios finales del software son seres humanos a los que le importa lo que hay en el software. Cuando el software cambia, la gente quiere saber el porqué y el cómo.

¿Cómo hago un buen changelog?

Directrices

  • Están hechos para los seres humanos, no para las máquinas.
  • Debe haber una entrada para cada versión.
  • Los mismos tipos de cambios deben ser agrupados.
  • Versiones y secciones deben ser enlazables.
  • La última versión va primero.
  • Debe mostrar la fecha de publicación de cada versión.
  • Indicar si el proyecto sigue el Versionamiento Semántico.

Tipos de cambios

  • Added para funcionalidades nuevas.
  • Changed para los cambios en las funcionalidades existentes.
  • Deprecated para indicar que una característica o funcionalidad está obsoleta y que se eliminará en las próximas versiones.
  • Removed para las características en desuso que se eliminaron en esta versión.
  • Fixed para corrección de errores.
  • Security en caso de vulnerabilidades.

¿Cómo puedo minimizar el esfuerzo requerido para mantener el changelog?

Mantén una sección con el nombre Unreleased para hacer un seguimiento sobre los próximos cambios.

Esto nos puede servir para dos cosas:

  • La gente puede ver qué cambios podrían esperar en los próximos lanzamientos.
  • Al lanzar una nueva versión, tan sólo habría que mover el contenido de Unreleased a una sección para la nueva versión.

¿Pueden los changelogs ser malos?

Sí. A continuación algunas formas en las que pueden ser muy poco útiles.

Usar un diff de los logs de los commits

Usar un diff de los logs de los commits es una mala idea: están llenos de ruido. Cosas como hacer merge de los commits, commits con títulos poco claros, cambios de documentación, etc.

El propósito de un commit es documentar un paso en la evolución del código fuente. Algunos proyectos limpian los commits, otros no.

El propósito de una entrada en el changelog es documentar cambios notables, usualmente entre múltiples commits, para comunicarlos claramente a los usuarios finales.

Ignorar funcionalidades sin soporte

Cuando la gente actualiza de una version a otra, debería estar bastante claro cuándo algo se va a romper. Debería ser posible actualizar a una versión que detalle funcionalidades sin soporte, eliminar lo que está obsoleto y actualizar a la versión donde esas funcionalidades han sido eliminadas.

Si no haces nada más, enumera lo que queda obsoleto, lo eliminado y cualquier otro cambio sin compatibilidad hacia atrás en tu changelog.

Fechas confusas

Los formatos de fecha regionales varían en todo el mundo y con frecuencia es difícil encontrar un formato intuitivo para todos. La ventaja de las fechas con el formato 2017-07-17 es que siguen un orden de unidades de mayor a menor: año, mes y día. Este formato tampoco coincide de forma ambigua con otros formatos de fecha, a diferencia de algunos que intercambian la posición del mes y el día. Todo esto, junto al hecho de ser un estándar ISO, son los motivos por los que es el formato de fecha recomendado para las entradas del changelog.

Preguntas frecuentes

¿Hay un formato estándar para el changelog?

No. Hay una guía de estilo del GNU o los dos parrafos del archivo guideline del GNU NEWS. Ambos son inadecuados o insuficientes.

Este proyecto apunta a ser una mejor convención de changelog. Esto se da observando las buenas prácticas en la comunidad open source y recopilando las mismas.

Críticas saludables, discusión y sugerencias para mejoras son bienvenidas.

¿Cómo debería llamarse el archivo de changelog?

Llámalo CHANGELOG.md. Algunos proyectos utilizan HISTORY, NEWS o RELEASES.

Si bien es fácil pensar que el nombre de tu archivo de changelog no importa tanto, ¿Por qué hacer difícil para los usuarios finales conseguir de manera consistente los cambios notables?

¿Y qué hay de los releases de Github?

Es una gran iniciativa. Los releases de Github pueden ser utilizados para convertir simples etiquetas de git (por ejemplo una etiqueta llamada v1.0.0) en ricas notas de lanzamiento ya sea añadiendo estas manualmente o trayendo los mensajes anotados de las etiquetas de git y convertirlas en notas.

Los releases de Github crean un changelog no portable que sólo pueden ser mostrados a usuarios dentro del contexto de Github. Es posible hacer que luzcan muy parecidas al formato de Mantenga un changelog, pero tiende a ser un poco más complicado.

La versión actual de los releases de Github es también discutiblemente no muy detectable por los usuarios finales, diferente a los típicos archivos en mayúsculas (README, CONTRIBUTING, etc.). Otro problema menor es que la interfaz actualmente no ofrece enlaces a los registros de los commits entre cada lanzamiento.

¿Se pueden analizar gramaticalmente los changelogs?

Es difícil, porque las personas usan formatos y nombres de archivos muy distintos.

Vandamme es una gema de Ruby creada por el equipo de Gemnasium que analiza gramaticalmente muchos (pero no todos) los changelogs de proyectos open source.

¿Qué hay sobre las versiones retiradas?

«Yanked releases» son versiones que tuvieron que ser retiradas por un error grave o problema de seguridad. Con frecuencia estas versiones ni siquiera aparecen en los changelogs. Deberían. Así es como deberían mostrarse:

## 0.0.5 - 2014-12-13 [YANKED]

La etiqueta [YANKED] está destacada por una razón: es importante que destaque. El hecho de estar entre corchetes la hace también más fácil de localizar programáticamente.

¿Deberías volver a escribir un changelog?

Por supuesto. Siempre hay buenas razones para mejorar el changelog. A veces abro «pull requests» para añadir registros faltantes en el changelog de proyectos open source.

También es posible que puedas descubrir que olvidaste señalar un cambio sin compatibilidad hacia atrás en las notas para una versión. En este caso es importante para ti actualizar el changelog.

¿Cómo puedo contribuir?

Este documento no es la verdad absoluta; es mi cuidadosa opinión, junto con información y ejemplos que recopilé.

Esto es porque quiero que la comunidad llegue a un consenso. Creo que la discusión es tan importante como el resultado final.

Así que por favor comienza a colaborar .

Conversaciones

Fui a The Changelog podcast para hablar acerca del porqué los mantenedores y colaboradores deberían preocuparse por los changelogs, y también acerca de las motivaciones detrás de este proyecto.