Merge pull request #1 from olivierlacan/master

Update fork version

CHANGELOG.md

@@ -24,6 +24,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - French translation from @zapashcanon.
 - Brazilian Portugese translation from @aisamu.
 - Polish translation from @amielucha.
+- Russian translation from @aishek.
 
 ### Changed
 - Start using "changelog" over "change log" since it's the common usage.

source/es-ES/1.0.0/index.html.haml

@@ -0,0 +1,258 @@
+---
+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"
+- 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/"
+- 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 copien y peguen git logs 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 (change log)?
+
+  %p
+    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 release (o versión) de nuestro proyecto.
+
+  %h3#why
+    %a.anchor{ href: "#why", aria_hidden: "true" }
+    ¿Cuál es el propósito del change log?
+
+  %p
+    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.
+
+  %h3#who
+    %a.anchor{ href: "#who", aria_hidden: "true" }
+    ¿Quién necesita un change log?
+
+  %p
+    Las personas. Ya sean consumidores o desarrolladores, los usuarios finales del software son seres humanos que les importa 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" }
+    ¿Como hago un buen change log?
+
+  %h4#principles
+    %a.anchor{ href: "#principles", aria_hidden: "true" }
+    Directrices
+
+  %ul
+    %li
+      Están hecho para los seres humanos, 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 viene primero.
+    %li
+      La fecha de publicación de cada versión es mostrada.
+    %li
+      Se menciona explícitamente si el proyecto sigue la convención del #{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 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 correcciones y bugs.
+    %li
+      %code Security
+      en caso de vulnerabilidades.
+
+.effort
+
+  %h3#effort
+    %a.anchor{ href: "#effort", aria_hidden: "true" }
+    ¿Cómo puedo minimizar el esfuerzo requerido?
+
+  %p
+    Siempre 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 releases.
+    %li
+      Una vez que queramos hacer un release, sólo habría que mover la sección <code>Unreleased</code> y sus cambios en una nueva sección con la respectiva versión.
+
+.bad-practices
+  %h3#bad-practices
+    %a.anchor{ href: "#bad-practices", aria_hidden: "true" }
+    ¿Pueden los change logs ser malos?
+
+  %p Si. Aquí hay unas maneras 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 oscuros, cambios de documentación, entre otros.
+
+  %p
+    El propósito de un commit es documentar un paso en la evolución del código fuente. Algunos proyectos limpian los commits, en otros no.
+
+  %p
+    El propósito de una entrada del change log es documentar la notable diferencia, usualmente entre múltiples commits, para comunicarlos claramente a los usuarios finales.
+
+  %h4#ignoring-deprecations
+    %a.anchor{ href: "#ignoring-deprecations", aria_hidden: "true" }
+    Ignorando Deprecaciones
+
+  %p
+    Cuando las personas actualizan de una versión a otra, debería ser extremadamente claro cuando algo se romperá. Debería ser posible actualizar a una versión que liste deprecaciones, remover que está deprecado, luego actualizar a la versión donde las deprecaciones sean remociones.
+
+  %p
+    Si no haces nada más, lista deprecaciones, remociones, y cualquier cambio sin compatibilidad hacia atrás en tu change log.
+
+
+  %h4#confusing-dates
+    %a.anchor{ href: "#confusing-dates", aria_hidden: "true" }
+    Fechas confusas
+
+  %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>, sin embargo lo pronuncian distinto. <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 "Estandar ISO", iso}. Por lo cual, es el formato de fecha recomendado para change logs.
+
+  %aside
+    Hay más. Ayudame a recoger estos anti-patrones
+    = link_to "abriendo un issue", "#issues"
+    o un pull request.
+
+.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 estandar para los change logs?
+
+  %p
+    No realmente. Hay una guía de estilo del GNU, o los dos parrafos del archivo de NOTICIAS <code>guideline</code> del GNU. Ambos son inadecuados o insuficientes.
+
+  %p
+    Este proyecto apunta a ser
+    = link_to "una mejor convención de change logs.", 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 change log?
+
+  %p
+    Llamalo <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 change log no importa tanto, ¿Por qué hacer dificil 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 release 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 change log no portable que solo 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 involucrado.
+
+  %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>, entre otros.). Otro problema menor es que la interfaz actualmente no ofrece enlaces a los registros de los commits entre cada release.
+
+  %h4#automatic
+    %a.anchor{ href: "#automatic", aria_hidden: "true" }
+    ¿Se pueden analizar gramaticalmente los change logs?
+
+  %p
+    Es difícil, porque las personas siguen formatos y distintos nombres de archivo muy distintos.
+
+  %p
+    #{link_to "Vandamme", vandamme} es una gema de Ruby creada por el equipo de 
+    #{link_to "Gemnasium", gemnasium} y que analiza gramaticalmente muchos (pero no todos) los change logs de proyectos open source.
+
+
+  %h4#yanked
+    %a.anchor{ href: "#yanked", aria_hidden: "true" }
+    ¿Qué hay sobre los releases retirados?
+
+  %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 change logs. Deberían. Así es como se deberían mostrarse:
+
+  %p <code>## 0.0.5 - 2014-12-13 [YANKED]</code>
+
+  %p
+    La etiqueta <code>[YANKED]</code> va entre corchetes por una razón, es importante que destaque, y el hecho de estar rodeado por corchetes lo hace más fácil de localizar programáticamente.
+
+
+  %h4#rewrite
+    %a.anchor{ href: "#rewrite", aria_hidden: "true" }
+    ¿Deberías volver a escribir un change log?
+
+  %p
+    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.
+
+  %p
+    También es posible que puedas descubrir que olvidaste comentar sobre un cambio sin compatibilidad hacia atrás en las notas para una versión. En este caso es importante para ti actualizar el change log.
+
+
+  %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 recogí.
+
+  %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
+    Fuí al #{link_to "The Changelog podcast", thechangelog} para hablar acerca de porqué a los mantenedores y contribuidores deberían importarles los change logs, y también acerca de las motivaciones detrás de este proyecto.

