Merge pull request #84 from ZeliosAriex/translations-spanish
First version of the spanish translation
This commit is contained in:
Olivier Lacan
commit
724cb90b31
|
|
@ -0,0 +1,123 @@
|
|||
---
|
||||
description: Mantenga un Changelog
|
||||
title: Mantenga un Changelog
|
||||
language: es-ES
|
||||
---
|
||||
|
||||
:markdown
|
||||
# Mantener un CHANGELOG
|
||||
|
||||
## No dejes que tus amigos copien y peguen git logs en los CHANGELOGs™
|
||||
|
||||
### Qué es un registro de cambios (change log)?
|
||||
Un registro de cambios o “change log” de ahora en adelante, es un archivo que contiene una lista en orden cronológico sobre los cambios que vamos haciendo en cada reléase (o versión) de nuestro proyecto.
|
||||
|
||||
%pre.changelog= File.read(File.expand_path("../../CHANGELOG.md", __FILE__))
|
||||
|
||||
:markdown
|
||||
### Cuál es el propósito del change log?
|
||||
Para que les sea más fácil a los usuarios y contribuyentes, ver exactamente los cambios notables que se han hecho entre cada versión (o versiones) del proyecto.
|
||||
|
||||
### Por qué me debería importar?
|
||||
Debido a que las herramientas de software son para la gente. Si no te importa, ¿por qué contribuyes al código abierto? Sin duda, tiene que haber un "kernel" (ha!) de importancia en ese pequeño y encantador cerebro tuyo.
|
||||
|
||||
[En el podcast "The Changelog" hablé con Adam Stacoviak y Jerod Santo][thechangelog]
|
||||
(muy apropiado, ¿no?) acerca de por qué nos debería importar y sobre las motivaciones que es están detrás del proyecto. Si tienes tiempo (1:06), escúchalo, vale la pena
|
||||
|
||||
### Cómo podemos hacer un buen change log?
|
||||
Me alegro de que te lo hayas preguntado.
|
||||
|
||||
Un buen change log se guía por los siguientes principios:
|
||||
|
||||
- Está hecho para los seres humanos, no máquinas, por lo que la legibilidad es fundamental.
|
||||
- Fácil de conectar a cualquier sección (de ahí a que se use Markdown sobre texto plano).
|
||||
- Una sub-sección por versión.
|
||||
- Lista los releases en un orden inversamente-cronológico (el más reciente en la parte superior).
|
||||
- Escribe todas las fechas en formato `AAAA-MM-DD`. (Ejemplo: `2012-06-02` en vez de `2 JUN 2012`.) Es internacional, [sensible](http://xkcd.com/1179/), e independientemente del lenguaje que usemos.
|
||||
- Se menciona explícitamente si el proyecto sigue la convención del [Versionamiento Semántico][semver].
|
||||
- Cada versión debería:
|
||||
- Indicar su fecha de lanzamiento en el formato anterior.
|
||||
- Agrupar los cambios para describir su impacto en el proyecto, de la siguiente manera:
|
||||
- `Added` para funcionalidades nuevas.
|
||||
- `Changed` para los cambios en las funcionalidades existentes.
|
||||
- `Deprecated` para indicar que una característica 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 correcciones y bugs.
|
||||
- `Security` para invitar a los usuarios a actualizar, en el caso de que haya vulnerabilidades.
|
||||
|
||||
### Cómo puedo minimizar el esfuerzo requerido?
|
||||
Siempre mantén una sección con el nombre `"Unreleased"` para hacer un seguimiento sobre los cambios
|
||||
|
||||
Esto nos puede servir para dos cosas:
|
||||
|
||||
- La gente puede ver qué cambios podrían esperar en los próximos releases
|
||||
- Una vez queramos hacer una release, sólo hay que cambiar `Unreleased` por el número de versión y añadir una nueva cabecera `Unreleased` en la parte superior.
|
||||
|
||||
### Qué es lo que hace llorar a los unicornios?
|
||||
Muy bien... vamos allá.
|
||||
|
||||
- **Hacer un copia y pega de un diff o de los logs de los commits.** Simplemente no lo hagas, no estas ayudando a nadie.
|
||||
- **No indicar las características obsoletas.** Cuando la gente actualiza de una versión a otra,debe tener claro cuando algo se romperá.
|
||||
- **Fechas en formatos específicos de una región.** En los EE.UU., la gente pone primero el mes ("06/02/2012" para el 2 de junio del 2012, lo que hace no tiene sentido), mientras que muchas personas en el resto del mundo escriben de una manera muy robótica "2 JUN 2012". "2012-06-02" me parece más lógico, y también cabe comentar que es un [ISO standard](http://www.iso.org/iso/home/standards/iso8601.htm). Por lo tanto, es el formato de la fecha recomendada para los change logs
|
||||
|
||||
Pero espera! hay más ayúdame a coleccionar esas lágrimas de unicornio [abriendo una incidencia][issues] o haciendo un pull request.
|
||||
|
||||
### Hay algún formato estándar de formato para los change log?
|
||||
Tristemente, no. Pero calma. Sé que estás corriendo furiosamente intentando encontrar ese link al libro de estilo de registro de cambios de GNU, or the two-paragraph GNU NEWS file
|
||||
"guideline". La guía de estilo GNU es un buen comienzo, pero es tristemente cándida. No hay nada malo en ser cándida, pero cuando la gente necesita orientación es rara la vez, que resulta ser muy útil. Sobre todo, cuando hay muchas situaciones y casos muy específicos.
|
||||
|
||||
Este proyecto [contiene lo que espero se convierta en un mejor patrón de CHANGELOGs][CHANGELOG].
|
||||
No creo que la situación actual sea lo suficientemente buena, i creo que como comunidad que somos podemos llegar a mejores convenciones si tratamos de extraer buenas prácticas de proyectos de software reales. Por favor echa un pequeño vistazo y recuerda que las [sugerencias y discusiones para mejorar son bienvenidas][issues]!
|
||||
|
||||
### Cómo se debería llamar el change log?
|
||||
Bueno, si te fijas en en ejemplo anterior, `CHANGELOG.md` es la convención más usada
|
||||
|
||||
Otros proyectos también usan los siguientes nombres `HISTORY.txt`, `HISTORY.md`, `History.md`, `NEWS.txt`,
|
||||
`NEWS.md`, `News.txt`, `RELEASES.txt`, `RELEASE.md`, `releases.md`, etc.
|
||||
|
||||
Es un desastre. Todos estos nombres sólo hacen más difícil la búsqueda del fichero.
|
||||
|
||||
### Por qué la gente no usa simplemente un `git log`?
|
||||
Debido a que están llenos de ruido - por naturaleza. No se podría hacer un change log adecuado ni siquiera en un proyecto hipotético dirigido por seres humanos perfectos que nunca se equivocan y que nunca se olvidan meter ningún archivo en un commit... etc. El propósito de un commit es el de documentar un cambio atómico en el cual el software evoluciona desde un estado hacia otro. El propósito del change log es el de documentar las diferencias notables entre estos estados.
|
||||
|
||||
### Se pueden parsear automáticamente los change logs?
|
||||
Es difícil, ya que la gente sigue formatos y nombres de archivo muy distintos.
|
||||
|
||||
[Vandamme][vandamme] es un Ruby gem creado por el equipo [Gemnasium][gemnasium], que lo que hace es parsear algunos (no todos) los change logs de varios proyectos open source.
|
||||
|
||||
### Por que estás continuamente alternando los nombres de "CHANGELOG" a "change log"?
|
||||
"CHANGELOG" es el nombre del archivo en sí. Es un poco intrusivo pero es una convención histórica seguida por muchos proyectos de código abierto. Otro ejemplo de este tipo de nombres en archivos son [`README`][README], [`LICENSE`][LICENSE],
|
||||
y [`CONTRIBUTING`][CONTRIBUTING].
|
||||
|
||||
Los nombres en mayúsculas (que en algunos sistemas operativos antiguos hacían que estos ficheros aparecieran los primeros) se utilizan para llamar la atención sobre ellos. Dado que son importantes metadatos sobre el proyecto, que podría ser útil a cualquier persona con la intención de utilizar o contribuir al mismo.
|
||||
|
||||
Cuando me refiero a "change log", estoy hablando de la función del fichero: registrar los cambios.
|
||||
|
||||
### Qué son las yanked releases?
|
||||
Las yanked releases son versiones que tuvieron que ser retiradas a causa de un grave error o problema de seguridad. A menudo, estas versiones ni siquiera aparecen en los change logs, y tendrían que aparecer. Así es como se muestran:
|
||||
|
||||
`## 0.0.5 - 2014-12-13 [YANKED]`
|
||||
|
||||
La sección `[YANKED]` va entre corchetes por una razón, es importante que destaque, y el echo de estar rodeado por corchetes lo hace más fácil de localizar programáticamente.
|
||||
|
||||
### Deberías volver a escribir un change log?
|
||||
Por supuesto. Siempre hay buenas razones para mejorar el change log. A veces abro "pull requests" para añadir registros faltantes en el change log de proyectos open source.
|
||||
|
||||
### Como puedo contribuir?
|
||||
Este documento no es la **verdad absoluta**; es mi cuidadosa opinión, junto con información y ejemplos que recogí.
|
||||
|
||||
Esto es porque quiero que la comunidad llegue a un conceso. Creo que la discusión es tan importante como el resultado final.
|
||||
|
||||
[**Contribuye**][gh].
|
||||
|
||||
[CHANGELOG]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md
|
||||
[CONTRIBUTING]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CONTRIBUTING.md
|
||||
[LICENSE]: https://github.com/olivierlacan/keep-a-changelog/blob/master/LICENSE
|
||||
[README]: https://github.com/olivierlacan/keep-a-changelog/blob/master/README.md
|
||||
[gemnasium]: https://gemnasium.com/
|
||||
[gh]: https://github.com/olivierlacan/keep-a-changelog
|
||||
[issues]: https://github.com/olivierlacan/keep-a-changelog/issues
|
||||
[semver]: http://semver.org/
|
||||
[shields]: http://shields.io/
|
||||
[thechangelog]: http://5by5.tv/changelog/127
|
||||
[vandamme]: https://github.com/tech-angels/vandamme/
|
||||
Loading…
Reference in New Issue