mirror of
https://github.com/olivierlacan/keep-a-changelog.git
synced 2025-07-29 16:54:12 +02:00
Break long lines to 80 characters
Because it is how they are formatted in the original file and also it is the standard for text mode.
This commit is contained in:
David Díaz
parent
964c9d321a
commit
ae0ef6227a
@ -33,21 +33,26 @@ version: 1.0.0
|
|||||||
¿Qué es un registro de cambios (changelog)?
|
¿Qué es un registro de cambios (changelog)?
|
||||||
|
|
||||||
%p
|
%p
|
||||||
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.
|
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.
|
||||||
|
|
||||||
%h3#why
|
%h3#why
|
||||||
%a.anchor{ href: "#why", aria_hidden: "true" }
|
%a.anchor{ href: "#why", aria_hidden: "true" }
|
||||||
¿Por qué mantener un changelog?
|
¿Por qué mantener un changelog?
|
||||||
|
|
||||||
%p
|
%p
|
||||||
Para facilitar a los usuarios y colaboradores ver exactamente qué cambios reseñables se han realizados entre cada versión del proyecto.
|
Para facilitar a los usuarios y colaboradores ver exactamente qué cambios
|
||||||
|
reseñables se han realizados entre cada versión del proyecto.
|
||||||
|
|
||||||
%h3#who
|
%h3#who
|
||||||
%a.anchor{ href: "#who", aria_hidden: "true" }
|
%a.anchor{ href: "#who", aria_hidden: "true" }
|
||||||
¿Quién necesita un changelog?
|
¿Quién necesita un changelog?
|
||||||
|
|
||||||
%p
|
%p
|
||||||
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.
|
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.
|
||||||
|
|
||||||
.good-practices
|
.good-practices
|
||||||
%h3#how
|
%h3#how
|
||||||
@ -86,7 +91,8 @@ version: 1.0.0
|
|||||||
para los cambios en las funcionalidades existentes.
|
para los cambios en las funcionalidades existentes.
|
||||||
%li
|
%li
|
||||||
%code Deprecated
|
%code Deprecated
|
||||||
para indicar que una característica o funcionalidad está obsoleta y que se eliminará en las próximas versiones.
|
para indicar que una característica o funcionalidad está obsoleta y que
|
||||||
|
se eliminará en las próximas versiones.
|
||||||
%li
|
%li
|
||||||
%code Removed
|
%code Removed
|
||||||
para las características en desuso que se eliminaron en esta versión.
|
para las características en desuso que se eliminaron en esta versión.
|
||||||
@ -104,7 +110,8 @@ version: 1.0.0
|
|||||||
¿Cómo puedo minimizar el esfuerzo requerido para mantener el changelog?
|
¿Cómo puedo minimizar el esfuerzo requerido para mantener el changelog?
|
||||||
|
|
||||||
%p
|
%p
|
||||||
Mantén una sección con el nombre <code>Unreleased</code> para hacer un seguimiento sobre los próximos cambios.
|
Mantén una sección con el nombre <code>Unreleased</code> para hacer un
|
||||||
|
seguimiento sobre los próximos cambios.
|
||||||
|
|
||||||
%p Esto nos puede servir para dos cosas:
|
%p Esto nos puede servir para dos cosas:
|
||||||
|
|
||||||
@ -112,7 +119,8 @@ version: 1.0.0
|
|||||||
%li
|
%li
|
||||||
La gente puede ver qué cambios podrían esperar en los próximos lanzamientos.
|
La gente puede ver qué cambios podrían esperar en los próximos lanzamientos.
|
||||||
%li
|
%li
|
||||||
Al lanzar una nueva versión, tan sólo habría que mover el contenido de <code>Unreleased</code> a una sección para la nueva versión.
|
Al lanzar una nueva versión, tan sólo habría que mover el contenido de
|
||||||
|
<code>Unreleased</code> a una sección para la nueva versión.
|
||||||
|
|
||||||
.bad-practices
|
.bad-practices
|
||||||
%h3#bad-practices
|
%h3#bad-practices
|
||||||
@ -126,29 +134,44 @@ version: 1.0.0
|
|||||||
Usar un diff de los logs de los commits
|
Usar un diff de los logs de los commits
|
||||||
|
|
||||||
%p
|
%p
|
||||||
Usar un diff de los logs de los commits es una mala idea: están llenos de ruido. Cosas como hacer <em>merge</em> de los commits, commits con títulos poco claros, cambios de documentación, etc.
|
Usar un diff de los logs de los commits es una mala idea: están llenos de
|
||||||
|
ruido. Cosas como hacer <em>merge</em> de los commits, commits con títulos poco
|
||||||
|
claros, cambios de documentación, etc.
|
||||||
|
|
||||||
%p
|
%p
|
||||||
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 un commit es documentar un paso en la evolución del código
|
||||||
|
fuente. Algunos proyectos limpian los commits, otros no.
|
||||||
|
|
||||||
%p
|
%p
|
||||||
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.
|
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.
|
||||||
|
|
||||||
%h4#ignoring-deprecations
|
%h4#ignoring-deprecations
|
||||||
%a.anchor{ href: "#ignoring-deprecations", aria_hidden: "true" }
|
%a.anchor{ href: "#ignoring-deprecations", aria_hidden: "true" }
|
||||||
Ignorar <em>funcionalidades sin soporte</em>
|
Ignorar <em>funcionalidades sin soporte</em>
|
||||||
|
|
||||||
%p
|
%p
|
||||||
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.
|
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.
|
||||||
%p
|
%p
|
||||||
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.
|
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.
|
||||||
|
|
||||||
%h4#confusing-dates
|
%h4#confusing-dates
|
||||||
%a.anchor{ href: "#confusing-dates", aria_hidden: "true" }
|
%a.anchor{ href: "#confusing-dates", aria_hidden: "true" }
|
||||||
Fechas confusas
|
Fechas confusas
|
||||||
|
|
||||||
%p
|
%p
|
||||||
En los EE.UU., la gente pone primero el mes (<code>06-02-2012</code> para el 2 de junio del 2012), mientras que muchas personas en el resto del mundo escriben de una manera muy robótica <code>2 Junio 2012</code> aunque lo proununcien diferente. <code>2012-06-02</code> funciona logicamente desde el más grande al más pequeño, no se solapa de maneras ambiugas con otros formatos de fecha y es un #{link_to "Estándar ISO", iso}. Por lo cual, es el formato de fecha recomendado para el changelog.
|
En los EE.UU., la gente pone primero el mes (<code>06-02-2012</code> para
|
||||||
|
el 2 de junio del 2012), mientras que muchas personas en el resto del mundo
|
||||||
|
escriben de una manera muy robótica <code>2 Junio 2012</code> aunque lo
|
||||||
|
proununcien diferente. <code>2012-06-02</code> funciona logicamente desde el
|
||||||
|
más grande al más pequeño, no se solapa de maneras ambiugas con otros formatos
|
||||||
|
de fecha y es un #{link_to "Estándar ISO", iso}. Por lo cual, es el formato de
|
||||||
|
fecha recomendado para el changelog.
|
||||||
|
|
||||||
%aside
|
%aside
|
||||||
Hay más. Ayúdame a recoger estos anti-patrones
|
Hay más. Ayúdame a recoger estos anti-patrones
|
||||||
@ -165,12 +188,15 @@ version: 1.0.0
|
|||||||
¿Hay un formato estándar para el changelog?
|
¿Hay un formato estándar para el changelog?
|
||||||
|
|
||||||
%p
|
%p
|
||||||
No. Hay una guía de estilo del GNU o los dos parrafos del archivo <code>guideline</code> del <em>GNU NEWS</em>. Ambos son inadecuados o insuficientes.
|
No. Hay una guía de estilo del GNU o los dos parrafos del archivo
|
||||||
|
<code>guideline</code> del <em>GNU NEWS</em>. Ambos son inadecuados o
|
||||||
|
insuficientes.
|
||||||
|
|
||||||
%p
|
%p
|
||||||
Este proyecto apunta a ser
|
Este proyecto apunta a ser
|
||||||
= link_to "una mejor convención de changelog.", changelog
|
= link_to "una mejor convención de changelog.", changelog
|
||||||
Esto se da observando las buenas prácticas en la comunidad open source y recopilando las mismas.
|
Esto se da observando las buenas prácticas en la comunidad open source y
|
||||||
|
recopilando las mismas.
|
||||||
|
|
||||||
%p
|
%p
|
||||||
Críticas saludables, discusión y sugerencias para mejoras
|
Críticas saludables, discusión y sugerencias para mejoras
|
||||||
@ -186,31 +212,46 @@ version: 1.0.0
|
|||||||
<code>HISTORY</code>, <code>NEWS</code> o <code>RELEASES</code>.
|
<code>HISTORY</code>, <code>NEWS</code> o <code>RELEASES</code>.
|
||||||
|
|
||||||
%p
|
%p
|
||||||
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?
|
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?
|
||||||
|
|
||||||
%h4#github-releases
|
%h4#github-releases
|
||||||
%a.anchor{ href: "#github-releases", aria_hidden: "true" }
|
%a.anchor{ href: "#github-releases", aria_hidden: "true" }
|
||||||
¿Y qué hay de los releases de Github?
|
¿Y qué hay de los releases de Github?
|
||||||
|
|
||||||
%p
|
%p
|
||||||
Es una gran iniciativa. #{link_to "Los releases de Github", ghr} pueden ser utilizados para convertir simples etiquetas de git (por ejemplo una etiqueta llamada <code>v1.0.0</code>) 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.
|
Es una gran iniciativa. #{link_to "Los releases de Github", ghr} pueden ser
|
||||||
|
utilizados para convertir simples etiquetas de git (por ejemplo una etiqueta
|
||||||
|
llamada <code>v1.0.0</code>) 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.
|
||||||
|
|
||||||
%p
|
%p
|
||||||
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 <em>Mantenga un changelog</em>, pero tiende a ser un poco más complicado.
|
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 <em>Mantenga un changelog</em>, pero tiende a ser
|
||||||
|
un poco más complicado.
|
||||||
|
|
||||||
%p
|
%p
|
||||||
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 (<code>README</code>, <code>CONTRIBUTING</code>, etc.). Otro problema menor es que la interfaz actualmente no ofrece enlaces a los registros de los commits entre cada lanzamiento.
|
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 (<code>README</code>, <code>CONTRIBUTING</code>, etc.). Otro
|
||||||
|
problema menor es que la interfaz actualmente no ofrece enlaces a los registros
|
||||||
|
de los commits entre cada lanzamiento.
|
||||||
|
|
||||||
%h4#automatic
|
%h4#automatic
|
||||||
%a.anchor{ href: "#automatic", aria_hidden: "true" }
|
%a.anchor{ href: "#automatic", aria_hidden: "true" }
|
||||||
¿Se pueden analizar gramaticalmente los changelogs?
|
¿Se pueden analizar gramaticalmente los changelogs?
|
||||||
|
|
||||||
%p
|
%p
|
||||||
Es difícil, porque las personas usan formatos y nombres de archivos muy distintos.
|
Es difícil, porque las personas usan formatos y nombres de archivos muy
|
||||||
|
distintos.
|
||||||
|
|
||||||
%p
|
%p
|
||||||
#{link_to "Vandamme", vandamme} es una gema de Ruby creada por el equipo de
|
#{link_to "Vandamme", vandamme} es una gema de Ruby creada por el equipo de
|
||||||
#{link_to "Gemnasium", gemnasium} que analiza gramaticalmente muchos (pero no todos) los changelogs de proyectos open source.
|
#{link_to "Gemnasium", gemnasium} que analiza gramaticalmente muchos (pero no
|
||||||
|
todos) los changelogs de proyectos open source.
|
||||||
|
|
||||||
|
|
||||||
%h4#yanked
|
%h4#yanked
|
||||||
@ -218,12 +259,16 @@ version: 1.0.0
|
|||||||
¿Qué hay sobre las versiones retiradas?
|
¿Qué hay sobre las versiones retiradas?
|
||||||
|
|
||||||
%p
|
%p
|
||||||
«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:
|
«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:
|
||||||
|
|
||||||
%p <code>## 0.0.5 - 2014-12-13 [YANKED]</code>
|
%p <code>## 0.0.5 - 2014-12-13 [YANKED]</code>
|
||||||
|
|
||||||
%p
|
%p
|
||||||
La etiqueta <code>[YANKED]</code> 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.
|
La etiqueta <code>[YANKED]</code> 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.
|
||||||
|
|
||||||
|
|
||||||
%h4#rewrite
|
%h4#rewrite
|
||||||
@ -231,10 +276,14 @@ version: 1.0.0
|
|||||||
¿Deberías volver a escribir un changelog?
|
¿Deberías volver a escribir un changelog?
|
||||||
|
|
||||||
%p
|
%p
|
||||||
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.
|
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.
|
||||||
|
|
||||||
%p
|
%p
|
||||||
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.
|
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.
|
||||||
|
|
||||||
|
|
||||||
%h4#contribute
|
%h4#contribute
|
||||||
@ -242,10 +291,12 @@ version: 1.0.0
|
|||||||
¿Cómo puedo contribuir?
|
¿Cómo puedo contribuir?
|
||||||
|
|
||||||
%p
|
%p
|
||||||
Este documento no es la <strong>verdad absoluta</strong>; es mi cuidadosa opinión, junto con información y ejemplos que recopilé.
|
Este documento no es la <strong>verdad absoluta</strong>; es mi cuidadosa
|
||||||
|
opinión, junto con información y ejemplos que recopilé.
|
||||||
|
|
||||||
%p
|
%p
|
||||||
Esto es porque quiero que la comunidad llegue a un consenso. Creo que la discusión es tan importante como el resultado final.
|
Esto es porque quiero que la comunidad llegue a un consenso. Creo que la
|
||||||
|
discusión es tan importante como el resultado final.
|
||||||
|
|
||||||
%p
|
%p
|
||||||
Así que por favor <strong>#{link_to "comienza a colaborar", gh}</strong>.
|
Así que por favor <strong>#{link_to "comienza a colaborar", gh}</strong>.
|
||||||
@ -253,4 +304,6 @@ version: 1.0.0
|
|||||||
.press
|
.press
|
||||||
%h3 Conversaciones
|
%h3 Conversaciones
|
||||||
%p
|
%p
|
||||||
Fui a #{link_to "The Changelog podcast", thechangelog} 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.
|
Fui a #{link_to "The Changelog podcast", thechangelog} 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.
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user