source/it-IT/1.0.0/index.html.haml

@@ -5,7 +5,6 @@ language: it-IT
 version: 1.0.0
 ---
 
-
 - changelog = "https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md"
 - gemnasium = "https://gemnasium.com/"
 - gh = "https://github.com/olivierlacan/keep-a-changelog"
@@ -34,7 +33,7 @@ version: 1.0.0
     Cos'è un changelog?
 
   %p
-    Un changelog è un file che contiene una lista curata e ordinata cronologicamente 
+    Un changelog è un file che contiene una lista curata e ordinata cronologicamente
     delle modifiche degne di nota per ogni versione di un progetto.
 
   %h3#why
@@ -42,7 +41,7 @@ version: 1.0.0
     Perché tenere un changelog?
 
   %p
-    Per rendere facile agli utilizzatori e contribuenti vedere con precisione quali modifiche 
+    Per rendere facile agli utilizzatori e contribuenti vedere con precisione quali modifiche
     importanti sono state fatte tra ogni release (o versione) del progetto.
 
   %h3#who
@@ -50,7 +49,7 @@ version: 1.0.0
     Chi ha bisogno di un changelog?
 
   %p
-    Le persone ne hanno bisogno. Che si tratti di consumatori o di sviluppatori, gli utenti finali 
+    Le persone ne hanno bisogno. Che si tratti di consumatori o di sviluppatori, gli utenti finali
     del software sono persone interessate a ciò che avviene in esso.
     Se il software è cambiato, allora le persone vogliono sapere come e perché.
 
@@ -75,9 +74,9 @@ version: 1.0.0
     %li
       L'ultima versione viene prima.
     %li
-     Viene mostrata la data di release di ogni versione.
+      Viene mostrata la data di release di ogni versione.
     %li
-     Si dichiara se il progetto segue il #{link_to "Versionamento Semantico", semver}.
+      Si dichiara se il progetto segue il #{link_to "Versionamento Semantico", semver}.
 
   %a.anchor{ href: "#types", aria_hidden: "true" }
   %h4#types Tipologie di cambiamenti
@@ -101,7 +100,7 @@ version: 1.0.0
     %li
       %code Security
       per invitare gli utilizzatori ad aggiornare in caso di vulnerabilità.
-      
+
 .effort
 
   %h3#effort
@@ -109,8 +108,8 @@ version: 1.0.0
     Come posso ridurre gli sforzi necessari a mantenere un changelog?
 
   %p
-    Tieni una sezione <code>Unreleased</code> in cima al changelog in modo da tenere traccia
-    dei cambiamenti imminenti.
+    Tieni una sezione <code>Unreleased</code> in cima al changelog in
+    modo da tenere traccia dei cambiamenti imminenti.
 
   %p Questo serve per due scopi:
 
@@ -118,14 +117,16 @@ version: 1.0.0
     %li
       Le persone possono vedere quali modifiche si possono aspettare nelle future release.
     %li
-    Ad una nuova release, si deve solo spostare i cambiamenti della sezione 
-    `"Unreleased"` in una nuova sezione con il suo numero di versione.
+      Ad una nuova release, si deve solo spostare i cambiamenti della sezione
+      `"Unreleased"` in una nuova sezione con il suo numero di versione.
 
 .bad-practices
   %h3#bad-practices
     %a.anchor{ href: "#bad-practices", aria_hidden: "true" }
     I changelog possono essere cattivi?
+
   %p Si. Ecco alcuni modi in cui possono essere meno utili.
+
   %h4#log-diffs
     %a.anchor{ href: "#log-diffs", aria_hidden: "true" }
     Commit log diffs
@@ -136,11 +137,11 @@ version: 1.0.0
     modifiche della documentazione, etc.
 
   %p
-    Lo scopo di un commit è quello di documentare un passo nell'evoluzione 
+    Lo scopo di un commit è quello di documentare un passo nell'evoluzione
     del codice sorgente. Alcuini progetti ripuliscono i commit, altri non lo fanno.
 
   %p
-    Lo scopo di una voce changelog è quello di documentare le differenze rilevanti, 
+    Lo scopo di una voce changelog è quello di documentare le differenze rilevanti,
     spesso attraverso commit mulptipli, per comunicarli in mdo chiaro agli utenti finali.
 
   %h4#ignoring-deprecations
