mirror of
https://github.com/olivierlacan/keep-a-changelog.git
synced 2025-08-26 12:18:16 +02:00
327 lines
11 KiB
Plaintext
327 lines
11 KiB
Plaintext
---
|
|
description: Mantenga un changelog
|
|
title: Mantenga un changelog
|
|
language: es-ES
|
|
version: 1.0.0
|
|
---
|
|
|
|
- changelog = "https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md"
|
|
- gh = "https://github.com/olivierlacan/keep-a-changelog"
|
|
- issues = "https://github.com/olivierlacan/keep-a-changelog/issues"
|
|
- semver = "https://semver.org/"
|
|
- shields = "https://shields.io/"
|
|
- thechangelog = "https://changelog.com/podcast/127"
|
|
- vandamme = "https://github.com/tech-angels/vandamme/"
|
|
- iso = "http://www.iso.org/iso/home/standards/iso8601.htm"
|
|
- ghr = "https://help.github.com/articles/creating-releases/"
|
|
|
|
.header
|
|
.title
|
|
%h1 Mantenga un changelog
|
|
%h2
|
|
No dejes que tus amigos usen el registro de git en los changelogs.
|
|
|
|
= link_to changelog do
|
|
Versión
|
|
%strong= current_page.metadata[:page][:version]
|
|
|
|
%pre.changelog= File.read("CHANGELOG.md")
|
|
|
|
.answers
|
|
%h3#what
|
|
%a.anchor{ href: "#what", aria_hidden: "true" }
|
|
¿Qué es un registro de cambios (changelog)?
|
|
|
|
%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.
|
|
|
|
%h3#why
|
|
%a.anchor{ href: "#why", aria_hidden: "true" }
|
|
¿Por qué mantener un changelog?
|
|
|
|
%p
|
|
Para facilitar a los usuarios y colaboradores ver exactamente qué
|
|
cambios reseñables se han realizado entre cada versión del
|
|
proyecto.
|
|
|
|
%h3#who
|
|
%a.anchor{ href: "#who", aria_hidden: "true" }
|
|
¿Quién necesita un changelog?
|
|
|
|
%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.
|
|
|
|
.good-practices
|
|
%h3#how
|
|
%a.anchor{ href: "#how", aria_hidden: "true" }
|
|
¿Cómo hago un buen changelog?
|
|
|
|
%h4#principles
|
|
%a.anchor{ href: "#principles", aria_hidden: "true" }
|
|
Directrices
|
|
|
|
%ul
|
|
%li
|
|
Están hechos <em>para los seres humanos</em>, no para las máquinas.
|
|
%li
|
|
Debe haber una entrada para cada versión.
|
|
%li
|
|
Los mismos tipos de cambios deben ser agrupados.
|
|
%li
|
|
Versiones y secciones deben ser enlazables.
|
|
%li
|
|
La última versión va primero.
|
|
%li
|
|
Debe mostrar la fecha de publicación de cada versión.
|
|
%li
|
|
Indicar si el proyecto sigue el #{link_to "Versionamiento Semántico", semver}.
|
|
|
|
%a.anchor{ href: "#types", aria_hidden: "true" }
|
|
%h4#types Tipos de cambios
|
|
|
|
%ul
|
|
%li
|
|
%code Added
|
|
para funcionalidades nuevas.
|
|
%li
|
|
%code Changed
|
|
para los cambios en las funcionalidades existentes.
|
|
%li
|
|
%code Deprecated
|
|
para indicar que una característica o funcionalidad está obsoleta
|
|
y que se eliminará en las próximas versiones.
|
|
%li
|
|
%code Removed
|
|
para las características en desuso que se eliminaron en esta
|
|
versión.
|
|
%li
|
|
%code Fixed
|
|
para corrección de errores.
|
|
%li
|
|
%code Security
|
|
en caso de vulnerabilidades.
|
|
|
|
.effort
|
|
|
|
%h3#effort
|
|
%a.anchor{ href: "#effort", aria_hidden: "true" }
|
|
¿Cómo puedo minimizar el esfuerzo requerido para mantener el
|
|
changelog?
|
|
|
|
%p
|
|
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:
|
|
|
|
%ul
|
|
%li
|
|
La gente puede ver qué cambios podrían esperar en los próximos
|
|
lanzamientos.
|
|
%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.
|
|
|
|
.bad-practices
|
|
%h3#bad-practices
|
|
%a.anchor{ href: "#bad-practices", aria_hidden: "true" }
|
|
¿Pueden los changelogs ser malos?
|
|
|
|
%p
|
|
Sí. A continuación algunas formas en las que pueden ser muy poco
|
|
útiles.
|
|
|
|
%h4#log-diffs
|
|
%a.anchor{ href: "#log-diffs", aria_hidden: "true" }
|
|
Usar un diff de los logs de los commits
|
|
|
|
%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.
|
|
|
|
%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.
|
|
|
|
%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.
|
|
|
|
%h4#ignoring-deprecations
|
|
%a.anchor{ href: "#ignoring-deprecations", aria_hidden: "true" }
|
|
Ignorar <em>funcionalidades sin soporte</em>
|
|
|
|
%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.
|
|
%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.
|
|
|
|
%h4#confusing-dates
|
|
%a.anchor{ href: "#confusing-dates", aria_hidden: "true" }
|
|
Fechas confusas
|
|
|
|
%p
|
|
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 <code>2017-07-17</code> 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
|
|
#{link_to "estándar ISO", iso}, son los motivos por los que es el
|
|
formato de fecha recomendado para las entradas del changelog.
|
|
|
|
%aside
|
|
Hay más. Ayúdame a recoger estos anti-patrones
|
|
= link_to "abriendo un issue", "#issues"
|
|
o una <em>pull request</em>.
|
|
|
|
.frequently-asked-questions
|
|
%h3#frequently-asked-questions
|
|
%a.anchor{ href: "#frequently-asked-questions", aria_hidden: "true" }
|
|
Preguntas frecuentes
|
|
|
|
%h4#standard
|
|
%a.anchor{ href: "#standard", aria_hidden: "true" }
|
|
¿Hay un formato estándar para el changelog?
|
|
|
|
%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.
|
|
|
|
%p
|
|
Este proyecto apunta a ser
|
|
= 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.
|
|
|
|
%p
|
|
Críticas saludables, discusión y sugerencias para mejoras
|
|
= link_to "son bienvenidas.", issues
|
|
|
|
|
|
%h4#filename
|
|
%a.anchor{ href: "#filename", aria_hidden: "true" }
|
|
¿Cómo debería llamarse el archivo de changelog?
|
|
|
|
%p
|
|
Llámalo <code>CHANGELOG.md</code>. Algunos proyectos utilizan
|
|
<code>HISTORY</code>, <code>NEWS</code> o <code>RELEASES</code>.
|
|
|
|
%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?
|
|
|
|
%h4#github-releases
|
|
%a.anchor{ href: "#github-releases", aria_hidden: "true" }
|
|
¿Y qué hay de los releases de Github?
|
|
|
|
%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.
|
|
|
|
%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.
|
|
|
|
%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.
|
|
|
|
%h4#automatic
|
|
%a.anchor{ href: "#automatic", aria_hidden: "true" }
|
|
¿Se pueden analizar gramaticalmente los changelogs?
|
|
|
|
%p
|
|
Es difícil, porque las personas usan formatos y nombres de archivos
|
|
muy distintos.
|
|
|
|
%p
|
|
#{link_to "Vandamme", 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.
|
|
|
|
|
|
%h4#yanked
|
|
%a.anchor{ href: "#yanked", aria_hidden: "true" }
|
|
¿Qué hay sobre las versiones retiradas?
|
|
|
|
%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:
|
|
|
|
%p <code>## [0.0.5] - 2014-12-13 [YANKED]</code>
|
|
|
|
%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.
|
|
|
|
|
|
%h4#rewrite
|
|
%a.anchor{ href: "#rewrite", aria_hidden: "true" }
|
|
¿Deberías volver a escribir un changelog?
|
|
|
|
%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.
|
|
|
|
%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.
|
|
|
|
|
|
%h4#contribute
|
|
%a.anchor{ href: "#contribute", aria_hidden: "true" }
|
|
¿Cómo puedo contribuir?
|
|
|
|
%p
|
|
Este documento no es la <strong>verdad absoluta</strong>; es mi
|
|
cuidadosa opinión, junto con información y ejemplos que recopilé.
|
|
|
|
%p
|
|
Esto es porque quiero que la comunidad llegue a un consenso. Creo
|
|
que la discusión es tan importante como el resultado final.
|
|
|
|
%p
|
|
Así que por favor <strong>#{link_to "comienza a colaborar", gh}
|
|
</strong>.
|
|
|
|
.press
|
|
%h3 Conversaciones
|
|
%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.
|