@@ -149,11 +150,11 @@ version: 1.0.0
   %p
     Quando le persone aggiornano da una versione ad un'altra,
     dovrebbe essere dolorosamente chiaro quando qualcosa si romperà.
-    Dovrebbe essere possibile eseguire l'aggiornamento a una versione 
-    che elenca le deprecazioni, rimuove ciò che è deprecato, quindi 
+    Dovrebbe essere possibile eseguire l'aggiornamento a una versione
+    che elenca le deprecazioni, rimuove ciò che è deprecato, quindi
     aggiorna alla versione in cui le deprecazioni diventano rimozioni.
   %p
-    Se non fai nient'altro elenca le deprecazioni, le rimozioni e 
+    Se non fai nient'altro elenca le deprecazioni, le rimozioni e
     qualsiasi altro cambiamento nel tuo changelog.
   %h4#confusing-dates
     %a.anchor{ href: "#confusing-dates", aria_hidden: "true" }
@@ -161,14 +162,14 @@ version: 1.0.0
 
   %p
     Negli Stati Uniti si mette prima il mese nelle date (<code>06-02-2012</code> sta per
-    il 2 Giugno 2012), mentre molte persone nel resto del mondo scrivono un 
+    il 2 Giugno 2012), mentre molte persone nel resto del mondo scrivono un
     robotico <code>2 June 2012</code>, ma lo pronunciano diversamente.
-    <code>2012-06-02</code> funziona con la logica dal più grande al più piccolo, 
-    non ha sovrapposizioni ambigue con altri formati di date, ed è uno #{link_to "ISO standard", iso}. 
+    <code>2012-06-02</code> funziona con la logica dal più grande al più piccolo,
+    non ha sovrapposizioni ambigue con altri formati di date, ed è uno #{link_to "ISO standard", iso}.
     Per tutti questi motivi, è il formato di date raccomandato per i changelog.
 
   %aside
-    C'è di più. Aiutatemi a collezionare questi anti-modelli 
+    C'è di più. Aiutatemi a collezionare questi anti-modelli
     = link_to "aprendo un issue", issues
     o una pull request.
 
@@ -181,14 +182,14 @@ version: 1.0.0
     Esiste un formato standard per i changelog?
 
   %p
-    Non esattamente. Esistono le linee guida GNU sullo stile dei changelog, oppure 
+    Non esattamente. Esistono le linee guida GNU sullo stile dei changelog, oppure
     i due lunghi paragrafi nel documento di GNU NEWS denominato "guideline". Entrambe
     sono inadeguate o insufficienti.
 
   %p
     Questo progetto vuole essere
     = link_to "una migliore convenzione  per i file changelog.", changelog
-    Per questo motivo osserviamo le migliori pratiche della comunità open source 
+    Per questo motivo osserviamo le migliori pratiche della comunità open source
     e le portiamo avanti.
 
   %p
@@ -205,41 +206,48 @@ version: 1.0.0
     <code>HISTORY</code>, <code>NEWS</code> o <code>RELEASES</code>.
 
   %p
-    Mentre è facile pensare che il nome del tuo file changelog 
-    non sia poi così importante, perchè non rendere facile la 
+    Mentre è facile pensare che il nome del tuo file changelog
+    non sia poi così importante, perchè non rendere facile la
     vita ai tuoi utenti, usando sempre lo stesso nome?
 
   %h4#github-releases
     %a.anchor{ href: "#github-releases", aria_hidden: "true" }
     Cosa dire delle GitHub Releases?
+
   %p
     È una bella iniziativa. #{link_to "Releases", ghr} può essere usato
-    per rendere semplice i git tags (per esempio il nome del tag <code>v1.0.0</code>)
-    All'interno di note di rilascio ben dettagliate si possono aggiungere le note manualmente oppure è possibile
-    utilizzare le note dei messaggi dei git tag inserendole dentro nelle note di rilascio.
-    j
+    per rendere semplice i git tags (per esempio il nome del tag
+    <code>v1.0.0</code>) All'interno di note di rilascio ben dettagliate
+    si possono aggiungere le note manualmente oppure è possibile
+    utilizzare le note dei messaggi dei git tag inserendole dentro nelle
+    note di rilascio.
+
   %p
     GitHub Releases crea un changelog non-portable che può essere solo
-    visualizzato dagli utenti nel contesto di GitHub. È possibile farlo 
-    apparire molto simile al formato di Keep a Changelog, tuttavia tende 
+    visualizzato dagli utenti nel contesto di GitHub. È possibile farlo
+    apparire molto simile al formato di Keep a Changelog, tuttavia tende
     ad essere un po' più complicato.
+
   %p
-    La versione corrente di GitHub Releases risulta inoltre probabilmente
-    poco rilevante per gli utenti finali, a differenza dei tipici file maiuscoli
-    (<code>README</code>, <code>CONTRIBUTING</code>, etc.). Un altro problema 
-    minore è che l'interfaccia non offre attualmente link per la 
-    creazione di log tra ciascuna release.
+    La versione corrente di GitHub Releases risulta inoltre
+    probabilmente poco rilevante per gli utenti finali, a differenza dei
+    tipici file maiuscoli (<code>README</code>,
+    <code>CONTRIBUTING</code>, etc.). Un altro problema minore è che
+    l'interfaccia non offre attualmente link per la creazione di log tra
+    ciascuna release.
+
   %h4#automatic
     %a.anchor{ href: "#automatic", aria_hidden: "true" }
     I changelog possono essere analizzati automaticamente?
 
   %p
-   È difficile, perché le persone usano formati e nomi di file profondamente diversi.
+    È difficile, perché le persone usano formati e nomi di file
+    profondamente diversi.
 
   %p
-    #{link_to "Vandamme", vandamme} è una Ruby gem
-    creata dal team #{link_to "Gemnasium", gemnasium} ed è in grado di fare il parsing dei
-  change log di molti (ma non tutti) i progetti open source.
+    #{link_to "Vandamme", vandamme} è una Ruby gem creata dal team
+    #{link_to "Gemnasium", gemnasium} ed è in grado di fare il parsing dei
+    change log di molti (ma non tutti) i progetti open source.
 
 
   %h4#yanked
@@ -247,17 +255,18 @@ version: 1.0.0
     Cosa sono le release "yanked"?
 
   %p
-    Le release "yanked" sono versioni che sono state rimosse a causa di bug seri
-  o problemi di sicurezza. Spesso queste versioni non appaiono nei change
-  log. Invece dovrebbero esserci, nel seguente modo:
+    Le release "yanked" sono versioni che sono state rimosse a causa di
+    bug seri o problemi di sicurezza. Spesso queste versioni non
+    appaiono nei change log. Invece dovrebbero esserci, nel seguente
+    modo:
 
   %p <code>## 0.0.5 - 2014-12-13 [YANKED]</code>
 
   %p
-    L'etichetta <code>[YANKED]</code> è in maiuscolo per un motivo. 
-    È importante che le persone la notino. 
-   Poiché è racchiusa tra parentesi quadre è anche 
-   più semplice da riconoscere nel parsing automatizzato.
+    L'etichetta <code>[YANKED]</code> è in maiuscolo per un motivo.
+    È importante che le persone la notino.
+    Poiché è racchiusa tra parentesi quadre è anche
+    più semplice da riconoscere nel parsing automatizzato.
 
 
   %h4#rewrite
@@ -266,13 +275,13 @@ version: 1.0.0
 
   %p
     Certo. Ci sono sempre buoni motivi per migliorare un changelog. Io apro regolarmente
-  delle pull request per aggiungere release mancanti ai progetti open source che non mantengono
-  correttamente i changelog.
+    delle pull request per aggiungere release mancanti ai progetti open source che non mantengono
+    correttamente i changelog.
 
   %p
-   È anche possibile che si scopra di aver dimenticato di annotare una modifica
-  non retro-compatibile nelle note per una versione. Ovviamente è importante aggiornare
-  il changelog in questo caso.
+    È anche possibile che si scopra di aver dimenticato di annotare una modifica
+    non retro-compatibile nelle note per una versione. Ovviamente è importante aggiornare
+    il changelog in questo caso.
 
   %h4#contribute
     %a.anchor{ href: "#contribute", aria_hidden: "true" }
@@ -280,11 +289,11 @@ version: 1.0.0
 
   %p
     Questo documento non è la <strong>verità assoluta</strong>; è solo la mia attenta
-  opinione, arricchita dalle informazioni ed esempi che ho raccolto.
+    opinione, arricchita dalle informazioni ed esempi che ho raccolto.
 
   %p
     Questo è perché voglio che la nostra comunità raggiunga un consenso. Credo che
-  la discussione sia importante almeno quanto il risultato finale.
+    la discussione sia importante almeno quanto il risultato finale.
 
   %p
     Quindi per favore <strong>#{link_to "partecipate e dateci dentro", gh}</strong>.

source/ru/1.0.0/index.html.haml

@@ -0,0 +1,303 @@
+---
+description: Keep a Changelog
+title: Keep a Changelog
+language: ru
+version: 1.0.0
+---
+
+- changelog = "https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.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/"
+- iso = "http://www.iso.org/iso/home/standards/iso8601.htm"
+- ghr = "https://help.github.com/articles/creating-releases/"
+
+.header
+  .title
+    %h1 Ведите CHANGELOG
+    %h2 Не позволяйте друзьям сливать логи гита в CHANGELOG™
+
+  = link_to changelog do
+    Version
+    %strong= current_page.metadata[:page][:version]
+
+  %pre.changelog= File.read("CHANGELOG.md")
+
+.answers
+  %h3#what
+    %a.anchor{ href: "#what", aria_hidden: "true" }
+    Что такое лог изменений?
+
+  %p
+    Лог изменений – это файл, который содержит поддерживаемый, хронологически
+    упорядоченный список изменений для каждой версии проекта.
+
+  %h3#why
+    %a.anchor{ href: "#why", aria_hidden: "true" }
+    Зачем вести лог изменений?
+
+  %p
+    Чтобы пользователям и контрибьюторам было проще точно понять,
+    какие изменения были сделаны в каждом релизе (или версии) проекта
+
+  %h3#who
+    %a.anchor{ href: "#who", aria_hidden: "true" }
+    Кому нужен лог изменений?
+
+  %p
+    Людям. Будь то клиенты или разработчики, конечные пользователи программного обеспечения
+    это люди, и им важно, с чем они работают. Когда программное обеспечение меняется,
+    люди хотят знать почему и что изменилось.
+
+.good-practices
+  %h3#how
+    %a.anchor{ href: "#how", aria_hidden: "true" }
+    Как мне сделать хороший лог изменений?
+
+  %h4#principles
+    %a.anchor{ href: "#principles", aria_hidden: "true" }
+    Главные принципы
+
+  %ul
+    %li
+      Лог изменений ведётся <em>для людей</em>, не для машин.
+    %li
+      Для каждой версии должен быть отдельный раздел.
+    %li
+      Одинаковые типы изменений должны быть сгруппированы.
+    %li
+      Должна быть возможность поставить ссылку на любую версию или раздел.
+    %li
+      Последняя версия должна идти в начале файла.
+    %li
+      У каждой версии указана дата выпуска.
+    %li
+      Уточните, следуете ли вы принципам #{link_to "Семантического версионирования", semver}
+
+  %a.anchor{ href: "#types", aria_hidden: "true" }
+  %h4#types Типы изменений
+
+  %ul
+    %li
+      %code Добавлено
+      для новых функций.
+    %li
+      %code Изменено
+      для изменений в существующей функциональности.
+    %li
+      %code Устарело
+      для функций, которы скоро будут удалены.
+    %li
+      %code Удалено
+      для удалённых функций.
+    %li
+      %code Исправлено
+      для любых исправлений.
+    %li
+      %code Безопасность
+      в случае уязвимостей.
+
+.effort
+
+  %h3#effort
+    %a.anchor{ href: "#effort", aria_hidden: "true" }
+    Как мне тратить меньше усилий на ведение лога изменений?
+
+  %p
+    Ведите раздел <code>Новое</code> с изменениями для новой версии в начале файла.
+
+  %p Это нужно для двух вещей:
+
+  %ul
+    %li
+      Люди смогут видеть, каких изменений им ожидать в ближайших релизах
+    %li
+      В момент релиза вы можете переместить изменения раздела <code>Новое</code>
+      в раздел нового релиза.
+
+.bad-practices
+  %h3#bad-practices
+    %a.anchor{ href: "#bad-practices", aria_hidden: "true" }
+    Бывают плохие логи изменений?
+
+  %p Да. Вот несколько способов чтобы сделать их не такими полезными.
+
+  %h4#log-diffs
+    %a.anchor{ href: "#log-diffs", aria_hidden: "true" }
+    Диффы лога коммитов
+
+  %p
+    Использование диффов лога коммитов это плохая идея: они очень шумные.
+    Шумят мердж-коммиты, коммиты с непонятными названиями, изменения в документации
+    и тому подобное.
+
+  %p
+    Назначение коммита в том, чтобы задокументировать шаг в эволюции исходного
+    кода. В некоторых проектах следят за историей коммитов, в некоторых нет.
+
+  %p
+    Назначение же раздела в логе изменений — задокументировать ключевые различия,
+    часто между несколькими коммитами, чтобы ясно донести их назначение
+    до конечных пользователей.
+
+
+  %h4#ignoring-deprecations
+    %a.anchor{ href: "#ignoring-deprecations", aria_hidden: "true" }
+    Игнорирование устаревающих функций
+
+  %p
+    Когда люди обновляются с одной версии на другую, должно быть до боли
+    очевидно, что сломается. Должна быть возможность обновиться до версии, которая
+    перечисляет устаревающие функции, удалить устаревшие данные, затем обновиться до версии,
+    в которой устаревающие функции становятся удалёнными.
+
+  %p
+    Если вы не ведёте лог изменений, то хотя бы указывайте в нём устаревающие
+    и удалённые функции, а также все критичные изменения.
+
+  %h4#confusing-dates
+    %a.anchor{ href: "#confusing-dates", aria_hidden: "true" }
+    Непонятные даты
+
+  %p
+    В США сначала пишут месяц (<code>06-02-2012</code> для 2 июня 2012),
+    в то время как большинство людей в остальном мире пишут роботоподобное
+    <code>2 июня 2012</code>, произнося эту дата по-разному. Запись
+    <code>2012-06-02</code> логично идёт от большего к меньшему, не пересекается
+    с большинством других форматов дат, и является #{link_to "стандартом ISO", iso}.
+    Поэтому именно такой формат рекомендуется для логов изменений.
+
+  %aside
+    Есть и другие. Помогите мне собрать эти антипаттерны,
+    #{link_to "создав тикет", "#issues"} или пулл-реквест.
+
+.frequently-asked-questions
+  %h3#frequently-asked-questions
+    %a.anchor{ href: "#frequently-asked-questions", aria_hidden: "true" }
+    Часто задаваемые вопросы
+
+  %h4#standard
+    %a.anchor{ href: "#standard", aria_hidden: "true" }
+    Существует ли стандарт формата логов изменений?
+
+  %p
+    На самом деле нет. Есть стайлгайд логов изменений GNU,
+    есть длиной-в-два-параграфа файл "guideline" GNU NEWS.
+    Оба или неадекватны или недостаточно полны.
+
+  %p
+    Цель этого проекта — стать
+    = link_to "улучшенной версией соглашения о формате логов изменений.", changelog
+    Это приходит из-за сбора и следования хорошим практикам сообщества.
+
+  %p
+    Здоровая критика, дискуссии и предложения по улучшению
+    = link_to "приветствуются.", issues
+
+
+  %h4#filename
+    %a.anchor{ href: "#filename", aria_hidden: "true" }
+    Как назвать файл лога изменений?
+
+  %p
+    Назовите его <code>CHANGELOG.md</code>. Некоторые проекты также используют
+    <code>HISTORY</code>, <code>NEWS</code> или <code>RELEASES</code>.
+
+  %p
+    Хоть и легко подумать, что имя файла лога изменений не так уж и важно,
+    но зачем усложнять вашим конечным пользователям поиск места,
+    где описаны все ключевые изменения?
+
+  %h4#github-releases
+    %a.anchor{ href: "#github-releases", aria_hidden: "true" }
+    Что насчёт функции "Релизы" на Гитхабе?
+
+  %p
+    Это отличная инициатива. #{link_to "Релизы", ghr} могут использоваться
+    для превращения простых тегов в Git (наприме тег <code>v1.0.0</code>)
+    в подробные заметки к релизам с помощью их редактирования вручную,
+    или с помощью комментариев к таким тегам.
+
+  %p
+    Релизы на Гитхабе создают непереносимый лог изменений, который может
+    быть показан пользователям только на самом Гитхабе. Возможно вести
+    их в формате, близком к формату проекта Keep a Changelog, но это требует
+    больших усилий.
+
+  %p
+    Текущая версия Релизов на Гитхабе также возможно не так хорошо видна
+    для конечных пользователей, в отличии от обычных файлов с именами в верхнем
+    регистре (<code>README</code>, <code>CONTRIBUTING</code>, и так далее).
+    Другая небольшая проблема заключается в том, что интерфейс не предлагает
+    ссылок на логи коммитов между релизами.
+
+  %h4#automatic
+    %a.anchor{ href: "#automatic", aria_hidden: "true" }
+    Могут ли логи изменений быть автоматически распарсены?
+
+  %p
+    Это сложно, потому что люди следуют сильно различающимся форматам
+    и используют разные имена файлов.
+
+  %p
+    #{link_to "Vandamme", vandamme} это гем для Руби, созданный командой
+    #{link_to "Gemnasium", gemnasium}, который парсит многие (но не все)
+    логи изменений проектов с открытым исходным кодом.
+
+
+  %h4#yanked
+    %a.anchor{ href: "#yanked", aria_hidden: "true" }
+    Что насчёт yanked-релизов?
+
+  %p
+    Yanked-релизы – это версии, которые изымаются из обращения из-за серьёзного
+    бага или проблемы безопасности в них. Часто такие версии даже не упоминаются
+    в логах изменений. А должны. И вот как вам следует их упоминать:
+
+  %p <code>## 0.0.5 - 2014-12-13 [YANKED]</code>
+
+  %p
+    Тег <code>[YANKED]</code> так бросается в глаза специально. Очень важно,
+    чтобы люди его заметели. Так как он обрамлён квадратными скобками,
+    его также проще распарсить программно.
+
+
+  %h4#rewrite
+    %a.anchor{ href: "#rewrite", aria_hidden: "true" }
+    Имеет ли смысл переписывать лог изменений?
+
+  %p
+    Конечно. Всегда есть веские причины для улучшения лога изменений.
+    Я регулярно открываю пулл-реквесты по добавлению недостающих релизов
+    в проекты с открытым исходным кодом с брошенными логами изменений.
+
+  %p
+    Также возможно вы можете обнаружить, что вы забыли указать критичное
+    изменение в замечаниям к версии. В этом случае очевидно вам важно
+    обновить ваш лог изменений.
+
+  %h4#contribute
+    %a.anchor{ href: "#contribute", aria_hidden: "true" }
+    Как я могу помочь вашему проекту?
+
+  %p
+    Этот документ <strong>не истина в последней инстанции</strong>; это моё
+    тщательно обдуманное мнение, вместе с информацией и примерами, которые я собрал.
+
+  %p
+    Дело в том, что я хочу, чтобы наше сообщество достигло согласия в этом вопросе.
+    Я верю, что дискуссия также важна, как и конечный результат.
+
+  %p
+    Так что, пожалуйста, <strong>#{link_to "участвуйте", gh}</strong>.
+
+.press
+  %h3 Обсуждения
+  %p
+    Я приходил в #{link_to "подкаст The Changelog", thechangelog},
+    чтобы поговорить о том, почему мейнтейнеры и контрьбьюторы долны вести логи изменений,
+    а также о моей мотивации к созданию этого проекта.

source/zh-CN/1.0.0/index.html.haml

@@ -0,0 +1,285 @@
+---
+description: 如何维护更新日志
+title: 如何维护更新日志
+language: zh-CN
+version: 1.0.0
+---
+
+- changelog = "https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.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/"
+- iso = "http://www.iso.org/iso/home/standards/iso8601.htm"
+- ghr = "https://help.github.com/articles/creating-releases/"
+
+.header
+  .title
+    %h1 如何维护更新日志
+    %h2 更新日志绝对不应该是git日志的堆砌物
+
+  = link_to changelog do
+    Version
+    %strong= current_page.metadata[:page][:version]
+
+  %pre.changelog= File.read("CHANGELOG.md")
+
+.answers
+  %h3#what
+    %a.anchor{ href: "#what", aria_hidden: "true" }
+    更新日志是什么？
+
+  %p
+    更新日志（Change Log）是一个由人工编辑，以时间为倒叙的列表，
+    以记录一个项目中所有版本的显著变动。
+
+  %h3#why
+    %a.anchor{ href: "#why", aria_hidden: "true" }
+    为何要提供更新日志？
+
+  %p
+    为了让用户和开发人员更简单明确的知晓项目在不同版本之间有哪些显著变动。
+
+  %h3#who
+    %a.anchor{ href: "#who", aria_hidden: "true" }
+    哪些人需要更新日志？
+
+  %p
+    人人需要更新日志。无论是消费者还是开发者，软件的最终用户都关心软件所包含什么。
+    当软件有所变动时，大家希望知道改动是为何、以及如何进行的。
+
+.good-practices
+  %h3#how
+    %a.anchor{ href: "#how", aria_hidden: "true" }
+    怎样制作高质量的更新日志？
+
+  %h4#principles
+    %a.anchor{ href: "#principles", aria_hidden: "true" }
+    指导原则
+
+  %ul
+    %li
+      记住日志是写给<em>人</em>的，而非机器。
+    %li
+      每个版本都应该有独立的入口。
+    %li
+      同类改动应该分组放置。
+    %li
+      版本与章节应该相互对应。
+    %li
+      新版本在前，旧版本在后。
+    %li
+      应包括每个版本的发布日期。
+    %li
+      注明是否遵守#{link_to "语义化版本格式", semver}.
+
+  %a.anchor{ href: "#types", aria_hidden: "true" }
+  %h4#types 变动类型
+
+  %ul
+    %li
+      %code Added
+      新添加的功能。
+    %li
+      %code Changed
+      对现有功能的变更。
+    %li
+      %code Deprecated
+      已经不建议使用，准备很快移除的功能。
+    %li
+      %code Removed
+      已经移除的功能。
+    %li
+      %code Fixed
+      对bug的修复
+    %li
+      %code Security
+      对安全的改进
+
+.effort
+
+  %h3#effort
+    %a.anchor{ href: "#effort", aria_hidden: "true" }
+    如何减少维护更新日志的精力？
+
+  %p
+    在文档最上方提供 <code>Unreleased</code> 区块以记录即将发布的更新内容。
+
+  %p 这样有两大意义：
+
+  %ul
+    %li
+      大家可以知道在未来版本中可能会有哪些变更
+    %li
+      在发布新版本时，可以直接将<code>Unreleased</code>区块中的内容移动至新发
+      布版本的描述区块就可以了
+
+.bad-practices
+  %h3#bad-practices
+    %a.anchor{ href: "#bad-practices", aria_hidden: "true" }
+    有很糟糕的更新日志吗？
+    
+  %p 当然有，下面就是一些糟糕的方式。
+  
+  %h4#log-diffs
+    %a.anchor{ href: "#log-diffs", aria_hidden: "true" }
+    使用git日志
+
+  %p
+    使用git日志作为更新日志是个非常糟糕的方式：git日志充满各种无意义的信息，
+    如合并提交、语焉不详的提交标题、文档更新等。
+
+  %p
+    提交的目的是记录源码的演化。
+    一些项目会清理提交记录，一些则不会。
+
+  %p
+    更新日志的目的则是记录重要的变更以供最终受众阅读，而记录范围通常涵盖多次提交。
+    
+  %h4#ignoring-deprecations
+    %a.anchor{ href: "#ignoring-deprecations", aria_hidden: "true" }
+    无视即将弃用功能
+    
+  %p
+    当从一个版本升级至另一个时，人们应清楚（尽管痛苦）的知道哪些部分将出现问题。
+    应该允许先升级至一个列出哪些功能将会被弃用的版本，待去掉那些不再支持的部分后，
+    再升级至把那些弃用功能真正移除的版本。
+    
+  %p
+    即使其他什么都不做，也要在更新日志中列出derecations，removals以及其他重大变动。
+    
+  %h4#confusing-dates
+    %a.anchor{ href: "#confusing-dates", aria_hidden: "true" }
+    易混淆的日期格式
+
+  %p
+    在美国，人们将月份写在日期的起始(<code>06-02-2012</code>对应2012年6月2日)，
+    与此同时世界上其他地方的很多人将至写作<code>2 June 2012</code>，并拥有不同发音。
+    <code>2012-06-02</code>从大到小的排列符合逻辑，并不与其他日期格式相混淆，而且还
+    符合#{link_to "ISO标准", iso}。因此，推荐在更新日志中采用使用此种日期格式。
+
+  %aside
+    还有更多内容。请通过
+    = link_to "发布问题", issues
+    或发布pull请求帮助我收集更多异常模式。
+
+.frequently-asked-questions
+  %h3#frequently-asked-questions
+    %a.anchor{ href: "#frequently-asked-questions", aria_hidden: "true" }
+    常见问题
+    
+  %h4#standard
+    %a.anchor{ href: "#standard", aria_hidden: "true" }
+    是否有一个标准化的更新日志格式？
+
+  %p
+    并没有。虽然GNU提供了更新日志样式指引，以及那个仅有两段长的GNU NEWS文件“指南”，
+    但两者均远远不够。
+
+  %p
+    此项目意在提供一个
+    = link_to "更好的更新日志惯例", changelog
+    所有点子都来自于在开源社区中对优秀实例的观察与记录。
+
+  %p
+    对于所有建设性批评、讨论及建议，我们都非常
+    = link_to "欢迎。", issues
+
+
+  %h4#filename
+    %a.anchor{ href: "#filename", aria_hidden: "true" }
+    更新日志文件应被如何命名？
+
+  %p
+    可以叫做<code>CHANGELOG.md</code>。 一些项目也使用
+    <code>HISTORY</code>、<code>NEWS</code>或<code>RELEASES</code>。
+
+  %p
+    当然，你可以认为更新日志的名字并不是什么要紧事，但是为什么要为难那些仅仅是
+    想看到都有哪些重大变更的最终用户呢？
+
+  %h4#github-releases
+    %a.anchor{ href: "#github-releases", aria_hidden: "true" }
+    对于GitHub发布呢？
+    
+  %p
+    这是个非常好的倡议。#{link_to "Releases", ghr}可通过手动添加发布日志或将带
+    有注释的git标签信息抓取后转换的方式，将简单的git标签（如一个叫<code>v1.0.0</code>的标签）
+    转换为信息丰富的发布日志。
+
+  %p
+    GitHub发布会创建一个非便携、仅可在GitHub环境下显示的更新日志。尽管会花费更
+    多时间，但将之处理成更新日志格式是完全可能的。
+
+  %p
+    现行版本的GitHub发布不像哪些典型的大写文件(<code>README</code>, 
+    <code>CONTRIBUTING</code>, etc.)，仍可以认为是不利于最终用户探索的。
+    另一个小问题则是界面并不提供不同版本间commit日志的链接。
+
+  %h4#automatic
+    %a.anchor{ href: "#automatic", aria_hidden: "true" }
+    更新日志可以被自动识别吗？
+
+  %p
+    非常困难，因为有各种不同的文件格式和命名。
+    
+
+  %p
+    #{link_to "Vandamme", vandamme} 是一个Ruby程序，由
+    #{link_to "Gemnasium", gemnasium} 团队制作，可以解析多种
+    （但绝对不是全部）开源库的更新日志。
+
+
+  %h4#yanked
+    %a.anchor{ href: "#yanked", aria_hidden: "true" }
+    那些后来撤下的版本怎么办？
+    
+  %p
+    因为各种安全/重大bug原因被撤下的版本被标记'YANKED'。
+    这些版本一般不出现在更新日志里，但建议他们出现。
+    显示方式应该是：
+
+  %p <code>## 0.0.5 - 2014-12-13 [YANKED]</code>
+
+  %p
+    <code>[YANKED]</code> 的标签应该非常醒目。
+    人们应该非常容易就可以注意到他。
+    并且被方括号所包围也使其更易被程序识别。
+
+
+  %h4#rewrite
+    %a.anchor{ href: "#rewrite", aria_hidden: "true" }
+    是否可以重写更新日志？
+
+  %p
+    当然可以。总会有多种多样的原因需要我们去改进更新日志。
+    对于那些有着未维护更新日志的开源项目，我会定期打开pull请求以加入缺失的发布信息。
+
+  %p
+    另外，很有可能你发现自己忘记记录一个重大功能更新。这种情况下显然你应该去重写更新日志。
+    It's also possible you may discover that you forgot to address a
+    breaking change in the notes for a version. It's obviously important
+    for you to update your changelog in this case.
+
+
+  %h4#contribute
+    %a.anchor{ href: "#contribute", aria_hidden: "true" }
+    如何贡献？
+
+  %p
+    本文档并非<strong>真理</strong>。而是我深思熟虑后的建议，以及我收集的信息与典例。
+
+  %p
+    我希望我们的社区可以对此达成一直。我相信讨论的过程与最终结果一样重要。
+
+  %p
+    所以欢迎<strong>#{link_to "贡献", gh}</strong>.
+
+.press
+  %h3 访谈
+  %p
+    我在#{link_to "更新日志播客", thechangelog}上讲述了为何维护者与贡献者应关心更新日志，
+    以及支持我进行此项目的诸多因素。