From e8602923dd7393c64d894e8d8cc808b0e01972a7 Mon Sep 17 00:00:00 2001 From: Olivier Lacan Date: Mon, 16 May 2016 15:20:26 +0200 Subject: [PATCH 01/24] Start versioning from 0.3.0 This requires moving every current translation into a 0.3.0/ directory and doing some default redirection when people hit keepachangelog.com they should always be redirected to the latest version. Currently that's hardcoded to 0.3.0 but we're going to surely use something akin to a version.rb to define that and use it across the codebase. --- Gemfile | 6 +-- Gemfile.lock | 10 ++++- config.rb | 22 +++++++++- routes.rb | 1 + source/{ => 0.3.0}/de/index.haml | 15 ++++--- source/{ => 0.3.0/en}/index.haml | 5 ++- source/{ => 0.3.0}/es-ES/index.haml | 13 +++--- source/{ => 0.3.0}/pt-BR/index.haml | 5 ++- source/{ => 0.3.0}/ru/index.haml | 7 +++- source/{ => 0.3.0}/zh-CN/index.haml | 63 +++++++++++++++-------------- source/{ => 0.3.0}/zh-TW/index.haml | 63 +++++++++++++++-------------- source/layouts/layout.haml | 10 ++--- 12 files changed, 133 insertions(+), 87 deletions(-) create mode 100644 routes.rb rename source/{ => 0.3.0}/de/index.haml (97%) rename source/{ => 0.3.0/en}/index.haml (98%) rename source/{ => 0.3.0}/es-ES/index.haml (98%) rename source/{ => 0.3.0}/pt-BR/index.haml (98%) rename source/{ => 0.3.0}/ru/index.haml (98%) rename source/{ => 0.3.0}/zh-CN/index.haml (97%) rename source/{ => 0.3.0}/zh-TW/index.haml (97%) diff --git a/Gemfile b/Gemfile index b7b55a4..f4e149a 100644 --- a/Gemfile +++ b/Gemfile @@ -1,12 +1,12 @@ source "https://rubygems.org" gem "addressable" -gem "middleman", "~>3.4.0" +gem "middleman", "~> 3.4.0" gem "middleman-autoprefixer" gem "middleman-blog" gem "middleman-livereload" gem "middleman-minify-html" gem "middleman-syntax" -gem 'middleman-gh-pages' - +gem "middleman-gh-pages" gem "redcarpet" +gem "pry" diff --git a/Gemfile.lock b/Gemfile.lock index e8d5df9..7b4ed17 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -18,6 +18,7 @@ GEM rack-test (>= 0.5.4) xpath (~> 2.0) chunky_png (1.3.4) + coderay (1.1.1) coffee-script (2.4.1) coffee-script-source execjs @@ -54,6 +55,7 @@ GEM listen (3.0.3) rb-fsevent (>= 0.9.3) rb-inotify (>= 0.9) + method_source (0.8.2) middleman (3.4.0) coffee-script (~> 2.2) compass (>= 1.0.0, < 2.0.0) @@ -113,6 +115,10 @@ GEM tilt (~> 1.4.1) padrino-support (0.12.5) activesupport (>= 3.1) + pry (0.10.3) + coderay (~> 1.1.0) + method_source (~> 0.8.1) + slop (~> 3.4) rack (1.6.4) rack-livereload (0.3.16) rack @@ -125,6 +131,7 @@ GEM redcarpet (3.3.3) rouge (1.10.1) sass (3.4.19) + slop (3.6.0) sprockets (2.12.4) hike (~> 1.2) multi_json (~> 1.0) @@ -159,7 +166,8 @@ DEPENDENCIES middleman-livereload middleman-minify-html middleman-syntax + pry redcarpet BUNDLED WITH - 1.10.6 + 1.12.0.rc diff --git a/config.rb b/config.rb index 3222dca..02c551c 100644 --- a/config.rb +++ b/config.rb @@ -3,12 +3,32 @@ # -------------------------------------- # ----- Site ----- # +$last_version = "0.3.0" +$languages = { + de: "Deutsch", + en: "English", + "es-ES" => "Español", + "pt-BR" => "Brazilian Portugese", + ru: "Pyccкий", + "zh-CN" => "简体中文", + "zh-TW" => " 繁體中文" +} + +activate :i18n, + lang_map: $languages, + mount_at_root: :en -activate :i18n, langs: [:en, 'es-ES', 'pt-BR', :ru, 'zh-CN', 'zh-TW'], :mount_at_root => :en set :gauges_id, '' set :publisher_url, 'https://www.facebook.com/olivier.lacan.5' set :site_url, 'http://keepachangelog.com' +redirect "index.html", to: "#{$last_version}/en/index.html" + +$languages.each do |language| + language_param = language.last.parameterize + redirect "#{language.first}/", to: "#{$last_version}/#{language.first}/" +end + # ----- Assets ----- # set :css_dir, 'assets/stylesheets' diff --git a/routes.rb b/routes.rb new file mode 100644 index 0000000..9be1991 --- /dev/null +++ b/routes.rb @@ -0,0 +1 @@ +redirect "/", to: "/0.3.0/" diff --git a/source/de/index.haml b/source/0.3.0/de/index.haml similarity index 97% rename from source/de/index.haml rename to source/0.3.0/de/index.haml index 5e673f4..86096cb 100644 --- a/source/de/index.haml +++ b/source/0.3.0/de/index.haml @@ -2,6 +2,7 @@ description: Keep a Changelog title: Keep a Changelog language: de +version: 0.3.0 --- :markdown @@ -9,15 +10,17 @@ language: de ## Lass deine Freunde nicht CHANGELOGs mit git logs füllen™ + Version **#{current_page.metadata[:page]["version"]}** + ### Was ist ein Changelog? Ein Changelog ist eine Datei, welche eine nachgeführte, chronologisch sortierte Liste aller relevanten Änderungen für jede Version eines Projektes enthält. -%pre.changelog= File.read(File.expand_path("../../../CHANGELOG.md", __FILE__)) +%pre.changelog= File.read(File.join(root_path, "README.md")) :markdown ### Was ist der Zweck eines Changelogs? - Es für Benutzer und Entwickler einfacher zu machen, die relevanten Änderungen, welche + Es für Benutzer und Entwickler einfacher zu machen, die relevanten Änderungen, welche zwischen Releases (oder Versionen) des Projekts gemacht wurden, zu sehen. ### Warum sollte ich mich darum kümmern? @@ -84,7 +87,7 @@ language: de Es ist sicher nichts falsch daran, naiv zu zu sein, aber beim Verfassen eines Leitfadens ist es nicht wirklich hilfreich. Vor allem nicht, wenn es viele Spezialfälle zu beachten gibt. - Dieses Projekt [enthält das, wovon ich hoffe, dass es zu einer besseren CHANGELOG-Datei-Konvention][CHANGELOG] + Dieses Projekt [enthält das, wovon ich hoffe, dass es zu einer besseren CHANGELOG-Datei-Konvention][CHANGELOG] wird. Ich glaube nicht, dass der status quo gut genug ist, und ich denke, dass wir als Community eine bessere Konvention entwickeln können, wenn wir Bewährtes aus echten Software-Projekten entnehmen. Schau dich um und denk daran, dass @@ -101,8 +104,8 @@ language: de ### Wieso sollte man nicht einfach ein `git log` Diff verwenden? Weil log Diffs voller unnötiger Information sind - von Natur aus. Sie wären nicht - einmal ein geeignetes Changelog in einem hypothetischen Projekt, welches von perfekten - Menschen geführt wird, welche sich niemals vertippen, niemals vergessen, neue Dateien + einmal ein geeignetes Changelog in einem hypothetischen Projekt, welches von perfekten + Menschen geführt wird, welche sich niemals vertippen, niemals vergessen, neue Dateien zu comitten und nie einen Teil eines Refactorings übersehen. Der Zweck eines Commits ist es, einen atomaren Schritt eines Prozesses zu dokumentieren, welcher den Code von einem Zustand in den nächsten bringt. Der Zweck eines Changelogs @@ -127,7 +130,7 @@ language: de Die Grossschreibung (welche in alten Betriebssystemen dafür gesorgt hat, dass die Dateien zuerst aufgelistet wurden) wird verwendet, um die Aufmerksamkeit - auf diese Dateien zu lenken. Da sie wichtige Metadaten über das Projekt enthalten, + auf diese Dateien zu lenken. Da sie wichtige Metadaten über das Projekt enthalten, können sie wichtig für jeden sein, der das Projekt gerne benutzen oder mitentwickeln möchte, ähnlich wie [Open-Source-Projekt-Badges][shields]. diff --git a/source/index.haml b/source/0.3.0/en/index.haml similarity index 98% rename from source/index.haml rename to source/0.3.0/en/index.haml index 3493069..919c945 100644 --- a/source/index.haml +++ b/source/0.3.0/en/index.haml @@ -2,6 +2,7 @@ description: Keep a Changelog title: Keep a Changelog language: en +version: 0.3.0 --- :markdown @@ -9,11 +10,13 @@ language: en ## Don’t let your friends dump git logs into CHANGELOGs™ + Version **#{current_page.metadata[:page]["version"]}** + ### What’s a change log? A change log is a file which contains a curated, chronologically ordered list of notable changes for each version of a project. -%pre.changelog= File.read(File.expand_path("../../CHANGELOG.md", __FILE__)) +%pre.changelog= File.read(File.join(root_path, "README.md")) :markdown ### What’s the point of a change log? diff --git a/source/es-ES/index.haml b/source/0.3.0/es-ES/index.haml similarity index 98% rename from source/es-ES/index.haml rename to source/0.3.0/es-ES/index.haml index e246fc4..fa556a0 100644 --- a/source/es-ES/index.haml +++ b/source/0.3.0/es-ES/index.haml @@ -2,6 +2,7 @@ description: Mantenga un Changelog title: Mantenga un Changelog language: es-ES +version: 0.3.0 --- :markdown @@ -9,11 +10,13 @@ language: es-ES ## No dejes que tus amigos copien y peguen git logs en los CHANGELOGs™ + Version **#{current_page.metadata[:page]["version"]}** + ### 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__)) +%pre.changelog= File.read(File.join(root_path, "README.md")) :markdown ### Cuál es el propósito del change log? @@ -69,12 +72,12 @@ language: es-ES 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? @@ -89,7 +92,7 @@ language: es-ES ### 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. @@ -108,7 +111,7 @@ language: es-ES ### 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. diff --git a/source/pt-BR/index.haml b/source/0.3.0/pt-BR/index.haml similarity index 98% rename from source/pt-BR/index.haml rename to source/0.3.0/pt-BR/index.haml index bbedfd1..842be29 100644 --- a/source/pt-BR/index.haml +++ b/source/0.3.0/pt-BR/index.haml @@ -2,6 +2,7 @@ description: Mantenha um CHANGELOG title: Mantenha um CHANGELOG language: pt-BR +version: 0.3.0 --- :markdown @@ -9,13 +10,15 @@ language: pt-BR ## Não deixe seus amigos despejar logs de commits em CHANGELOGs™ + Version **#{current_page.metadata[:page]["version"]}** + ### O que é um change log? Um *change log* é um arquivo que contém uma lista selecionada, ordenada cronologicamente de mudanças significativas para cada versão de um projeto open source. -%pre.changelog= File.read(File.expand_path("../../../CHANGELOG.md", __FILE__)) +%pre.changelog= File.read(File.join(root_path, "README.md")) :markdown ### Para que serve um *change log*? diff --git a/source/ru/index.haml b/source/0.3.0/ru/index.haml similarity index 98% rename from source/ru/index.haml rename to source/0.3.0/ru/index.haml index 311199e..5282c4a 100644 --- a/source/ru/index.haml +++ b/source/0.3.0/ru/index.haml @@ -2,6 +2,7 @@ description: Ведите Changelog title: Ведите Changelog language: ru +version: 0.3.0 --- :markdown @@ -9,13 +10,15 @@ language: ru ## Не позволяйте друзьям сливать логи гита в CHANGELOG™ + Version **#{current_page.metadata[:page]["version"]}** + ### Что такое лог изменений? Лог изменений – это файл, который содержит поддерживаемый, упорядоченный в хронологическом порядке список значимых изменений для каждой версии проекта с открытым исходным кодом. -%pre.changelog= File.read(File.expand_path("../../../CHANGELOG.md", __FILE__)) +%pre.changelog= File.read(File.join(root_path, "README.md")) :markdown ### Для чего нужен лог изменений? @@ -92,7 +95,7 @@ language: ru [стандартом ISO](http://www.iso.org/iso/home/standards/iso8601.htm). Таким образом, этот формат является рекомендуемым для логов изменений. - Существуют и другие. Помогите мне собрать слёзы единорогов, + Существуют и другие. Помогите мне собрать слёзы единорогов, [открыв тикет][issues] или пулл-реквест. ### Существует стандарт формата лога изменений? diff --git a/source/zh-CN/index.haml b/source/0.3.0/zh-CN/index.haml similarity index 97% rename from source/zh-CN/index.haml rename to source/0.3.0/zh-CN/index.haml index 18ac099..b258f3e 100644 --- a/source/zh-CN/index.haml +++ b/source/0.3.0/zh-CN/index.haml @@ -2,6 +2,7 @@ description: 如何维护更新日志 title: 如何维护更新日志 language: zh-CN +version: 0.3.0 --- :markdown @@ -9,21 +10,23 @@ language: zh-CN ## 更新日志绝对不应该是git日志的堆砌物 + Version **#{current_page.metadata[:page]["version"]}** + ### 更新日志是什么？ 更新日志（Change Log）是一个由人工编辑，以时间为倒叙的列表。 这个列表记录所有版本的重大变动。 -%pre.changelog= File.read(File.expand_path("../../../CHANGELOG.md", __FILE__)) +%pre.changelog= File.read(File.join(root_path, "README.md")) :markdown ### 为何要提供更新日志？ 为了让用户和开发人员更好知道每一个版本有哪些区别。 - + ### 为何我要在乎呢？ 因为归根结底软件是为人提供的。既然你不关心人，哪么为何写软件呢？ 多少你还是要关心你的受众。 - + 本文档原作者和另外两个人的一个[播客][thechangelog]向大家介绍了， 为何代码的管理者和开发者应该在乎更新日志。如果你有一小时时间和很好的英文听力本领， 不放听听。 @@ -32,7 +35,7 @@ language: zh-CN 好问题！ 一个好的更新日志，一定满足： - + - 给人而不是机器写的。记住，要说人话。 - 快速跳转到任意段。所以采用markdown格式 - 一个版本对应一个章节。 @@ -49,88 +52,88 @@ language: zh-CN - 'Removed' 之前不建议使用的功能，这次真的删掉了 - 'Fixed' 改的bug - 'Security' 改的有关安全相关bug - - + + ### 怎么尽可能减少耗费的精力？ 永远在文档最上方提供一个'Unreleased' 未发布区域，来记录当前的变化。 这佯作有两大意义。 - + - 大家可以看到接下来会有什么变化 - 在发布时，只要把'Unreleased'改为当前版本号，然后再添加一个新的'Unreleased'就行了 - + ### 吐槽环节到了 请你一定要注意： - + - **把git日志扔到更新日志里。**看似有用，然并卵。 - **不写'deprecations'就删功能。**不带这样坑队友的。 - **采用各种不靠谱日期格式** 2012年12月12日，也就中国人能看懂了。 - + 如果你还有要吐槽的，欢迎留[issue][issues]或者直接PR - + ### 世界上不是有标准的更新日志格式吗？ 貌似GNU或者GNU NEWS还是提过些规范的，事实是它们太过简陋了。 开发有那么多中情况，采用那样的规范，确实是不太合适的。 - + 这个项目提供的[规范][CHANGELOG]是作者本人希望能够成为世界规范的。 作者不认为当前的标准足够好，而且作为一个社区，我们是有能力提供更棒的规范。 如果你对这个规范有不满的地方，不要忘记还可以[吐槽][issues]呢。 - + ### 更新日志文件名应该叫什么？ 我们的案例中给的名字就是最好的规范：`CHANGELOG.md`，注意大小写。 - + 像`HISTORY.txt`, `HISTORY.md`, `History.md`, `NEWS.txt`, `NEWS.md`, `News.txt`, `RELEASES.txt`, `RELEASE.md`, `releases.md`这么 多文件名就太不统一了。 - + 只会让大家更难找到。 - + ### 为何不直接记录`git log`? 因为git日志一定是乱糟糟的。哪怕一个最理想的由完美的程序员开发的提交的，哪怕一个 从不忘记每次提交全部文件，不写错别字，不忘记重构每一个部分——也无法保证git日志完美无瑕。 况且git日志的核心在于记录代码的演化，而更新日志则是记录最重要的变更。 - + 就像注释之于代码，更新日志之于git日志。前者解释*为什么*，而后者说明*发生了什么*。 ### 更新日志能机器识别吗？ 非常困难，因为有各种不同的文件格式和其他规范。 - + [Vandamme][vandamme]是一个Ruby程序（由[Gemnasium][gemnasium]团队制作），可以解析 好多种（但绝对不是全部）开源库的更新日志。 - + ### 到底是CHANGELOG还是更新日志 - + CHANGELOG是文件名，更新日志是常用说法。CHANGELOG采用大写是有历史根源的。就像很多类似的文件 [`README`][README]， [`LICENSE`][LICENSE]，还有[`CONTRIBUTING`][CONTRIBUTING]。 - + 采用大写可以更加显著，毕竟这是项目很重要的元信息。就像[开源徽章][shields]。 - + ### 那些后来撤下的版本怎么办？ 因为各种安全/重大bug原因被撤下的版本被标记'YANKED'。这些版本一般不出现在更新日志里，但作者建议他们出现。 显示方式应该是： - + `## 0.0.5 - 2014-12-13 [YANKED]` - + `[YANKED]`采用大写更加显著，因为这个信息很重要。而采用方括号则容易被程序解析。 - + ### 是否可以重写更新日志 当然。哪怕已经上线了，也可以重新更新更新日志。有许多开源项目更新日志不够新，所以作者就会帮忙更新。 - + 另外，很有可能你忘记记录一个重大功能更新。所以这时候应该去重写更新日志。 - + ### 如何贡献？ 本文档并不是**真理**。这只是原作者的个人建议，并且包括许多收集的例子。 哪怕[本开源库][gh]提供一个[更新日志案例][CHANGELOG]，我刻意没有提供一个 过于苛刻的规则列表（不像[语义化版本格式][semver]）。 - + 这是因为我希望通过社区达到统一观点，我认为中间讨论的过程与结果一样重要。 - + 所以[欢迎贡献][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 diff --git a/source/zh-TW/index.haml b/source/0.3.0/zh-TW/index.haml similarity index 97% rename from source/zh-TW/index.haml rename to source/0.3.0/zh-TW/index.haml index 3099b3a..30fe43c 100644 --- a/source/zh-TW/index.haml +++ b/source/0.3.0/zh-TW/index.haml @@ -2,6 +2,7 @@ description: 如何維護更新日誌 title: 如何維護更新日誌 language: zh-TW +version: 0.3.0 --- :markdown @@ -9,21 +10,23 @@ language: zh-TW ## 更新日誌絕對不應該是git日誌的堆砌物 + Version **#{current_page.metadata[:page]["version"]}** + ### 更新日誌是什麽？ 更新日誌（Change Log）是壹個由人工編輯，以時間為倒敘的列表。 這個列表記錄所有版本的重大變動。 -%pre.changelog= File.read(File.expand_path("../../../CHANGELOG.md", __FILE__)) +%pre.changelog= File.read(File.join(root_path, "README.md")) :markdown ### 為何要提供更新日誌？ 為了讓用戶和開發人員更好知道每壹個版本有哪些區別。 - + ### 為何我要在乎呢？ 因為歸根結底軟件是為人提供的。既然妳不關心人，哪麽為何寫軟件呢？ 多少妳還是要關心妳的受眾。 - + 本文檔原作者和另外兩個人的壹個[播客][thechangelog]向大家介紹了， 為何代碼的管理者和開發者應該在乎更新日誌。如果妳有壹小時時間和很好的英文聽力本領， 不放聽聽。 @@ -32,7 +35,7 @@ language: zh-TW 好問題！ 壹個好的更新日誌，壹定滿足： - + - 給人而不是機器寫的。記住，要說人話。 - 快速跳轉到任意段。所以采用markdown格式 - 壹個版本對應壹個章節。 @@ -49,88 +52,88 @@ language: zh-TW - 'Removed' 之前不建議使用的功能，這次真的刪掉了 - 'Fixed' 改的bug - 'Security' 改的有關安全相關bug - - + + ### 怎麽盡可能減少耗費的精力？ 永遠在文檔最上方提供壹個'Unreleased' 未發布區域，來記錄當前的變化。 這佯作有兩大意義。 - + - 大家可以看到接下來會有什麽變化 - 在發布時，只要把'Unreleased'改為當前版本號，然後再添加壹個新的'Unreleased'就行了 - + ### 吐槽環節到了 請妳壹定要註意： - + - **把git日誌扔到更新日誌裏。**看似有用，然並卵。 - **不寫'deprecations'就刪功能。**不帶這樣坑隊友的。 - **采用各種不靠譜日期格式** 2012年12月12日，也就中國人能看懂了。 - + 如果妳還有要吐槽的，歡迎留[issue][issues]或者直接PR - + ### 世界上不是有標準的更新日誌格式嗎？ 貌似GNU或者GNU NEWS還是提過些規範的，事實是它們太過簡陋了。 開發有那麽多中情況，采用那樣的規範，確實是不太合適的。 - + 這個項目提供的[規範][CHANGELOG]是作者本人希望能夠成為世界規範的。 作者不認為當前的標準足夠好，而且作為壹個社區，我們是有能力提供更棒的規範。 如果妳對這個規範有不滿的地方，不要忘記還可以[吐槽][issues]呢。 - + ### 更新日誌文件名應該叫什麽？ 我們的案例中給的名字就是最好的規範：`CHANGELOG.md`，註意大小寫。 - + 像`HISTORY.txt`, `HISTORY.md`, `History.md`, `NEWS.txt`, `NEWS.md`, `News.txt`, `RELEASES.txt`, `RELEASE.md`, `releases.md`這麽 多文件名就太不統壹了。 - + 只會讓大家更難找到。 - + ### 為何不直接記錄`git log`? 因為git日誌壹定是亂糟糟的。哪怕壹個最理想的由完美的程序員開發的提交的，哪怕壹個 從不忘記每次提交全部文件，不寫錯別字，不忘記重構每壹個部分——也無法保證git日誌完美無瑕。 況且git日誌的核心在於記錄代碼的演化，而更新日誌則是記錄最重要的變更。 - + 就像註釋之於代碼，更新日誌之於git日誌。前者解釋*為什麽*，而後者說明*發生了什麽*。 ### 更新日誌能機器識別嗎？ 非常困難，因為有各種不同的文件格式和其他規範。 - + [Vandamme][vandamme]是壹個Ruby程序（由[Gemnasium][gemnasium]團隊制作），可以解析 好多種（但絕對不是全部）開源庫的更新日誌。 - + ### 到底是CHANGELOG還是更新日誌 - + CHANGELOG是文件名，更新日誌是常用說法。CHANGELOG采用大寫是有歷史根源的。就像很多類似的文件 [`README`][README]， [`LICENSE`][LICENSE]，還有[`CONTRIBUTING`][CONTRIBUTING]。 - + 采用大寫可以更加顯著，畢竟這是項目很重要的元信息。就像[開源徽章][shields]。 - + ### 那些後來撤下的版本怎麽辦？ 因為各種安全/重大bug原因被撤下的版本被標記'YANKED'。這些版本壹般不出現在更新日誌裏，但作者建議他們出現。 顯示方式應該是： - + `## 0.0.5 - 2014-12-13 [YANKED]` - + `[YANKED]`采用大寫更加顯著，因為這個信息很重要。而采用方括號則容易被程序解析。 - + ### 是否可以重寫更新日誌 當然。哪怕已經上線了，也可以重新更新更新日誌。有許多開源項目更新日誌不夠新，所以作者就會幫忙更新。 - + 另外，很有可能妳忘記記錄壹個重大功能更新。所以這時候應該去重寫更新日誌。 - + ### 如何貢獻？ 本文檔並不是**真理**。這只是原作者的個人建議，並且包括許多收集的例子。 哪怕[本開源庫][gh]提供壹個[更新日誌案例][CHANGELOG]，我刻意沒有提供壹個 過於苛刻的規則列表（不像[語義化版本格式][semver]）。 - + 這是因為我希望通過社區達到統壹觀點，我認為中間討論的過程與結果壹樣重要。 - + 所以[歡迎貢獻][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 diff --git a/source/layouts/layout.haml b/source/layouts/layout.haml index 38e0140..bddd972 100644 --- a/source/layouts/layout.haml +++ b/source/layouts/layout.haml @@ -31,13 +31,9 @@ %header{role: "banner"} %nav.locales{role: "navigation"} %ul - %li= link_to 'english [en]', '/', {rel: "alternate", lang: "en", hreflang: "en"} - %li= link_to 'español [es-ES]', '/es-ES/', {rel: "alternate", lang: "es-ES", hreflang: "es-ES"} - %li= link_to 'português brasileiro [pt-BR]', '/pt-BR/', {rel: "alternate", lang: "pt-BR", hreflang: "pt-BR"} - %li= link_to 'pyccкий [ru]', '/ru/', {rel: "alternate", lang: "ru", hreflang: "ru"} - %li= link_to '简体中文 [zh-CN]', '/zh-CN/', {rel: "alternate", lang: "zh-CN", hreflang: "zh-CN"} - %li= link_to '繁體中文 [zh-TW]', '/zh-TW/', {rel: "alternate", lang: "zh-TW", hreflang: "zh-TW"} - %li= link_to 'german [de]', '/de/', {rel: "alternate", lang: "de", hreflang: "de"} + - $languages.each do |language| + %li= link_to "#{language.last} [#{language.first}]", "/#{language.first}/", + { rel: "alternate", lang: "#{language}", hreflang: "#{language}" } .main{role: "main"}= yield From 4a828c8bd6ac0039e91c7c29ca6ee79cec91d342 Mon Sep 17 00:00:00 2001 From: Emre Erkan Date: Mon, 23 May 2016 16:46:26 +0300 Subject: [PATCH 02/24] Added tr-TR translation. --- source/tr-TR/index.haml | 177 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 177 insertions(+) create mode 100644 source/tr-TR/index.haml diff --git a/source/tr-TR/index.haml b/source/tr-TR/index.haml new file mode 100644 index 0000000..e9ba68d --- /dev/null +++ b/source/tr-TR/index.haml @@ -0,0 +1,177 @@ +--- +description: Değişiklik kaydı tutun +title: Değişiklik kaydı tutun +language: tr-TR +--- + +:markdown + # CHANGELOG dosyası kullanın + + ## Arkadaşlarınızın git kayıtlarını CHANGELOG dosyalarına boşaltmasını engelleyin™ + + ### Nedir bu değişiklik kayıtları? + Değişiklik kayıtları bir proje için özel olarak hazırlanmış, tarihsel sıralamayla + sıralanmış, önemli değişikliklerin bir bütünüdür. + +%pre.changelog= File.read(File.expand_path("../../CHANGELOG.md", __FILE__)) + +:markdown + ### Değişikliklerin kayıtlarını tutmanın anlamı ne? + Bir projenin kullanıcılarının ya da katılımcılarının, dağıtımlar (ya da sürümler) + arasındaki tam olarak hangi önemli değişikliklerin olduğunu takip edebilmelerini sağlar. + + ### Neden umrumda olsun ki? + Çünkü yazılım paketleri insanlar içindir. Eğer umrunuzda değilse neden açık kaynağa + katkıda bulunuyorsunuz ki? Mutlaka sevimli beyninizin bir yerlerinde bunu önemseyen + bir çekirdek (a-ha!) vardır. + + [Adam Stacoviak ve Jerod Santo ile Changelog Podcast'inde][thechangelog](uyuyor, + değil mi?) neden geliştiricilerin ve katılımcıların umrunda olması gerektiğini ve + bu projenin arkasındaki motivasyonu konuştuk. Eğer vaktiniz varsa (1:06) iyi bir + söyleşi oldu. + + ### Bir değişiklik kaydını iyi yapan nedir? + Bunu sorduğunuza sevindim. + + İyi bir değişiklik kaydı şu prensiplere bağlıdır: + + - İnsanlar için yapılmıştır, makineler için değil, yani okunurluğu kritik. + - Kolayca bölümler arası bağlantı kurulabilmeli (bu yüzden yalın metin yerine markdown). + - Her sürüm için bir alt bölüm. + - Dağıtımları tersine tarih sırası ile listeleyin (en yeni en üstte). + - Tüm tarihleri `YYYY-AA-GG` biçiminde yazın. (Örneğin `2 Haziran 2012` için `2012-06-02`.) Uluslararasıdır, [anlamlıdır](http://xkcd.com/1179/), ve lisan bağımsızdır. + - [Anlamsal sürümlemeyi][semver] destekleyip desteklemediğini özellikle belirtin. + - Her sürümde olması gerekenler: + - Üstteki biçimde dağıtım tarihi. + - Projeye etkileri bakımından değişiklikleri gruplayın, şöyle ki: + - `Eklendi`: yeni özellikler için. + - `Değişti`: var olan beceriler değiştiyse. + - `Rafa kalktı`: gelecekte yok olacak var olan beceriler. + - `Kaldırıldı`: bu sürümde kaldırılan, daha önce rafa kaldırılmış olan beceriler. + - `Düzeltildi`: ayıklanmış hatalar için. + - `Güvenlik`: açıkları kapatabilmeleri için kullanıcıları bilgilendirin. + + ### Gerekli çabayı nasıl en aza indirebilirim? + Her zaman en üstte değişiklikleri takip ettiğiniz bir `"Yayımlanmadı"` bölümü olsun. + + Bu, iki amaca hizmet eder: + + - İnsanlar gelecek sürümlerde karşılarına ne gibi değişiklikler çıkacağını görebilirler + - Dağıtım zamanı geldiğinde `"Yayımlanmadı"` başlığını sürüm numarası ile değişitip + tepeye yeni bir `"Yayımlanmadı"` bölümü eklemeniz yeterli. + + ### Tek boynuzlu atları ağlatan ne? + Peki… Gelelim sadede. + + - **Commit kayıtlarının farkını yüklemek.** Sakın bunu yapmayın, kimseye yardım etmiyorsunuz. + - **Rafa kalkanları ön plana çıkarmamak.** Kullanıcılar bir sürümden diğerine + yükseltme yaptıklarında neyin bozulabileceği apaçık ortada olmalı. + - **Bölgesel biçimlenmiş tarihler.** ABD'de insanlar ay bilgisini önce kullanıyor + ("06-02-2012" demek 2 Haziran 2012 demek yani, ki tamamen *saçma*), diğer taraftan + dünyanın bir çok bölgesinde "2 Haziran 2012" gibi robotik bir yapı kullanıp farklı + şekilde dile getiriyor. "2012-06-02" hem mantıksal olarak en büyüğünden en küçüğüne çalışıyor, + hem de diğer tarih biçimleriyle çakışmıyor. Aynı zamanda [ISO standardında](http://www.iso.org/iso/home/standards/iso8601.htm). + Bu yüzden değişiklik kayıtları için önerilen tarih biçimidir. + + Dahası da var. Bu tek boynuzlu at gözyaşlarını toplamak için + [bir başlık açın][issues] + ya da bir çekme isteği (pull request) gönderin. + + ### Standart bir değişiklik kaydı biçimi var mı? + Ne yazık ki hayır. Sakin olun. Biliyorum, şu an alelacele GNU değişiklik kaydı + stil rehberi için bağlantı arıyorsunuz, ya da iki paragraflık GNU NEWS dosyasına + bakınıyorsunuz. GNU stil rehberi iyi bir başlangıç fakat üzücü derece naif. + Naif olmakta yanlış bir şey yok, fakat insanlar rehberlik aradığında nadiren + yardımcı oluyorlar. Özellikle ortada uğraşılacak bir çok durum ve uç örnekler + mevcutken. + + Bu proje [umuyorum ki daha iyi CHANGELOG dosyaları için bir altyapı oluşturacak][CHANGELOG]. + Mevcut durumun çok iyi olduğunu düşünmüyorum, ve topluluk olarak, gerçek yazılım + projelerinden iyi pratikleri toplayarak bundan daha iyisini yapabiliriz. Lütfen + etrafa bir göz gezdirin ve unutmayın [gelişme yolunda tartışmalara ve önerilere her zaman açığız][issues]! + + ### Değişiklik kayıtlarının dosya ismi ne olmalı? + Eh, üstteki örnekten çıkartamadıysanız eğer, `CHANGELOG.md` şu ana kadarki + en iyi çözüm. + + Bazı projeler `HISTORY.txt`, `HISTORY.md`, `History.md`, `NEWS.txt`, `NEWS.md`, + `News.txt`, `RELEASES.txt`, `RELEASE.md`, `releases.md` vb de kullanıyor. + + Tam bir karmaşa. Tüm bu isimler insanların bu dosyayı bulmasını zorlaştırıyor. + + ### Neden `git log` farkları kullanılmasın? + Çünkü kayıt farkları bir sürü gürültü içerir - doğal olarak. Mükemmel insanlar + tarafından yürütülen, hiç yazım hatasının yapılmadığı, dosyaların gönderilmesinin + hiç unutulmadığı, refaktör yapılmasının atlanmadığı varsayımsal bir projede bile + uygun bir değişiklik kaydı oluşmayacaktır. Dosyaları repoya göndermenin amacı + atomik seviyede kodun bir durumdan diğerine geçişinin sağlanmasıdır. Değişiklik + kayıtları ise bu durumlar arasında, önem arz eden değişiklikleri belgelemeyi + amaçlıyor. + + İyi yorumla ve kodun kendisi arasındaki fark, + aynı şekilde değişiklik kayıtları ve commit kayıtları arasındaki gibidir: + biri *neden* olduğunu, diğeri nasıl olduğunu açıklar. + + ### Değişiklik kayıtları otomatik olarak toplanabilir mi? + Zor, çünkü insanlar bir çok farklı biçim ve dosya isimleri kullanıyorlar. + + [Vandamme][vandamme], [Gemnasium][gemnasium] ekibi tarafından oluşturulmuş + bir Ruby Gem'idir ve bir çok (hepsini değil) açık kaynaklı projenin değişiklik + kayıtlarını ayrıştırabiliyor. + + ### Neden arada bir "CHANGELOG" ve arada bir "değişiklik kaydı" yazıyorsun? + "CHANGELOG" dosyanın ismi. Biraz fazla şaşalı ama bir çok açık kaynak kodlu + proje tarafından uygulanan tarihi bir gelenek. Benzer dosyalar da var; + [`README`][README], [`LICENSE`][LICENSE], ve [`CONTRIBUTING`][CONTRIBUTING]. + + Büyük harfle isimlendirme (eski işletim sistemlerinde dosyaların tepede + gözükmelerini sağlardı) dikkat çekmek için. Proje hakkında önemli meta verileri + içerdikleri için, kullanmak ya da katkıda bulunmak isteyen herkesin işine + yarar, tıpkı [açık kaynaklı proje rozeleri][shields] gibi. + + "Değişiklik kaydı"ndan bahsettiğim zamanlar bu dosyanın işlevinden bahsediyorum: + Değişiklikleri kaydetmek. + + ### Geri çekilen dağıtımlar? + Geri çekilen dağıtımlar, önemli hatalar ya da güvenlik sebepleri nedeniyle + yayından geri çekilen sürümlerdir. Genelde bu sürümler değişiklik kayıtlarında + görüntülenmezler. Görünmeliler. Tam da şu şekilde görünmeliler: + + `## 0.0.5 - 2014-12-13 [GERİ ÇEKİLDİ]` + + `[GERİ ÇEKİLDİ]` etiketi belirli bir sebepten büyük harf. İnsanların bunu fark + etmeleri çok önemli. Ayrıca köşeli parantezler ile çevrelenmiş olması + programatik olarak da ayrıştırılabilmeine olanak sağlıyor. + + ### Değişiklik kayıtlarınızı tekrar yazmalı mısınız? + Tabii ki. Her zaman değişiklik kayıtlarını geliştirmek için iyi sebepler vardır. + Düzenli olarak açık kaynaklı projelerde bakım yapılmayan değişiklik kayıtları + için çekme istekleri yapıyorum. + + Ayrıca bir sürümdeki notların arasında önemli bir değişiklikten bahsetmeyi + unutmuş olduğunuzu fark edebilirsiniz. Değişiklik kütüğünüzü bu bilgi ışığında + güncellemeniz gerekliliği gün gibi ortada. + + ### Nasıl katkıda bulunabilirim? + Bu belge **doğrunun kendisi** değil; benim hesaplı görüşlerimdir. Beraberinde + toparlamış olduğum bilgiler ve örnekler bulunur. + [GitHub repo][gh]sunda güncel bir [CHANGELOG][] sağlıyor olsam da, özellikle + bir *sürüm* ya da ([SemVer.org][semver] benzeri) takip edilecek kurallar + oluşturmadım. + + Bunu istememin sebebi topluluğun ortak bir paydada buluşmasını istememdir. + İnanıyorum ki tartışmanın kendisi de sonucu kadar önemli. + + Yani lütfen, [**siz de katılın**][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/ From 1fe17fd838d219e34bd28d90bf578a6c7f7129eb Mon Sep 17 00:00:00 2001 From: Olivier Lacan Date: Sun, 5 Jun 2016 17:05:06 +0200 Subject: [PATCH 03/24] Fix language-specific redirects --- config.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/config.rb b/config.rb index 02c551c..be396dc 100644 --- a/config.rb +++ b/config.rb @@ -26,7 +26,7 @@ redirect "index.html", to: "#{$last_version}/en/index.html" $languages.each do |language| language_param = language.last.parameterize - redirect "#{language.first}/", to: "#{$last_version}/#{language.first}/" + redirect "#{language.first}/index.html", to: "#{$last_version}/#{language.first}/index.html" end # ----- Assets ----- # From 9950f8d3956e3b00f2dbbe51dee9441b068100b4 Mon Sep 17 00:00:00 2001 From: Arthur Maltson Date: Fri, 10 Jun 2016 17:15:37 -0400 Subject: [PATCH 04/24] Add link back to keepachangelog.com Usually every time one adds entries to the changelog they forget the format. Making it clear what the format is for the CHANGELOG might help level set any contributors. --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index b4e2b6b..97e34d5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,7 @@ # Change Log All notable changes to this project will be documented in this file. This project adheres to [Semantic Versioning](http://semver.org/). +The format conforms to [keepachangelog.com](http://keepachangelog.com/). ## [Unreleased] ### Added From 292715a296cbbc3b36fa7a2c7991a129143cef12 Mon Sep 17 00:00:00 2001 From: Arthur Maltson Date: Sun, 10 Jul 2016 23:16:26 -0400 Subject: [PATCH 05/24] Nicer title for referring link --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 97e34d5..df1ae97 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,7 +1,7 @@ # Change Log All notable changes to this project will be documented in this file. This project adheres to [Semantic Versioning](http://semver.org/). -The format conforms to [keepachangelog.com](http://keepachangelog.com/). +The format conforms to [Keep a Changelog](http://keepachangelog.com/). ## [Unreleased] ### Added From 525d015e5426e82a2f7f5eebf0046f003c772aee Mon Sep 17 00:00:00 2001 From: magol Date: Mon, 18 Jul 2016 00:58:45 +0100 Subject: [PATCH 06/24] Translated some swedish --- CHANGELOG.md | 1 + source/layouts/layout.haml | 1 + source/sv/index.haml | 188 +++++++++++++++++++++++++++++++++++++ 3 files changed, 190 insertions(+) create mode 100644 source/sv/index.haml diff --git a/CHANGELOG.md b/CHANGELOG.md index b4e2b6b..150e391 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,7 @@ This project adheres to [Semantic Versioning](http://semver.org/). ### Added - zh-CN and zh-TW translations from @tianshuo. - de translation from @mpbzh. +- sv translated from @magol ## [0.3.0] - 2015-12-03 ### Added diff --git a/source/layouts/layout.haml b/source/layouts/layout.haml index 38e0140..6078756 100644 --- a/source/layouts/layout.haml +++ b/source/layouts/layout.haml @@ -38,6 +38,7 @@ %li= link_to '简体中文 [zh-CN]', '/zh-CN/', {rel: "alternate", lang: "zh-CN", hreflang: "zh-CN"} %li= link_to '繁體中文 [zh-TW]', '/zh-TW/', {rel: "alternate", lang: "zh-TW", hreflang: "zh-TW"} %li= link_to 'german [de]', '/de/', {rel: "alternate", lang: "de", hreflang: "de"} + %li= link_to 'svenska [sv]', '/sv/', {rel: "alternate", lang: "sv", hreflang: "sv"} .main{role: "main"}= yield diff --git a/source/sv/index.haml b/source/sv/index.haml new file mode 100644 index 0000000..9dfe256 --- /dev/null +++ b/source/sv/index.haml @@ -0,0 +1,188 @@ +--- +description: Håll en Changelog +title: Håll en Changelog +language: sv +--- + +:markdown + # Håll en CHANGELOG + + ## Låt inte dina vänner slänga in en git logs i CHANGELOG™ + + ### Vad är en ändringslogg? + En ändringslogg är en fil innehållandes en sammanfattad, kronologiskt ordnad + lista över ändringar för varje version av ett projekt. + +%pre.changelog= File.read(File.expand_path("../../CHANGELOG.md", __FILE__)) + +:markdown + ### Vad är meningen med en ändringslogg? + För att göra det enkelt för användare och medarbetare att se exakt vilka + viktiga ändringar som har gjort mellan varje utgåva (eller version) av projektet. + + ### Varför ska jag bry mig? + Därför att mjukvaurverktyg är för människor. Om du inte bryr dig, varför + bidrar du till öppen källkod? Visst finns det väl någon del i din vackra + hjärna som bryr sig. + + Jag [pratade med Adam Stacoviak och Jerod Santo på The Changelog][thechangelog] + (passande, eller hur?) podcast om varför ansvariga och bidragsgivare bör bry sig, + och motiveringen bakom detta projekt. + Om du kan avvara lite tid (1:06), rekomenderar jag att lyssna på det. + + ### Vad gör en bra ändringslogg? + Jag är glad att du frågade. + + En bra ändringslogg håller sig till dessa principer: + + - Den är skapad för människor, inte maskiner, så läsbarhet är avgörande. + - Lätt att länka till valfri sektion (därav Markdown framför klartext). + - En undersektion per version. + - Lista utgåvor i omvänd kronologisk ordning (nyast högst upp). + - Skriv alla datum på formatet `YYYY-MM-DD` + (exempel: `2012-06-02` för 2:a juni 2012). Det är internationellt, + [förnuftigt](http://xkcd.com/1179/) och språkoberoende. + - Ange uttryckligen att projektet följer [Semantisk versionshantering][SemVer]. + - Varje version bör: + - Ange datum då utgåvan släptes på formatet angivet ovan. + - Gruppera ändringar för att beskriva deras inverkan på projektet enligt följande: + - `Added` för nya funktioner. + - `Changed` för ändringar på existerande funktionalitet. + - `Deprecated` för tidigare stabila funktioner som tas bort i nästa utgåva. + - `Removed` för funktioner tidigare markerade som `deprecated` som tas bort i denna version. + - `Fixed` för buggfixar. + - `Security` för att uppmana användare att uppgradera vid fall av sårbarheter. + + ### Hur kan jag minimera den insats som krävs? + Ha alltid en sektion kallas `"Unreleased"` högst upp för att hålla reda på + alla ändringar. + + Detta tjänar två syften: + + - Folk kan se vilka ändringar som kan förväntas i kommande utgåvor + - Vid lansering behöver du bara ändra `"Unreleased"` till versionsnummret + och lägga till en ny `"Unreleased"` högst upp. + + ### Vad får en Enhörning att gråta? + Okej...låt oss gå genom det. + + - **Dumpa ut en diff från commit-loggen.** Gör helt enkelt inte så, du hjälper ingen. + - **Inte betona `deprecations`.** När folk uppgraderar från en version till + en annan ska det vara smärtsamt uppenbart att något kommer att gå sönder. + - **Datum i region-specifikt format.** I USA lägger folk månaden föst + ("06-02-2012" för 2:a juni 2012, vilket bara är *konstigt*), medan många + andra människor runt om i världen skriver "2 June 2012" men uttala det anolunda. + "2012-06-02" fungerar logiskt från största till minsta, inte överlappar på ett + tvetydligt sätt med andra datumformat, och det är en + [ISO-standard](http://www.iso.org/iso/home/standards/iso8601.htm). Dessutom + är det det rekomenderade datumformatet för ändringsloggar. + + + Det finns mer. Hjälp mig att samla dessa enhörningstårar genom att + [öppna en issue][issues] + eller en pull-förfrågan. + + ### Finns det ett standardformat på ändringsloggar? + Tyvärr inte. Men lugn. Jag vet att du frustrerad kommer att rusa iväg för att hitta + den där länken till GUS:s format för ändringsloggar, eller den två stycken långa + GNu NEWS-filen med "guideline". Stilguiden från GNU är en bra start, men den är + tyvärr allt för naiv. Det är inget fel med att vara naiv, men när människor + behöver vägledning är det inte speciellt hjälpsamt. Speciellt när det är många + olika situationer och spcialfall att hantera. + + Detta projekt [inehåller vad jag hoppas kommer att bli en bättre filkonvention + för CHANGELOG][CHANGELOG]. Jag tror inte att status quo är tillräckligt bra, + och jag tror att vi tillsammans kan komma fram till en bättre konvention + om vi försöker att plocka ut bra erfarenheter från riktiga mjukvaruprojekt. + Titta runt och kom ihåg att [diskutioner och förbättringsförslag är välkomna][issues]! + + ### Vad bör filen med ändringsloggen heta? + Tja, om du inte kan lista ut det från exemplen ovan är `CHANGELOG.md` + den bästa konvention hittils. + + En del projekt använder också `HISTORY.txt`, `HISTORY.md`, `History.md`, `NEWS.txt`, + `NEWS.md`, `News.txt`, `RELEASES.txt`, `RELEASE.md`, `releases.md`, etc. + + Det är ebn verklig röra. Alla dessa namn gör det bara svårare för ämnniskor att hitta. + + ### Varför kan folk inte bara använda en diff från `git log`? + Eftersom logg-diffar av naturen är fulla med brus. Det kan inte ens användas + för att göra en lämplig ändringslogg ens i ett hypotetiskt projekt drivet av + perfekta människor som aldrig skriver fel, aldrig glömmer att checka in nya filer + eller aldrig glömmer någon del av en refaktorering. Syftet med en commit är att + dokumentera ett enskilt steg i processen då koden utecklas från ett tillstånd till + ett annat. Syftet med en ändringslogg är att dokumentera de anmärkningsvärda + skillnadenrna mellan dessa tillstånd. + + På samma sätt som det är skillnad mellan bra kommentarer och själva koden, + är det skillnad mellan ändringsloggen och commit-loggen: + en beskriver "varför" och den andra "hur". + + ### Kan ändringsloggar bli automatiskt tolkade? + Det är svårt då människor följer vitt olika format och filnamn. + + [Vandamme][vandamme] är en Ruby gem + skapad av gruppen bakom [Gemnasium][gemnasium] som tolkar många (men inte alla) + ändringsloggar för öppen källkod. + + + + + + ### Why do you alternate between spelling it "CHANGELOG" and "change log"? + "CHANGELOG" is the name of the file itself. It's a bit shouty but it's a + historical convention followed by many open source projects. Other + examples of similar files include [`README`][README], [`LICENSE`][LICENSE], + and [`CONTRIBUTING`][CONTRIBUTING]. + + The uppercase naming (which in old operating systems made these files stick + to the top) is used to draw attention to them. Since they're important + metadata about the project, they could be useful to anyone intending to use + or contribute to it, much like [open source project badges][shields]. + + When I refer to a "change log", I'm talking about the function of this + file: to log changes. + + ### What about yanked releases? + Yanked releases are versions that had to be pulled because of a serious + bug or security issue. Often these versions don't even appear in change + logs. They should. This is how you should display them: + + `## 0.0.5 - 2014-12-13 [YANKED]` + + The `[YANKED]` tag is loud for a reason. It's important for people to + notice it. Since it's surrounded by brackets it's also easier to parse + programmatically. + + ### Should you ever rewrite a change log? + Sure. There are always good reasons to improve a change log. I regularly open + pull requests to add missing releases to open source projects with unmaintained + change logs. + + 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 + change log in this case. + + ### How can I contribute? + This document is not the **truth**; it’s my carefully considered + opinion, along with information and examples I gathered. + Although I provide an actual [CHANGELOG][] on [the GitHub repo][gh], + I have purposefully not created a proper *release* or clear list of rules + to follow (as [SemVer.org][semver] does, for instance). + + This is because I want our community to reach a consensus. I believe the + discussion is as important as the end result. + + So please [**pitch in**][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/ From 8f3a0ca05378a37398afcdcbee411a81667cb4c7 Mon Sep 17 00:00:00 2001 From: magol Date: Thu, 28 Jul 2016 16:13:00 +0100 Subject: [PATCH 07/24] Translate to swedish --- source/sv/index.haml | 74 +++++++++++++++++++++----------------------- 1 file changed, 35 insertions(+), 39 deletions(-) diff --git a/source/sv/index.haml b/source/sv/index.haml index 9dfe256..1ab1caf 100644 --- a/source/sv/index.haml +++ b/source/sv/index.haml @@ -125,55 +125,51 @@ language: sv skapad av gruppen bakom [Gemnasium][gemnasium] som tolkar många (men inte alla) ändringsloggar för öppen källkod. + ### Varför alternerar du mellan att skriva det som "CHANGELOG" och "ändringslogg"?" + "CHANGELOG" är namnet på själva filen. Det sticker ut lite, men det är en + historisk konvention använt i många öppen källkodsprojekt. Andra + exempel på liknande filer är [`README`][README], [`LICENSE`][LICENSE], + och [`CONTRIBUTING`][CONTRIBUTING]. - - - - ### Why do you alternate between spelling it "CHANGELOG" and "change log"? - "CHANGELOG" is the name of the file itself. It's a bit shouty but it's a - historical convention followed by many open source projects. Other - examples of similar files include [`README`][README], [`LICENSE`][LICENSE], - and [`CONTRIBUTING`][CONTRIBUTING]. + De stora bokstäverna i namnen (som gjorde att de i äldre operativsystem + hamnade högst upp) används för att dra uppmärksamhet till dem. Då de är + viktig metadata om projektet borde de vara användbara för att alla som + vill använda eller bidra till det, ungefär som [open source project badges][shields]. - The uppercase naming (which in old operating systems made these files stick - to the top) is used to draw attention to them. Since they're important - metadata about the project, they could be useful to anyone intending to use - or contribute to it, much like [open source project badges][shields]. + När jag refererar till "ändringslogg" pratar jag om syftet med denna fil: + att logga ändringar. - When I refer to a "change log", I'm talking about the function of this - file: to log changes. - - ### What about yanked releases? - Yanked releases are versions that had to be pulled because of a serious - bug or security issue. Often these versions don't even appear in change - logs. They should. This is how you should display them: + ### Hur är det med brådskande utgåvor ("yanked")? + Brådskande utgåvor är versioner som måste släppas p.g.a. alvarliga + buggar eller säkerhetsproblem. Oftast brukar dessa versioner inte ens + finnas med i ändringsloggarna. De borde det. Så här borde du visa dem: `## 0.0.5 - 2014-12-13 [YANKED]` - The `[YANKED]` tag is loud for a reason. It's important for people to - notice it. Since it's surrounded by brackets it's also easier to parse - programmatically. + Taggen `[YANKED]` står ut av en anledning, det är viktigt för människor + att se den. Då den är omsluten med hakparanteser är det också lättare + för ett program att tolka. - ### Should you ever rewrite a change log? - Sure. There are always good reasons to improve a change log. I regularly open - pull requests to add missing releases to open source projects with unmaintained - change logs. + ### Borde du någonsin förändra en ändringslogg? + Självklart. Det finns alltid en bra anlending att förbättra en ändringslogg. + Jag öppnar regelbundet pull requests för att lägga till saknade utgåvor + för öppen källkodsprojekt som inte tar hand om sin ändringslogg. - 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 - change log in this case. + Det kan också hända att du upptäcker att du glömst att ta upp en icke + bakåtkompatibel förändring i en version. I sånna fall är det självklart + viktigt att uppdatera din ändringslogg. - ### How can I contribute? - This document is not the **truth**; it’s my carefully considered - opinion, along with information and examples I gathered. - Although I provide an actual [CHANGELOG][] on [the GitHub repo][gh], - I have purposefully not created a proper *release* or clear list of rules - to follow (as [SemVer.org][semver] does, for instance). + ### Hur kan jag bidra? + Detta dokuemtn är inte **sanningen**, det är en noga övervägd åsikt + tillsammans med information coh exempel jag har sammlat på mig. + Även om jag tillhandahåller en [CHANGELOG][] i min [GitHub repo][gh], + har jag avsiktligt inte skpat en egentlig *utgåva* eller en tydlig lista + med regler att följa (som t.ex. [SemVer.org][semver] gör). - This is because I want our community to reach a consensus. I believe the - discussion is as important as the end result. - - So please [**pitch in**][gh]. + Detta beror på att jag vill att vår gemenskap ska nå samförstånd. Jag + tror att diskussionen är lika viktig som slutresultatet. + + Så välkomna att [**diskutera**]][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 From 8411db9cabd62bd02e11d61fd317f1fe67d6cf03 Mon Sep 17 00:00:00 2001 From: 10sr <8slashes+git@gmail.com> Date: Fri, 29 Jul 2016 01:59:22 +0900 Subject: [PATCH 08/24] Add charset config to .editorconfig --- .editorconfig | 1 + 1 file changed, 1 insertion(+) diff --git a/.editorconfig b/.editorconfig index 97eec54..0c4e702 100644 --- a/.editorconfig +++ b/.editorconfig @@ -11,6 +11,7 @@ root = true # use the same settings everywhere [*] end_of_line = lf +charset = utf-8 insert_final_newline = true indent_style = space indent_size = 2 From c93410fc049cf95bd68471509f0fc5d69c28c3f3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Magnus=20=C3=96sterlund?= Date: Sun, 31 Jul 2016 17:11:47 +0200 Subject: [PATCH 09/24] Fix Swedish spelling --- source/sv/index.haml | 50 ++++++++++++++++++++++---------------------- 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/source/sv/index.haml b/source/sv/index.haml index 1ab1caf..d5d2b76 100644 --- a/source/sv/index.haml +++ b/source/sv/index.haml @@ -1,6 +1,6 @@ --- -description: Håll en Changelog -title: Håll en Changelog +description: Håll en ändringslogg +title: Håll en ändringslogg language: sv --- @@ -21,14 +21,14 @@ language: sv viktiga ändringar som har gjort mellan varje utgåva (eller version) av projektet. ### Varför ska jag bry mig? - Därför att mjukvaurverktyg är för människor. Om du inte bryr dig, varför + Därför att mjukvaruverktyg är för människor. Om du inte bryr dig, varför bidrar du till öppen källkod? Visst finns det väl någon del i din vackra hjärna som bryr sig. Jag [pratade med Adam Stacoviak och Jerod Santo på The Changelog][thechangelog] (passande, eller hur?) podcast om varför ansvariga och bidragsgivare bör bry sig, och motiveringen bakom detta projekt. - Om du kan avvara lite tid (1:06), rekomenderar jag att lyssna på det. + Om du kan avvara lite tid (1:06), rekommenderar jag att lyssna på det. ### Vad gör en bra ändringslogg? Jag är glad att du frågade. @@ -60,59 +60,59 @@ language: sv Detta tjänar två syften: - Folk kan se vilka ändringar som kan förväntas i kommande utgåvor - - Vid lansering behöver du bara ändra `"Unreleased"` till versionsnummret + - Vid lansering behöver du bara ändra `"Unreleased"` till versionsnumret och lägga till en ny `"Unreleased"` högst upp. - ### Vad får en Enhörning att gråta? + ### Vad får änglarna att gråta? Okej...låt oss gå genom det. - **Dumpa ut en diff från commit-loggen.** Gör helt enkelt inte så, du hjälper ingen. - **Inte betona `deprecations`.** När folk uppgraderar från en version till - en annan ska det vara smärtsamt uppenbart att något kommer att gå sönder. + en annan ska det vara smärtsamt uppenbart om något förväntas gå sönder. - **Datum i region-specifikt format.** I USA lägger folk månaden föst ("06-02-2012" för 2:a juni 2012, vilket bara är *konstigt*), medan många - andra människor runt om i världen skriver "2 June 2012" men uttala det anolunda. + andra runt om i världen skriver "2 June 2012" men uttala det annorlunda. "2012-06-02" fungerar logiskt från största till minsta, inte överlappar på ett tvetydligt sätt med andra datumformat, och det är en [ISO-standard](http://www.iso.org/iso/home/standards/iso8601.htm). Dessutom - är det det rekomenderade datumformatet för ändringsloggar. + är det rekommenderat datumformat för ändringsloggar. - Det finns mer. Hjälp mig att samla dessa enhörningstårar genom att + Det finns mer. Hjälp mig att samla tårarna från änglarna genom att [öppna en issue][issues] eller en pull-förfrågan. ### Finns det ett standardformat på ändringsloggar? Tyvärr inte. Men lugn. Jag vet att du frustrerad kommer att rusa iväg för att hitta den där länken till GUS:s format för ändringsloggar, eller den två stycken långa - GNu NEWS-filen med "guideline". Stilguiden från GNU är en bra start, men den är + GNU NEWS-filen med "guideline". Stilguiden från GNU är en bra start, men den är tyvärr allt för naiv. Det är inget fel med att vara naiv, men när människor behöver vägledning är det inte speciellt hjälpsamt. Speciellt när det är många - olika situationer och spcialfall att hantera. + olika situationer och specialfall att hantera. - Detta projekt [inehåller vad jag hoppas kommer att bli en bättre filkonvention + Detta projekt [innehåller vad jag hoppas kommer att bli en bättre filkonvention för CHANGELOG][CHANGELOG]. Jag tror inte att status quo är tillräckligt bra, och jag tror att vi tillsammans kan komma fram till en bättre konvention om vi försöker att plocka ut bra erfarenheter från riktiga mjukvaruprojekt. - Titta runt och kom ihåg att [diskutioner och förbättringsförslag är välkomna][issues]! + Titta runt och kom ihåg att [diskussioner och förbättringsförslag är välkomna][issues]! ### Vad bör filen med ändringsloggen heta? Tja, om du inte kan lista ut det från exemplen ovan är `CHANGELOG.md` - den bästa konvention hittils. + den bästa konvention hittills. En del projekt använder också `HISTORY.txt`, `HISTORY.md`, `History.md`, `NEWS.txt`, `NEWS.md`, `News.txt`, `RELEASES.txt`, `RELEASE.md`, `releases.md`, etc. - Det är ebn verklig röra. Alla dessa namn gör det bara svårare för ämnniskor att hitta. + Det är en verklig röra. Alla dessa namn gör det bara svårare för människor att hitta. ### Varför kan folk inte bara använda en diff från `git log`? Eftersom logg-diffar av naturen är fulla med brus. Det kan inte ens användas för att göra en lämplig ändringslogg ens i ett hypotetiskt projekt drivet av perfekta människor som aldrig skriver fel, aldrig glömmer att checka in nya filer eller aldrig glömmer någon del av en refaktorering. Syftet med en commit är att - dokumentera ett enskilt steg i processen då koden utecklas från ett tillstånd till + dokumentera ett enskilt steg i processen då koden utvecklas från ett tillstånd till ett annat. Syftet med en ändringslogg är att dokumentera de anmärkningsvärda - skillnadenrna mellan dessa tillstånd. + skillnaderna mellan dessa tillstånd. På samma sätt som det är skillnad mellan bra kommentarer och själva koden, är det skillnad mellan ändringsloggen och commit-loggen: @@ -128,7 +128,7 @@ language: sv ### Varför alternerar du mellan att skriva det som "CHANGELOG" och "ändringslogg"?" "CHANGELOG" är namnet på själva filen. Det sticker ut lite, men det är en historisk konvention använt i många öppen källkodsprojekt. Andra - exempel på liknande filer är [`README`][README], [`LICENSE`][LICENSE], + exempel på liknande filer är [`README`][README], [`LICENSE`][LICENSE] och [`CONTRIBUTING`][CONTRIBUTING]. De stora bokstäverna i namnen (som gjorde att de i äldre operativsystem @@ -147,7 +147,7 @@ language: sv `## 0.0.5 - 2014-12-13 [YANKED]` Taggen `[YANKED]` står ut av en anledning, det är viktigt för människor - att se den. Då den är omsluten med hakparanteser är det också lättare + att se den. Då den är omsluten med hakparenteser är det också lättare för ett program att tolka. ### Borde du någonsin förändra en ändringslogg? @@ -155,15 +155,15 @@ language: sv Jag öppnar regelbundet pull requests för att lägga till saknade utgåvor för öppen källkodsprojekt som inte tar hand om sin ändringslogg. - Det kan också hända att du upptäcker att du glömst att ta upp en icke - bakåtkompatibel förändring i en version. I sånna fall är det självklart + Det kan också hända att du upptäcker att du glömt att ta upp en icke + bakåtkompatibel förändring i en version. I sådana fall är det självklart viktigt att uppdatera din ändringslogg. ### Hur kan jag bidra? - Detta dokuemtn är inte **sanningen**, det är en noga övervägd åsikt - tillsammans med information coh exempel jag har sammlat på mig. + Detta dokument är inte **sanningen**, det är en noga övervägd åsikt + tillsammans med information och exempel jag har samlat på mig. Även om jag tillhandahåller en [CHANGELOG][] i min [GitHub repo][gh], - har jag avsiktligt inte skpat en egentlig *utgåva* eller en tydlig lista + har jag avsiktligt inte skapat en egentlig *utgåva* eller en tydlig lista med regler att följa (som t.ex. [SemVer.org][semver] gör). Detta beror på att jag vill att vår gemenskap ska nå samförstånd. Jag From 79b1cc653a44cce3d28d3192bda48f961fc8bbbb Mon Sep 17 00:00:00 2001 From: Olivier Lacan Date: Fri, 5 Aug 2016 20:00:22 -0400 Subject: [PATCH 10/24] @jswanner says I should ignore this --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index 6cb2241..865ecdb 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,4 @@ /.cache /.sass-cache /build +/_site From adfbaf9235d591aad0c1c466536cf6e4d058ca1e Mon Sep 17 00:00:00 2001 From: Olivier Lacan Date: Fri, 5 Aug 2016 20:00:43 -0400 Subject: [PATCH 11/24] Flip the directory organization to have lang first MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Thanks @jswanner you’re so swell and stuff. --- config.rb | 4 +- source/{0.3.0/de => de/0.3.0}/index.haml | 2 +- source/en/0.3.0/index.haml | 184 ++++++++++++++++++ .../{0.3.0/es-ES => es-ES/0.3.0}/index.haml | 2 +- source/{0.3.0/en => }/index.haml | 2 +- .../{0.3.0/pt-BR => pt-BR/0.3.0}/index.haml | 2 +- source/{0.3.0/ru => ru/0.3.0}/index.haml | 2 +- .../{0.3.0/zh-CN => zh-CN/0.3.0}/index.haml | 2 +- .../{0.3.0/zh-TW => zh-TW/0.3.0}/index.haml | 2 +- 9 files changed, 193 insertions(+), 9 deletions(-) rename source/{0.3.0/de => de/0.3.0}/index.haml (99%) create mode 100644 source/en/0.3.0/index.haml rename source/{0.3.0/es-ES => es-ES/0.3.0}/index.haml (99%) rename source/{0.3.0/en => }/index.haml (99%) rename source/{0.3.0/pt-BR => pt-BR/0.3.0}/index.haml (99%) rename source/{0.3.0/ru => ru/0.3.0}/index.haml (99%) rename source/{0.3.0/zh-CN => zh-CN/0.3.0}/index.haml (99%) rename source/{0.3.0/zh-TW => zh-TW/0.3.0}/index.haml (99%) diff --git a/config.rb b/config.rb index be396dc..2c8bd11 100644 --- a/config.rb +++ b/config.rb @@ -22,11 +22,11 @@ set :gauges_id, '' set :publisher_url, 'https://www.facebook.com/olivier.lacan.5' set :site_url, 'http://keepachangelog.com' -redirect "index.html", to: "#{$last_version}/en/index.html" +redirect "index.html", to: "en/#{$last_version}/index.html" $languages.each do |language| language_param = language.last.parameterize - redirect "#{language.first}/index.html", to: "#{$last_version}/#{language.first}/index.html" + redirect "#{language.first}/index.html", to: "#{language.first}/#{$last_version}/index.html" end # ----- Assets ----- # diff --git a/source/0.3.0/de/index.haml b/source/de/0.3.0/index.haml similarity index 99% rename from source/0.3.0/de/index.haml rename to source/de/0.3.0/index.haml index 86096cb..4496b70 100644 --- a/source/0.3.0/de/index.haml +++ b/source/de/0.3.0/index.haml @@ -16,7 +16,7 @@ version: 0.3.0 Ein Changelog ist eine Datei, welche eine nachgeführte, chronologisch sortierte Liste aller relevanten Änderungen für jede Version eines Projektes enthält. -%pre.changelog= File.read(File.join(root_path, "README.md")) +%pre.changelog= File.read(File.join(root_path, "CHANGELOG.md")) :markdown ### Was ist der Zweck eines Changelogs? diff --git a/source/en/0.3.0/index.haml b/source/en/0.3.0/index.haml new file mode 100644 index 0000000..a263ab5 --- /dev/null +++ b/source/en/0.3.0/index.haml @@ -0,0 +1,184 @@ +--- +description: Keep a Changelog +title: Keep a Changelog +language: en +version: 0.3.0 +redirect_path: /about/ +--- + +:markdown + # Keep a CHANGELOG + + ## Don’t let your friends dump git logs into CHANGELOGs™ + + Version **#{current_page.metadata[:page]["version"]}** + + ### What’s a change log? + A change log is a file which contains a curated, chronologically ordered + list of notable changes for each version of a project. + +%pre.changelog= File.read(File.join(root_path, "CHANGELOG.md")) + +:markdown + ### What’s the point of a change log? + To make it easier for users and contributors to see precisely what + notable changes have been made between each release (or version) of the project. + + ### Why should I care? + Because software tools are for people. If you don’t care, why are + you contributing to open source? Surely, there must be a kernel (ha!) + of care somewhere in that lovely little brain of yours. + + I [talked with Adam Stacoviak and Jerod Santo on The Changelog][thechangelog] + (fitting, right?) podcast about why maintainers and + contributors should care, and the motivations behind this project. + If you can spare the time (1:06), it’s a good listen. + + ### What makes a good change log? + I’m glad you asked. + + A good change log sticks to these principles: + + - It’s made for humans, not machines, so legibility is crucial. + - Easy to link to any section (hence Markdown over plain text). + - One sub-section per version. + - List releases in reverse-chronological order (newest on top). + - Write all dates in `YYYY-MM-DD` format. (Example: `2012-06-02` for `June 2nd, 2012`.) It’s international, [sensible](http://xkcd.com/1179/), and language-independent. + - Explicitly mention whether the project follows [Semantic Versioning][semver]. + - Each version should: + - List its release date in the above format. + - Group changes to describe their impact on the project, as follows: + - `Added` for new features. + - `Changed` for changes in existing functionality. + - `Deprecated` for once-stable features removed in upcoming releases. + - `Removed` for deprecated features removed in this release. + - `Fixed` for any bug fixes. + - `Security` to invite users to upgrade in case of vulnerabilities. + + ### How can I minimize the effort required? + Always have an `"Unreleased"` section at the top for keeping track of any + changes. + + This serves two purposes: + + - People can see what changes they might expect in upcoming releases + - At release time, you just have to change `"Unreleased"` to the version number + and add a new `"Unreleased"` header at the top. + + ### What makes unicorns cry? + Alright…let’s get into it. + + - **Dumping a diff of commit logs.** Just don’t do that, you’re helping nobody. + - **Not emphasizing deprecations.** When people upgrade from one version to + another, it should be painfully clear when something will break. + - **Dates in region-specific formats.** In the U.S., people put the month first + ("06-02-2012" for June 2nd, 2012, which makes *no* sense), while many people + in the rest of the world write a robotic-looking "2 June 2012", yet pronounce + it differently. "2012-06-02" works logically from largest to smallest, doesn't + overlap in ambiguous ways with other date formats, and is an + [ISO standard](http://www.iso.org/iso/home/standards/iso8601.htm). Thus, it + is the recommended date format for change logs. + + There’s more. Help me collect those unicorn tears by + [opening an issue][issues] + or a pull request. + + ### Is there a standard change log format? + Sadly, no. Calm down. I know you're furiously rushing to find that link + to the GNU change log style guide, or the two-paragraph GNU NEWS file + "guideline". The GNU style guide is a nice start but it is sadly naive. + There's nothing wrong with being naive but when people need + guidance it's rarely very helpful. Especially when there are many + situations and edge cases to deal with. + + This project [contains what I hope will become a better CHANGELOG file convention][CHANGELOG]. + I don't think the status quo is good enough, and I think that as a community we + can come up with better conventions if we try to extract good practices from + real software projects. Please take a look around and remember that + [discussions and suggestions for improvements are welcome][issues]! + + ### What should the change log file be named? + Well, if you can’t tell from the example above, `CHANGELOG.md` is the + best convention so far. + + Some projects also use `HISTORY.txt`, `HISTORY.md`, `History.md`, `NEWS.txt`, + `NEWS.md`, `News.txt`, `RELEASES.txt`, `RELEASE.md`, `releases.md`, etc. + + It’s a mess. All these names only makes it harder for people to find it. + + ### Why can’t people just use a `git log` diff? + Because log diffs are full of noise — by nature. They could not make a suitable + change log even in a hypothetical project run by perfect humans who never make + typos, never forget to commit new files, never miss any part of a refactoring. + The purpose of a commit is to document one atomic step in the process by which + the code evolves from one state to another. The purpose of a change log is to + document the noteworthy differences between these states. + + As is the difference between good comments and the code itself, + so is the difference between a change log and the commit log: + one describes the *why*, the other the how. + + ### Can change logs be automatically parsed? + It’s difficult, because people follow wildly different formats and file names. + + [Vandamme][vandamme] is a Ruby gem + created by the [Gemnasium][gemnasium] team and which parses + many (but not all) open source project change logs. + + ### Why do you alternate between spelling it "CHANGELOG" and "change log"? + "CHANGELOG" is the name of the file itself. It's a bit shouty but it's a + historical convention followed by many open source projects. Other + examples of similar files include [`README`][README], [`LICENSE`][LICENSE], + and [`CONTRIBUTING`][CONTRIBUTING]. + + The uppercase naming (which in old operating systems made these files stick + to the top) is used to draw attention to them. Since they're important + metadata about the project, they could be useful to anyone intending to use + or contribute to it, much like [open source project badges][shields]. + + When I refer to a "change log", I'm talking about the function of this + file: to log changes. + + ### What about yanked releases? + Yanked releases are versions that had to be pulled because of a serious + bug or security issue. Often these versions don't even appear in change + logs. They should. This is how you should display them: + + `## 0.0.5 - 2014-12-13 [YANKED]` + + The `[YANKED]` tag is loud for a reason. It's important for people to + notice it. Since it's surrounded by brackets it's also easier to parse + programmatically. + + ### Should you ever rewrite a change log? + Sure. There are always good reasons to improve a change log. I regularly open + pull requests to add missing releases to open source projects with unmaintained + change logs. + + 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 + change log in this case. + + ### How can I contribute? + This document is not the **truth**; it’s my carefully considered + opinion, along with information and examples I gathered. + Although I provide an actual [CHANGELOG][] on [the GitHub repo][gh], + I have purposefully not created a proper *release* or clear list of rules + to follow (as [SemVer.org][semver] does, for instance). + + This is because I want our community to reach a consensus. I believe the + discussion is as important as the end result. + + So please [**pitch in**][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/ diff --git a/source/0.3.0/es-ES/index.haml b/source/es-ES/0.3.0/index.haml similarity index 99% rename from source/0.3.0/es-ES/index.haml rename to source/es-ES/0.3.0/index.haml index fa556a0..9cc2cc4 100644 --- a/source/0.3.0/es-ES/index.haml +++ b/source/es-ES/0.3.0/index.haml @@ -16,7 +16,7 @@ version: 0.3.0 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.join(root_path, "README.md")) +%pre.changelog= File.read(File.join(root_path, "CHANGELOG.md")) :markdown ### Cuál es el propósito del change log? diff --git a/source/0.3.0/en/index.haml b/source/index.haml similarity index 99% rename from source/0.3.0/en/index.haml rename to source/index.haml index 919c945..1d3bbba 100644 --- a/source/0.3.0/en/index.haml +++ b/source/index.haml @@ -16,7 +16,7 @@ version: 0.3.0 A change log is a file which contains a curated, chronologically ordered list of notable changes for each version of a project. -%pre.changelog= File.read(File.join(root_path, "README.md")) +%pre.changelog= File.read(File.join(root_path, "CHANGELOG.md")) :markdown ### What’s the point of a change log? diff --git a/source/0.3.0/pt-BR/index.haml b/source/pt-BR/0.3.0/index.haml similarity index 99% rename from source/0.3.0/pt-BR/index.haml rename to source/pt-BR/0.3.0/index.haml index 842be29..6e06095 100644 --- a/source/0.3.0/pt-BR/index.haml +++ b/source/pt-BR/0.3.0/index.haml @@ -18,7 +18,7 @@ version: 0.3.0 cronologicamente de mudanças significativas para cada versão de um projeto open source. -%pre.changelog= File.read(File.join(root_path, "README.md")) +%pre.changelog= File.read(File.join(root_path, "CHANGELOG.md")) :markdown ### Para que serve um *change log*? diff --git a/source/0.3.0/ru/index.haml b/source/ru/0.3.0/index.haml similarity index 99% rename from source/0.3.0/ru/index.haml rename to source/ru/0.3.0/index.haml index 5282c4a..c38e26d 100644 --- a/source/0.3.0/ru/index.haml +++ b/source/ru/0.3.0/index.haml @@ -18,7 +18,7 @@ version: 0.3.0 хронологическом порядке список значимых изменений для каждой версии проекта с открытым исходным кодом. -%pre.changelog= File.read(File.join(root_path, "README.md")) +%pre.changelog= File.read(File.join(root_path, "CHANGELOG.md")) :markdown ### Для чего нужен лог изменений? diff --git a/source/0.3.0/zh-CN/index.haml b/source/zh-CN/0.3.0/index.haml similarity index 99% rename from source/0.3.0/zh-CN/index.haml rename to source/zh-CN/0.3.0/index.haml index b258f3e..8640f7e 100644 --- a/source/0.3.0/zh-CN/index.haml +++ b/source/zh-CN/0.3.0/index.haml @@ -17,7 +17,7 @@ version: 0.3.0 这个列表记录所有版本的重大变动。 -%pre.changelog= File.read(File.join(root_path, "README.md")) +%pre.changelog= File.read(File.join(root_path, "CHANGELOG.md")) :markdown ### 为何要提供更新日志？ diff --git a/source/0.3.0/zh-TW/index.haml b/source/zh-TW/0.3.0/index.haml similarity index 99% rename from source/0.3.0/zh-TW/index.haml rename to source/zh-TW/0.3.0/index.haml index 30fe43c..fc1d9ce 100644 --- a/source/0.3.0/zh-TW/index.haml +++ b/source/zh-TW/0.3.0/index.haml @@ -17,7 +17,7 @@ version: 0.3.0 這個列表記錄所有版本的重大變動。 -%pre.changelog= File.read(File.join(root_path, "README.md")) +%pre.changelog= File.read(File.join(root_path, "CHANGELOG.md")) :markdown ### 為何要提供更新日誌？ From 9afff8fc3e40dbb485e411693a4f44f8c8d9b416 Mon Sep 17 00:00:00 2001 From: Olivier Lacan Date: Sat, 6 Aug 2016 01:35:29 -0400 Subject: [PATCH 12/24] Upgrade to Middleman 4.1.10 --- .ruby-version | 2 +- Gemfile | 2 +- Gemfile.lock | 164 ++++++++---------- config.rb | 2 +- ...{application.sass => application.css.sass} | 0 .../de/0.3.0/{index.haml => index.html.haml} | 4 +- .../{index.haml => en/0.3.0/index.html.haml} | 4 +- .../0.3.0/{index.haml => index.html.haml} | 4 +- .../{en/0.3.0/index.haml => index.html.haml} | 5 +- .../layouts/{layout.haml => layout.html.haml} | 6 +- .../0.3.0/{index.haml => index.html.haml} | 4 +- .../ru/0.3.0/{index.haml => index.html.haml} | 4 +- .../0.3.0/{index.haml => index.html.haml} | 4 +- .../0.3.0/{index.haml => index.html.haml} | 4 +- 14 files changed, 92 insertions(+), 117 deletions(-) rename source/assets/stylesheets/{application.sass => application.css.sass} (100%) rename source/de/0.3.0/{index.haml => index.html.haml} (98%) rename source/{index.haml => en/0.3.0/index.html.haml} (98%) rename source/es-ES/0.3.0/{index.haml => index.html.haml} (98%) rename source/{en/0.3.0/index.haml => index.html.haml} (98%) rename source/layouts/{layout.haml => layout.html.haml} (92%) rename source/pt-BR/0.3.0/{index.haml => index.html.haml} (98%) rename source/ru/0.3.0/{index.haml => index.html.haml} (99%) rename source/zh-CN/0.3.0/{index.haml => index.html.haml} (98%) rename source/zh-TW/0.3.0/{index.haml => index.html.haml} (98%) diff --git a/.ruby-version b/.ruby-version index 276cbf9..2bf1c1c 100644 --- a/.ruby-version +++ b/.ruby-version @@ -1 +1 @@ -2.3.0 +2.3.1 diff --git a/Gemfile b/Gemfile index f4e149a..ca87ecb 100644 --- a/Gemfile +++ b/Gemfile @@ -1,7 +1,7 @@ source "https://rubygems.org" gem "addressable" -gem "middleman", "~> 3.4.0" +gem "middleman", "~> 4.1.0" gem "middleman-autoprefixer" gem "middleman-blog" gem "middleman-livereload" diff --git a/Gemfile.lock b/Gemfile.lock index 7b4ed17..97d167e 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -1,120 +1,111 @@ GEM remote: https://rubygems.org/ specs: - activesupport (4.2.4) + activesupport (4.2.7) i18n (~> 0.7) json (~> 1.7, >= 1.7.7) minitest (~> 5.1) thread_safe (~> 0.3, >= 0.3.4) tzinfo (~> 1.1) - addressable (2.3.8) - autoprefixer-rails (6.0.3) + addressable (2.4.0) + autoprefixer-rails (6.4.0.1) execjs - json - capybara (2.4.4) - mime-types (>= 1.16) - nokogiri (>= 1.3.3) - rack (>= 1.0.0) - rack-test (>= 0.5.4) - xpath (~> 2.0) - chunky_png (1.3.4) + backports (3.6.8) coderay (1.1.1) coffee-script (2.4.1) coffee-script-source execjs - coffee-script-source (1.9.1.1) - compass (1.0.3) - chunky_png (~> 1.2) - compass-core (~> 1.0.2) - compass-import-once (~> 1.0.5) - rb-fsevent (>= 0.9.3) - rb-inotify (>= 0.9) - sass (>= 3.3.13, < 3.5) - compass-core (1.0.3) - multi_json (~> 1.0) - sass (>= 3.3.0, < 3.5) + coffee-script-source (1.10.0) compass-import-once (1.0.5) sass (>= 3.2, < 3.5) + concurrent-ruby (1.0.2) + contracts (0.13.0) + dotenv (2.1.1) em-websocket (0.5.1) eventmachine (>= 0.12.9) http_parser.rb (~> 0.6.0) erubis (2.7.0) - eventmachine (1.0.8) - execjs (2.6.0) - ffi (1.9.10) + eventmachine (1.2.0.1) + execjs (2.7.0) + fast_blank (1.0.0) + fastimage (2.0.0) + addressable (~> 2) + ffi (1.9.14) haml (4.0.7) tilt - hike (1.2.3) - hooks (0.4.1) - uber (~> 0.0.14) + hamster (3.0.0) + concurrent-ruby (~> 1.0) + hashie (3.4.4) htmlcompressor (0.2.0) http_parser.rb (0.6.0) i18n (0.7.0) json (1.8.3) - kramdown (1.9.0) - listen (3.0.3) - rb-fsevent (>= 0.9.3) - rb-inotify (>= 0.9) + kramdown (1.11.1) + listen (3.0.8) + rb-fsevent (~> 0.9, >= 0.9.4) + rb-inotify (~> 0.9, >= 0.9.7) + memoist (0.14.0) method_source (0.8.2) - middleman (3.4.0) + middleman (4.1.10) coffee-script (~> 2.2) - compass (>= 1.0.0, < 2.0.0) compass-import-once (= 1.0.5) - execjs (~> 2.0) haml (>= 4.0.5) kramdown (~> 1.2) - middleman-core (= 3.4.0) - middleman-sprockets (>= 3.1.2) + middleman-cli (= 4.1.10) + middleman-core (= 4.1.10) sass (>= 3.4.0, < 4.0) - uglifier (~> 2.5) - middleman-autoprefixer (2.6.1) - autoprefixer-rails (~> 6.0.1) + middleman-autoprefixer (2.7.0) + autoprefixer-rails (>= 6.3.1, < 7.0.0) middleman-core (>= 3.3.3) - middleman-blog (3.5.3) - addressable (~> 2.3.5) - middleman-core (~> 3.2) + middleman-blog (4.0.1) + addressable (~> 2.3) + middleman-core (>= 4.0.0) tzinfo (>= 0.3.0) - middleman-core (3.4.0) - activesupport (~> 4.1) + middleman-cli (4.1.10) + thor (>= 0.17.0, < 2.0) + middleman-core (4.1.10) + activesupport (~> 4.2) + addressable (~> 2.3) + backports (~> 3.6) bundler (~> 1.1) - capybara (~> 2.4.4) + contracts (~> 0.13.0) + dotenv erubis - hooks (~> 0.3) + execjs (~> 2.0) + fast_blank + fastimage (~> 2.0) + hamster (~> 3.0) + hashie (~> 3.4) i18n (~> 0.7.0) - listen (~> 3.0.3) - padrino-helpers (~> 0.12.3) + listen (~> 3.0.0) + memoist (~> 0.14) + padrino-helpers (~> 0.13.0) + parallel rack (>= 1.4.5, < 2.0) - thor (>= 0.15.2, < 2.0) - tilt (~> 1.4.1, < 2.0) + sass (>= 3.4) + servolux + tilt (~> 1.4.1) + uglifier (~> 3.0) middleman-gh-pages (0.0.3) rake (> 0.9.3) - middleman-livereload (3.4.3) + middleman-livereload (3.4.6) em-websocket (~> 0.5.1) middleman-core (>= 3.3) rack-livereload (~> 0.3.15) middleman-minify-html (3.4.1) htmlcompressor (~> 0.2.0) middleman-core (>= 3.2) - middleman-sprockets (3.4.2) - middleman-core (>= 3.3) - sprockets (~> 2.12.1) - sprockets-helpers (~> 1.1.0) - sprockets-sass (~> 1.3.0) - middleman-syntax (2.0.0) - middleman-core (~> 3.2) - rouge (~> 1.0) - mime-types (2.6.2) - mini_portile (0.6.2) - minitest (5.8.1) - multi_json (1.11.2) - nokogiri (1.6.6.2) - mini_portile (~> 0.6.0) - padrino-helpers (0.12.5) + middleman-syntax (3.0.0) + middleman-core (>= 3.2) + rouge (~> 2.0) + minitest (5.9.0) + padrino-helpers (0.13.2) i18n (~> 0.6, >= 0.6.7) - padrino-support (= 0.12.5) - tilt (~> 1.4.1) - padrino-support (0.12.5) + padrino-support (= 0.13.2) + tilt (>= 1.4.1, < 3) + padrino-support (0.13.2) activesupport (>= 3.1) + parallel (1.9.0) pry (0.10.3) coderay (~> 1.1.0) method_source (~> 0.8.1) @@ -122,44 +113,29 @@ GEM rack (1.6.4) rack-livereload (0.3.16) rack - rack-test (0.6.3) - rack (>= 1.0) rake (10.4.2) - rb-fsevent (0.9.6) - rb-inotify (0.9.5) + rb-fsevent (0.9.7) + rb-inotify (0.9.7) ffi (>= 0.5.0) redcarpet (3.3.3) - rouge (1.10.1) - sass (3.4.19) + rouge (2.0.5) + sass (3.4.22) + servolux (0.12.0) slop (3.6.0) - sprockets (2.12.4) - hike (~> 1.2) - multi_json (~> 1.0) - rack (~> 1.0) - tilt (~> 1.1, != 1.3.0) - sprockets-helpers (1.1.0) - sprockets (~> 2.0) - sprockets-sass (1.3.1) - sprockets (~> 2.0) - tilt (~> 1.1) thor (0.19.1) thread_safe (0.3.5) tilt (1.4.1) tzinfo (1.2.2) thread_safe (~> 0.1) - uber (0.0.15) - uglifier (2.7.2) - execjs (>= 0.3.0) - json (>= 1.8.0) - xpath (2.0.0) - nokogiri (~> 1.3) + uglifier (3.0.1) + execjs (>= 0.3.0, < 3) PLATFORMS ruby DEPENDENCIES addressable - middleman (~> 3.4.0) + middleman (~> 4.1.0) middleman-autoprefixer middleman-blog middleman-gh-pages @@ -170,4 +146,4 @@ DEPENDENCIES redcarpet BUNDLED WITH - 1.12.0.rc + 1.12.0 diff --git a/config.rb b/config.rb index 2c8bd11..01d6293 100644 --- a/config.rb +++ b/config.rb @@ -57,7 +57,7 @@ set :markdown, { helpers do def path_to_url(path) - Addressable::URI.join(site_url, path).normalize.to_s + Addressable::URI.join(config.site_url, path).normalize.to_s end end diff --git a/source/assets/stylesheets/application.sass b/source/assets/stylesheets/application.css.sass similarity index 100% rename from source/assets/stylesheets/application.sass rename to source/assets/stylesheets/application.css.sass diff --git a/source/de/0.3.0/index.haml b/source/de/0.3.0/index.html.haml similarity index 98% rename from source/de/0.3.0/index.haml rename to source/de/0.3.0/index.html.haml index 4496b70..ed7e8e9 100644 --- a/source/de/0.3.0/index.haml +++ b/source/de/0.3.0/index.html.haml @@ -10,13 +10,13 @@ version: 0.3.0 ## Lass deine Freunde nicht CHANGELOGs mit git logs füllen™ - Version **#{current_page.metadata[:page]["version"]}** + Version **#{current_page.metadata[:page][:version]}** ### Was ist ein Changelog? Ein Changelog ist eine Datei, welche eine nachgeführte, chronologisch sortierte Liste aller relevanten Änderungen für jede Version eines Projektes enthält. -%pre.changelog= File.read(File.join(root_path, "CHANGELOG.md")) +%pre.changelog= File.read("CHANGELOG.md") :markdown ### Was ist der Zweck eines Changelogs? diff --git a/source/index.haml b/source/en/0.3.0/index.html.haml similarity index 98% rename from source/index.haml rename to source/en/0.3.0/index.html.haml index 1d3bbba..3bbd884 100644 --- a/source/index.haml +++ b/source/en/0.3.0/index.html.haml @@ -10,13 +10,13 @@ version: 0.3.0 ## Don’t let your friends dump git logs into CHANGELOGs™ - Version **#{current_page.metadata[:page]["version"]}** + Version **#{current_page.metadata[:page][:version]}** ### What’s a change log? A change log is a file which contains a curated, chronologically ordered list of notable changes for each version of a project. -%pre.changelog= File.read(File.join(root_path, "CHANGELOG.md")) +%pre.changelog= File.read("CHANGELOG.md") :markdown ### What’s the point of a change log? diff --git a/source/es-ES/0.3.0/index.haml b/source/es-ES/0.3.0/index.html.haml similarity index 98% rename from source/es-ES/0.3.0/index.haml rename to source/es-ES/0.3.0/index.html.haml index 9cc2cc4..b46f90e 100644 --- a/source/es-ES/0.3.0/index.haml +++ b/source/es-ES/0.3.0/index.html.haml @@ -10,13 +10,13 @@ version: 0.3.0 ## No dejes que tus amigos copien y peguen git logs en los CHANGELOGs™ - Version **#{current_page.metadata[:page]["version"]}** + Version **#{current_page.metadata[:page][:version]}** ### 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.join(root_path, "CHANGELOG.md")) +%pre.changelog= File.read("CHANGELOG.md") :markdown ### Cuál es el propósito del change log? diff --git a/source/en/0.3.0/index.haml b/source/index.html.haml similarity index 98% rename from source/en/0.3.0/index.haml rename to source/index.html.haml index a263ab5..3bbd884 100644 --- a/source/en/0.3.0/index.haml +++ b/source/index.html.haml @@ -3,7 +3,6 @@ description: Keep a Changelog title: Keep a Changelog language: en version: 0.3.0 -redirect_path: /about/ --- :markdown @@ -11,13 +10,13 @@ redirect_path: /about/ ## Don’t let your friends dump git logs into CHANGELOGs™ - Version **#{current_page.metadata[:page]["version"]}** + Version **#{current_page.metadata[:page][:version]}** ### What’s a change log? A change log is a file which contains a curated, chronologically ordered list of notable changes for each version of a project. -%pre.changelog= File.read(File.join(root_path, "CHANGELOG.md")) +%pre.changelog= File.read("CHANGELOG.md") :markdown ### What’s the point of a change log? diff --git a/source/layouts/layout.haml b/source/layouts/layout.html.haml similarity index 92% rename from source/layouts/layout.haml rename to source/layouts/layout.html.haml index bddd972..5afea05 100644 --- a/source/layouts/layout.haml +++ b/source/layouts/layout.html.haml @@ -8,7 +8,7 @@ -# Open Graph - %meta{property: 'og:article:publisher', content: publisher_url} + %meta{property: 'og:article:publisher', content: config.publisher_url} %meta{property: 'og:title', content: current_page.data.title} %meta{property: 'og:type', content: 'article'} %meta{property: 'og:url', content: path_to_url(current_page.url)} @@ -47,7 +47,7 @@ #{link_to "Olivier Lacan", "http://olivierlacan.com/"} from #{link_to "Code School", "https://www.codeschool.com/"}. - - unless gauges_id.blank? + - unless config.gauges_id.blank? :javascript var _gauges = _gauges || []; (function() { @@ -55,7 +55,7 @@ t.type = 'text/javascript'; t.async = true; t.id = 'gauges-tracker'; - t.setAttribute('data-site-id', '#{gauges_id}'); + t.setAttribute('data-site-id', '#{config.gauges_id}'); t.src = '//secure.gaug.es/track.js'; var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(t, s); diff --git a/source/pt-BR/0.3.0/index.haml b/source/pt-BR/0.3.0/index.html.haml similarity index 98% rename from source/pt-BR/0.3.0/index.haml rename to source/pt-BR/0.3.0/index.html.haml index 6e06095..4d981a5 100644 --- a/source/pt-BR/0.3.0/index.haml +++ b/source/pt-BR/0.3.0/index.html.haml @@ -10,7 +10,7 @@ version: 0.3.0 ## Não deixe seus amigos despejar logs de commits em CHANGELOGs™ - Version **#{current_page.metadata[:page]["version"]}** + Version **#{current_page.metadata[:page][:version]}** ### O que é um change log? @@ -18,7 +18,7 @@ version: 0.3.0 cronologicamente de mudanças significativas para cada versão de um projeto open source. -%pre.changelog= File.read(File.join(root_path, "CHANGELOG.md")) +%pre.changelog= File.read("CHANGELOG.md") :markdown ### Para que serve um *change log*? diff --git a/source/ru/0.3.0/index.haml b/source/ru/0.3.0/index.html.haml similarity index 99% rename from source/ru/0.3.0/index.haml rename to source/ru/0.3.0/index.html.haml index c38e26d..23ffa88 100644 --- a/source/ru/0.3.0/index.haml +++ b/source/ru/0.3.0/index.html.haml @@ -10,7 +10,7 @@ version: 0.3.0 ## Не позволяйте друзьям сливать логи гита в CHANGELOG™ - Version **#{current_page.metadata[:page]["version"]}** + Version **#{current_page.metadata[:page][:version]}** ### Что такое лог изменений? @@ -18,7 +18,7 @@ version: 0.3.0 хронологическом порядке список значимых изменений для каждой версии проекта с открытым исходным кодом. -%pre.changelog= File.read(File.join(root_path, "CHANGELOG.md")) +%pre.changelog= File.read("CHANGELOG.md") :markdown ### Для чего нужен лог изменений? diff --git a/source/zh-CN/0.3.0/index.haml b/source/zh-CN/0.3.0/index.html.haml similarity index 98% rename from source/zh-CN/0.3.0/index.haml rename to source/zh-CN/0.3.0/index.html.haml index 8640f7e..1837edf 100644 --- a/source/zh-CN/0.3.0/index.haml +++ b/source/zh-CN/0.3.0/index.html.haml @@ -10,14 +10,14 @@ version: 0.3.0 ## 更新日志绝对不应该是git日志的堆砌物 - Version **#{current_page.metadata[:page]["version"]}** + Version **#{current_page.metadata[:page][:version]}** ### 更新日志是什么？ 更新日志（Change Log）是一个由人工编辑，以时间为倒叙的列表。 这个列表记录所有版本的重大变动。 -%pre.changelog= File.read(File.join(root_path, "CHANGELOG.md")) +%pre.changelog= File.read("CHANGELOG.md") :markdown ### 为何要提供更新日志？ diff --git a/source/zh-TW/0.3.0/index.haml b/source/zh-TW/0.3.0/index.html.haml similarity index 98% rename from source/zh-TW/0.3.0/index.haml rename to source/zh-TW/0.3.0/index.html.haml index fc1d9ce..564d883 100644 --- a/source/zh-TW/0.3.0/index.haml +++ b/source/zh-TW/0.3.0/index.html.haml @@ -10,14 +10,14 @@ version: 0.3.0 ## 更新日誌絕對不應該是git日誌的堆砌物 - Version **#{current_page.metadata[:page]["version"]}** + Version **#{current_page.metadata[:page][:version]}** ### 更新日誌是什麽？ 更新日誌（Change Log）是壹個由人工編輯，以時間為倒敘的列表。 這個列表記錄所有版本的重大變動。 -%pre.changelog= File.read(File.join(root_path, "CHANGELOG.md")) +%pre.changelog= File.read("CHANGELOG.md") :markdown ### 為何要提供更新日誌？ From aad8220ea8e5b3c6b42c45eaf5837463cc70ad83 Mon Sep 17 00:00:00 2001 From: Olivier Lacan Date: Sat, 6 Aug 2016 01:41:15 -0400 Subject: [PATCH 13/24] Add version badge pointing to CHANGELOG --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index bf2af7c..c47c8b9 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Keep a CHANGELOG +# Keep a CHANGELOG [![version](https://img.shields.io/badge/version-0.3.0-blue.svg)][CHANGELOG] ## Don’t let your friends dump git logs into CHANGELOGs™ From 5a0497f7dc685132057b9632a89b2a034e36de66 Mon Sep 17 00:00:00 2001 From: Olivier Lacan Date: Sat, 6 Aug 2016 02:01:45 -0400 Subject: [PATCH 14/24] Rewrite README to focus on development --- CONTRIBUTING.md | 8 +-- README.md | 187 +++++++++--------------------------------------- 2 files changed, 33 insertions(+), 162 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c2ea054..46dbc28 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,7 +1 @@ -Hi there, - -Please open a pull request with any suggestions you have. - -Edit files in [`source/`](source/). Each sub-directory is a different language translation of [`source/index.haml`](source/index.haml). - -You will need a maintainer to run `rake publish` for you once changes are merged in in order to update keepachangelog.com. +See [README](README.md#development). diff --git a/README.md b/README.md index c47c8b9..be3d9b6 100644 --- a/README.md +++ b/README.md @@ -1,169 +1,46 @@ # Keep a CHANGELOG [![version](https://img.shields.io/badge/version-0.3.0-blue.svg)][CHANGELOG] -## Don’t let your friends dump git logs into CHANGELOGs™ +Don’t let your friends dump git logs into CHANGELOGs™ -### What’s a change log? -A change log is a file which contains a curated, chronologically ordered -list of notable changes for each version of a project. +This repository generates http://keepachangelog.com/. - +## Development +### Dependencies -### What’s the point of a change log? -To make it easier for users and contributors to see precisely what -notable changes have been made between each release (or version) of the project. +- Ruby ([see version][ruby-version], [rbenv][rbenv] recommended) +- Bundler (`gem install bundler`) -### Why should I care? -Because software tools are for people. If you don’t care, why are -you contributing to open source? Surely, there must be a kernel (ha!) -of care somewhere in that lovely little brain of yours. +### Installation -I [talked with Adam Stacoviak and Jerod Santo on The Changelog][thechangelog] -(fitting, right?) podcast about why maintainers and -contributors should care, and the motivations behind this project. -If you can spare the time (1:06), it’s a good listen. +- `git clone https://github.com/olivierlacan/keep-a-changelog.git` +- `cd keep-a-changelog` +- `bundle install` +- `middleman` starts the local development server at http://localhost:4567 -### What makes a good change log? -I’m glad you asked. +### Deployment +- `rake publish` builds and pushes to the `gh-pages` branch -A good change log sticks to these principles: +### Translations -- It’s made for humans, not machines, so legibility is crucial. -- Easy to link to any section (hence Markdown over plain text). -- One sub-section per version. -- List releases in reverse-chronological order (newest on top). -- Write all dates in `YYYY-MM-DD` format. (Example: `2012-06-02` for `June 2nd, 2012`.) It’s international, [sensible](https://xkcd.com/1179/), and language-independent. -- Explicitly mention whether the project follows [Semantic Versioning][semver]. -- Each version should: - - List its release date in the above format. - - Group changes to describe their impact on the project, as follows: - - `Added` for new features. - - `Changed` for changes in existing functionality. - - `Deprecated` for once-stable features removed in upcoming releases. - - `Removed` for deprecated features removed in this release. - - `Fixed` for any bug fixes. - - `Security` to invite users to upgrade in case of vulnerabilities. +Create a new directory in [`source/`][source] named after the ISO 639-1 code +for the language you wish to translate Keep a CHANGELOG to. For example, +assuming you want to translate to French Canadian: +- create the `source/fr-CA` directory. +- duplicate the `source/en-US/index.html.haml` file in `source/fr-CA`. +- edit `source/fr-CA/index.html.haml` until your translation is ready. +- commit your changes to your own [fork][fork] +- submit a [Pull Request][pull-request] with your changes -### How can I minimize the effort required? -Always have an `"Unreleased"` section at the top for keeping track of any -changes. +It may take some time to review your submitted Pull Request. Try to involve a +few native speakers of the language you're translating to in the Pull Request +comments. They'll help review your translation for simple mistakes and give us +a better idea of whether your translation is accurate. -This serves two purposes: - -- People can see what changes they might expect in upcoming releases -- At release time, you just have to change `"Unreleased"` to the version number - and add a new `"Unreleased"` header at the top. - -### What makes unicorns cry? -Alright…let’s get into it. - -- **Dumping a diff of commit logs.** Just don’t do that, you’re helping nobody. -- **Not emphasizing deprecations.** When people upgrade from one version to - another, it should be painfully clear when something will break. -- **Dates in region-specific formats.** In the U.S., people put the month first - ("06-02-2012" for June 2nd, 2012, which makes *no* sense), while many people - in the rest of the world write a robotic-looking "2 June 2012", yet pronounce - it differently. "2012-06-02" works logically from largest to smallest, doesn't - overlap in ambiguous ways with other date formats, and is an - [ISO standard](http://www.iso.org/iso/home/standards/iso8601.htm). Thus, it - is the recommended date format for change logs. - -There’s more. Help me collect those unicorn tears by -[opening an issue][issues] -or a pull request. - -### Is there a standard change log format? -Sadly, no. Calm down. I know you're furiously rushing to find that link -to the GNU change log style guide, or the two-paragraph GNU NEWS file -"guideline". The GNU style guide is a nice start but it is sadly naive. -There's nothing wrong with being naive but when people need -guidance it's rarely very helpful. Especially when there are many -situations and edge cases to deal with. - -This project [contains what I hope will become a better CHANGELOG file convention][CHANGELOG]. -I don't think the status quo is good enough, and I think that as a community we -can come up with better conventions if we try to extract good practices from -real software projects. Please take a look around and remember that -[discussions and suggestions for improvements are welcome][issues]! - -### What should the change log file be named? -Well, if you can’t tell from the example above, `CHANGELOG.md` is the -best convention so far. - -Some projects also use `HISTORY.txt`, `HISTORY.md`, `History.md`, `NEWS.txt`, -`NEWS.md`, `News.txt`, `RELEASES.txt`, `RELEASE.md`, `releases.md`, etc. - -It’s a mess. All these names only makes it harder for people to find it. - -### Why can’t people just use a `git log` diff? -Because log diffs are full of noise — by nature. They could not make a suitable -change log even in a hypothetical project run by perfect humans who never make -typos, never forget to commit new files, never miss any part of a refactoring. -The purpose of a commit is to document one atomic step in the process by which -the code evolves from one state to another. The purpose of a change log is to -document the noteworthy differences between these states. - -As is the difference between good comments and the code itself, -so is the difference between a change log and the commit log: -one describes the *why*, the other the how. - -### Can change logs be automatically parsed? -It’s difficult, because people follow wildly different formats and file names. - -[Vandamme][vandamme] is a Ruby gem -created by the [Gemnasium][gemnasium] team and which parses -many (but not all) open source project change logs. - -### Why do you alternate between spelling it "CHANGELOG" and "change log"? -"CHANGELOG" is the name of the file itself. It's a bit shouty but it's a -historical convention followed by many open source projects. Other -examples of similar files include [`README`](README.md), [`LICENSE`](LICENSE), -and [`CONTRIBUTING`](CONTRIBUTING.md). - -The uppercase naming (which in old operating systems made these files stick -to the top) is used to draw attention to them. Since they're important -metadata about the project, they could be useful to anyone intending to use -or contribute to it, much like [open source project badges][shields]. - -When I refer to a "change log", I'm talking about the function of this -file: to log changes. - -### What about yanked releases? -Yanked releases are versions that had to be pulled because of a serious -bug or security issue. Often these versions don't even appear in change -logs. They should. This is how you should display them: - -`## 0.0.5 - 2014-12-13 [YANKED]` - -The `[YANKED]` tag is loud for a reason. It's important for people to -notice it. Since it's surrounded by brackets it's also easier to parse -programmatically. - -### Should you ever rewrite a change log? -Sure. There are always good reasons to improve a change log. I regularly open -pull requests to add missing releases to open source projects with unmaintained -change logs. - -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 -change log in this case. - -### How can I contribute? -This document is not the **truth**; it’s my carefully considered -opinion, along with information and examples I gathered. -Although I provide an actual [CHANGELOG][] on [the GitHub repo][gh], -I have purposefully not created a proper *release* or clear list of rules -to follow (as [SemVer.org][semver] does, for instance). - -This is because I want our community to reach a consensus. I believe the -discussion is as important as the end result. - -So please [**pitch in**][gh]. +Thank you for your help improving software one changelog at a time! [CHANGELOG]: ./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/ +[rbenv]: https://github.com/rbenv/rbenv +[ruby-version]: .ruby-version +[source]: source/ +[pull-request]: https://help.github.com/articles/creating-a-pull-request/ +[fork]: https://help.github.com/articles/fork-a-repo/ From 8ca917682e74f9af04c8e3a2fcd53dee8ac3b226 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Magnus=20=C3=96sterlund?= Date: Sat, 6 Aug 2016 17:46:51 +0200 Subject: [PATCH 15/24] Update Swedish to 0.3.0 --- CHANGELOG.md | 2 +- config.rb | 3 ++- source/sv/{index.haml => 0.3.0/index.html.haml} | 5 ++++- 3 files changed, 7 insertions(+), 3 deletions(-) rename source/sv/{index.haml => 0.3.0/index.html.haml} (98%) diff --git a/CHANGELOG.md b/CHANGELOG.md index 150e391..463d923 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,7 +6,7 @@ This project adheres to [Semantic Versioning](http://semver.org/). ### Added - zh-CN and zh-TW translations from @tianshuo. - de translation from @mpbzh. -- sv translated from @magol +- sv translation from @magol ## [0.3.0] - 2015-12-03 ### Added diff --git a/config.rb b/config.rb index 01d6293..1ecca8a 100644 --- a/config.rb +++ b/config.rb @@ -11,7 +11,8 @@ $languages = { "pt-BR" => "Brazilian Portugese", ru: "Pyccкий", "zh-CN" => "简体中文", - "zh-TW" => " 繁體中文" + "zh-TW" => " 繁體中文", + "sv" => "Svenska" } activate :i18n, diff --git a/source/sv/index.haml b/source/sv/0.3.0/index.html.haml similarity index 98% rename from source/sv/index.haml rename to source/sv/0.3.0/index.html.haml index d5d2b76..f631ab2 100644 --- a/source/sv/index.haml +++ b/source/sv/0.3.0/index.html.haml @@ -2,6 +2,7 @@ description: Håll en ändringslogg title: Håll en ändringslogg language: sv +version: 0.3.0 --- :markdown @@ -9,11 +10,13 @@ language: sv ## Låt inte dina vänner slänga in en git logs i CHANGELOG™ + Version **#{current_page.metadata[:page][:version]}** + ### Vad är en ändringslogg? En ändringslogg är en fil innehållandes en sammanfattad, kronologiskt ordnad lista över ändringar för varje version av ett projekt. -%pre.changelog= File.read(File.expand_path("../../CHANGELOG.md", __FILE__)) +%pre.changelog= File.read("CHANGELOG.md") :markdown ### Vad är meningen med en ändringslogg? From beb0d31ec485362a00912f34ad53d24d57d2f0de Mon Sep 17 00:00:00 2001 From: Emre Erkan Date: Sat, 6 Aug 2016 20:53:00 +0300 Subject: [PATCH 16/24] Updated folder structure for verrsion 0.3.0 --- source/tr-TR/{index.haml => 0.3.0/index.html.haml} | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) rename source/tr-TR/{index.haml => 0.3.0/index.html.haml} (97%) diff --git a/source/tr-TR/index.haml b/source/tr-TR/0.3.0/index.html.haml similarity index 97% rename from source/tr-TR/index.haml rename to source/tr-TR/0.3.0/index.html.haml index e9ba68d..fddcac6 100644 --- a/source/tr-TR/index.haml +++ b/source/tr-TR/0.3.0/index.html.haml @@ -2,6 +2,7 @@ description: Değişiklik kaydı tutun title: Değişiklik kaydı tutun language: tr-TR +version: 0.3.0 --- :markdown @@ -13,7 +14,7 @@ language: tr-TR Değişiklik kayıtları bir proje için özel olarak hazırlanmış, tarihsel sıralamayla sıralanmış, önemli değişikliklerin bir bütünüdür. -%pre.changelog= File.read(File.expand_path("../../CHANGELOG.md", __FILE__)) +%pre.changelog= File.read("CHANGELOG.md") :markdown ### Değişikliklerin kayıtlarını tutmanın anlamı ne? @@ -42,7 +43,7 @@ language: tr-TR - Tüm tarihleri `YYYY-AA-GG` biçiminde yazın. (Örneğin `2 Haziran 2012` için `2012-06-02`.) Uluslararasıdır, [anlamlıdır](http://xkcd.com/1179/), ve lisan bağımsızdır. - [Anlamsal sürümlemeyi][semver] destekleyip desteklemediğini özellikle belirtin. - Her sürümde olması gerekenler: - - Üstteki biçimde dağıtım tarihi. + - Üstteki biçimde dağıtım tarihi. - Projeye etkileri bakımından değişiklikleri gruplayın, şöyle ki: - `Eklendi`: yeni özellikler için. - `Değişti`: var olan beceriler değiştiyse. @@ -108,7 +109,7 @@ language: tr-TR kayıtları ise bu durumlar arasında, önem arz eden değişiklikleri belgelemeyi amaçlıyor. - İyi yorumla ve kodun kendisi arasındaki fark, + İyi yorumlar ve kodun kendisi arasındaki fark, aynı şekilde değişiklik kayıtları ve commit kayıtları arasındaki gibidir: biri *neden* olduğunu, diğeri nasıl olduğunu açıklar. @@ -132,7 +133,7 @@ language: tr-TR "Değişiklik kaydı"ndan bahsettiğim zamanlar bu dosyanın işlevinden bahsediyorum: Değişiklikleri kaydetmek. - ### Geri çekilen dağıtımlar? + ### Peki ya Geri çekilen dağıtımlar? Geri çekilen dağıtımlar, önemli hatalar ya da güvenlik sebepleri nedeniyle yayından geri çekilen sürümlerdir. Genelde bu sürümler değişiklik kayıtlarında görüntülenmezler. Görünmeliler. Tam da şu şekilde görünmeliler: From c068d450d81ab7c1bd486652f3cdc3c8ff3c8ca6 Mon Sep 17 00:00:00 2001 From: Olivier Lacan Date: Sat, 6 Aug 2016 17:19:06 -0400 Subject: [PATCH 17/24] Fix typo in Swedish version --- source/sv/0.3.0/index.html.haml | 74 ++++++++++++++++----------------- 1 file changed, 37 insertions(+), 37 deletions(-) diff --git a/source/sv/0.3.0/index.html.haml b/source/sv/0.3.0/index.html.haml index f631ab2..7bc0121 100644 --- a/source/sv/0.3.0/index.html.haml +++ b/source/sv/0.3.0/index.html.haml @@ -13,7 +13,7 @@ version: 0.3.0 Version **#{current_page.metadata[:page][:version]}** ### Vad är en ändringslogg? - En ändringslogg är en fil innehållandes en sammanfattad, kronologiskt ordnad + En ändringslogg är en fil innehållandes en sammanfattad, kronologiskt ordnad lista över ändringar för varje version av ett projekt. %pre.changelog= File.read("CHANGELOG.md") @@ -22,28 +22,28 @@ version: 0.3.0 ### Vad är meningen med en ändringslogg? För att göra det enkelt för användare och medarbetare att se exakt vilka viktiga ändringar som har gjort mellan varje utgåva (eller version) av projektet. - + ### Varför ska jag bry mig? - Därför att mjukvaruverktyg är för människor. Om du inte bryr dig, varför - bidrar du till öppen källkod? Visst finns det väl någon del i din vackra + Därför att mjukvaruverktyg är för människor. Om du inte bryr dig, varför + bidrar du till öppen källkod? Visst finns det väl någon del i din vackra hjärna som bryr sig. Jag [pratade med Adam Stacoviak och Jerod Santo på The Changelog][thechangelog] (passande, eller hur?) podcast om varför ansvariga och bidragsgivare bör bry sig, - och motiveringen bakom detta projekt. + och motiveringen bakom detta projekt. Om du kan avvara lite tid (1:06), rekommenderar jag att lyssna på det. ### Vad gör en bra ändringslogg? Jag är glad att du frågade. En bra ändringslogg håller sig till dessa principer: - + - Den är skapad för människor, inte maskiner, så läsbarhet är avgörande. - - Lätt att länka till valfri sektion (därav Markdown framför klartext). - - En undersektion per version. + - Lätt att länka till valfri sektion (därav Markdown framför klartext). + - En undersektion per version. - Lista utgåvor i omvänd kronologisk ordning (nyast högst upp). - Skriv alla datum på formatet `YYYY-MM-DD` - (exempel: `2012-06-02` för 2:a juni 2012). Det är internationellt, + (exempel: `2012-06-02` för 2:a juni 2012). Det är internationellt, [förnuftigt](http://xkcd.com/1179/) och språkoberoende. - Ange uttryckligen att projektet följer [Semantisk versionshantering][SemVer]. - Varje version bör: @@ -68,15 +68,15 @@ version: 0.3.0 ### Vad får änglarna att gråta? Okej...låt oss gå genom det. - + - **Dumpa ut en diff från commit-loggen.** Gör helt enkelt inte så, du hjälper ingen. - **Inte betona `deprecations`.** När folk uppgraderar från en version till en annan ska det vara smärtsamt uppenbart om något förväntas gå sönder. - - **Datum i region-specifikt format.** I USA lägger folk månaden föst - ("06-02-2012" för 2:a juni 2012, vilket bara är *konstigt*), medan många + - **Datum i region-specifikt format.** I USA lägger folk månaden föst + ("06-02-2012" för 2:a juni 2012, vilket bara är *konstigt*), medan många andra runt om i världen skriver "2 June 2012" men uttala det annorlunda. "2012-06-02" fungerar logiskt från största till minsta, inte överlappar på ett - tvetydligt sätt med andra datumformat, och det är en + tvetydligt sätt med andra datumformat, och det är en [ISO-standard](http://www.iso.org/iso/home/standards/iso8601.htm). Dessutom är det rekommenderat datumformat för ändringsloggar. @@ -88,20 +88,20 @@ version: 0.3.0 ### Finns det ett standardformat på ändringsloggar? Tyvärr inte. Men lugn. Jag vet att du frustrerad kommer att rusa iväg för att hitta den där länken till GUS:s format för ändringsloggar, eller den två stycken långa - GNU NEWS-filen med "guideline". Stilguiden från GNU är en bra start, men den är - tyvärr allt för naiv. Det är inget fel med att vara naiv, men när människor + GNU NEWS-filen med "guideline". Stilguiden från GNU är en bra start, men den är + tyvärr allt för naiv. Det är inget fel med att vara naiv, men när människor behöver vägledning är det inte speciellt hjälpsamt. Speciellt när det är många - olika situationer och specialfall att hantera. + olika situationer och specialfall att hantera. Detta projekt [innehåller vad jag hoppas kommer att bli en bättre filkonvention - för CHANGELOG][CHANGELOG]. Jag tror inte att status quo är tillräckligt bra, + för CHANGELOG][CHANGELOG]. Jag tror inte att status quo är tillräckligt bra, och jag tror att vi tillsammans kan komma fram till en bättre konvention - om vi försöker att plocka ut bra erfarenheter från riktiga mjukvaruprojekt. + om vi försöker att plocka ut bra erfarenheter från riktiga mjukvaruprojekt. Titta runt och kom ihåg att [diskussioner och förbättringsförslag är välkomna][issues]! ### Vad bör filen med ändringsloggen heta? Tja, om du inte kan lista ut det från exemplen ovan är `CHANGELOG.md` - den bästa konvention hittills. + den bästa konvention hittills. En del projekt använder också `HISTORY.txt`, `HISTORY.md`, `History.md`, `NEWS.txt`, `NEWS.md`, `News.txt`, `RELEASES.txt`, `RELEASE.md`, `releases.md`, etc. @@ -109,15 +109,15 @@ version: 0.3.0 Det är en verklig röra. Alla dessa namn gör det bara svårare för människor att hitta. ### Varför kan folk inte bara använda en diff från `git log`? - Eftersom logg-diffar av naturen är fulla med brus. Det kan inte ens användas + Eftersom logg-diffar av naturen är fulla med brus. Det kan inte ens användas för att göra en lämplig ändringslogg ens i ett hypotetiskt projekt drivet av - perfekta människor som aldrig skriver fel, aldrig glömmer att checka in nya filer - eller aldrig glömmer någon del av en refaktorering. Syftet med en commit är att - dokumentera ett enskilt steg i processen då koden utvecklas från ett tillstånd till + perfekta människor som aldrig skriver fel, aldrig glömmer att checka in nya filer + eller aldrig glömmer någon del av en refaktorering. Syftet med en commit är att + dokumentera ett enskilt steg i processen då koden utvecklas från ett tillstånd till ett annat. Syftet med en ändringslogg är att dokumentera de anmärkningsvärda skillnaderna mellan dessa tillstånd. - På samma sätt som det är skillnad mellan bra kommentarer och själva koden, + På samma sätt som det är skillnad mellan bra kommentarer och själva koden, är det skillnad mellan ändringsloggen och commit-loggen: en beskriver "varför" och den andra "hur". @@ -127,16 +127,16 @@ version: 0.3.0 [Vandamme][vandamme] är en Ruby gem skapad av gruppen bakom [Gemnasium][gemnasium] som tolkar många (men inte alla) ändringsloggar för öppen källkod. - + ### Varför alternerar du mellan att skriva det som "CHANGELOG" och "ändringslogg"?" - "CHANGELOG" är namnet på själva filen. Det sticker ut lite, men det är en + "CHANGELOG" är namnet på själva filen. Det sticker ut lite, men det är en historisk konvention använt i många öppen källkodsprojekt. Andra exempel på liknande filer är [`README`][README], [`LICENSE`][LICENSE] och [`CONTRIBUTING`][CONTRIBUTING]. - - De stora bokstäverna i namnen (som gjorde att de i äldre operativsystem - hamnade högst upp) används för att dra uppmärksamhet till dem. Då de är - viktig metadata om projektet borde de vara användbara för att alla som + + De stora bokstäverna i namnen (som gjorde att de i äldre operativsystem + hamnade högst upp) används för att dra uppmärksamhet till dem. Då de är + viktig metadata om projektet borde de vara användbara för att alla som vill använda eller bidra till det, ungefär som [open source project badges][shields]. När jag refererar till "ändringslogg" pratar jag om syftet med denna fil: @@ -144,21 +144,21 @@ version: 0.3.0 ### Hur är det med brådskande utgåvor ("yanked")? Brådskande utgåvor är versioner som måste släppas p.g.a. alvarliga - buggar eller säkerhetsproblem. Oftast brukar dessa versioner inte ens + buggar eller säkerhetsproblem. Oftast brukar dessa versioner inte ens finnas med i ändringsloggarna. De borde det. Så här borde du visa dem: `## 0.0.5 - 2014-12-13 [YANKED]` Taggen `[YANKED]` står ut av en anledning, det är viktigt för människor - att se den. Då den är omsluten med hakparenteser är det också lättare + att se den. Då den är omsluten med hakparenteser är det också lättare för ett program att tolka. ### Borde du någonsin förändra en ändringslogg? - Självklart. Det finns alltid en bra anlending att förbättra en ändringslogg. + Självklart. Det finns alltid en bra anlending att förbättra en ändringslogg. Jag öppnar regelbundet pull requests för att lägga till saknade utgåvor för öppen källkodsprojekt som inte tar hand om sin ändringslogg. - Det kan också hända att du upptäcker att du glömt att ta upp en icke + Det kan också hända att du upptäcker att du glömt att ta upp en icke bakåtkompatibel förändring i en version. I sådana fall är det självklart viktigt att uppdatera din ändringslogg. @@ -169,10 +169,10 @@ version: 0.3.0 har jag avsiktligt inte skapat en egentlig *utgåva* eller en tydlig lista med regler att följa (som t.ex. [SemVer.org][semver] gör). - Detta beror på att jag vill att vår gemenskap ska nå samförstånd. Jag + Detta beror på att jag vill att vår gemenskap ska nå samförstånd. Jag tror att diskussionen är lika viktig som slutresultatet. - - Så välkomna att [**diskutera**]][gh]. + + Så välkomna att [**diskutera**][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 From df94619e6fc7921ab1da04b989ed62b38bd4439a Mon Sep 17 00:00:00 2001 From: Olivier Lacan Date: Sat, 6 Aug 2016 23:16:29 -0400 Subject: [PATCH 18/24] Add Turkish to language nav Also reorganized alphabetically. --- config.rb | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/config.rb b/config.rb index 1ecca8a..41a75da 100644 --- a/config.rb +++ b/config.rb @@ -5,14 +5,15 @@ # ----- Site ----- # $last_version = "0.3.0" $languages = { - de: "Deutsch", - en: "English", "es-ES" => "Español", "pt-BR" => "Brazilian Portugese", - ru: "Pyccкий", + "sv" => "Svenska", "zh-CN" => "简体中文", "zh-TW" => " 繁體中文", - "sv" => "Svenska" + de: "Deutsch", + en: "English", + ru: "Pyccкий", + "tr-TR" => "Türkçe" } activate :i18n, From 8b18b4ba3c47682fa0ada147ca062c27d6ba62ef Mon Sep 17 00:00:00 2001 From: Olivier Lacan Date: Sun, 7 Aug 2016 00:33:18 -0400 Subject: [PATCH 19/24] Add Turkish translation to CHANGELOG --- CHANGELOG.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 463d923..14729b9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,7 +6,8 @@ This project adheres to [Semantic Versioning](http://semver.org/). ### Added - zh-CN and zh-TW translations from @tianshuo. - de translation from @mpbzh. -- sv translation from @magol +- sv translation from @magol. +- tr-TR translation from @karalamalar. ## [0.3.0] - 2015-12-03 ### Added From 3c40af2eca616ef8f8d05161e1c179721e4ad613 Mon Sep 17 00:00:00 2001 From: Olivier Lacan Date: Sun, 7 Aug 2016 00:34:55 -0400 Subject: [PATCH 20/24] Mention versioning in changelog --- CHANGELOG.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 14729b9..b3257eb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,10 @@ This project adheres to [Semantic Versioning](http://semver.org/). - sv translation from @magol. - tr-TR translation from @karalamalar. +### Changed +- Start versioning based on the current English version at 0.3.0 to help +translation authors keep things up-to-date. + ## [0.3.0] - 2015-12-03 ### Added - RU translation from @aishek. From c844dcacdcce8d026f0867b7782866d6d5b11492 Mon Sep 17 00:00:00 2001 From: Olivier Lacan Date: Sun, 7 Aug 2016 00:38:40 -0400 Subject: [PATCH 21/24] Tighten words in site title --- source/assets/stylesheets/application.css.sass | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/source/assets/stylesheets/application.css.sass b/source/assets/stylesheets/application.css.sass index 40aa1ce..0b8d1ee 100644 --- a/source/assets/stylesheets/application.css.sass +++ b/source/assets/stylesheets/application.css.sass @@ -15,11 +15,12 @@ a:hover h1 color: #C647BF - font-size: 3.8em + font-size: 4.1em font-weight: bold font-family: $source-code-font-family margin-bottom: 0 line-height: 1 + word-spacing: -0.3em h2 margin-top: 0 From 6d8f4ad67832352ce9996d4082cffd1500c459f7 Mon Sep 17 00:00:00 2001 From: Emre Erkan Date: Sun, 7 Aug 2016 20:54:16 +0300 Subject: [PATCH 22/24] Just a small fix. --- source/tr-TR/0.3.0/index.html.haml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/tr-TR/0.3.0/index.html.haml b/source/tr-TR/0.3.0/index.html.haml index fddcac6..a08e66b 100644 --- a/source/tr-TR/0.3.0/index.html.haml +++ b/source/tr-TR/0.3.0/index.html.haml @@ -150,8 +150,8 @@ version: 0.3.0 için çekme istekleri yapıyorum. Ayrıca bir sürümdeki notların arasında önemli bir değişiklikten bahsetmeyi - unutmuş olduğunuzu fark edebilirsiniz. Değişiklik kütüğünüzü bu bilgi ışığında - güncellemeniz gerekliliği gün gibi ortada. + unutmuş olduğunuzu fark edebilirsiniz. Değişiklik kayıtlarınızı bu bilgi ışığında + güncellemeniz gerektiği gün gibi ortada. ### Nasıl katkıda bulunabilirim? Bu belge **doğrunun kendisi** değil; benim hesaplı görüşlerimdir. Beraberinde From d062ea3a36b3f52540af00fa9dd586afd16b752d Mon Sep 17 00:00:00 2001 From: Olivier Lacan Date: Sun, 7 Aug 2016 15:07:11 -0400 Subject: [PATCH 23/24] This project isn't sponsored by Code School So no point in mentioning it in the footer. --- source/layouts/layout.html.haml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/source/layouts/layout.html.haml b/source/layouts/layout.html.haml index 5afea05..e6ddcab 100644 --- a/source/layouts/layout.html.haml +++ b/source/layouts/layout.html.haml @@ -44,8 +44,7 @@ %p.about #{link_to "Typed", "https://github.com/olivierlacan/keep-a-changelog/"} with trepidation by - #{link_to "Olivier Lacan", "http://olivierlacan.com/"} from - #{link_to "Code School", "https://www.codeschool.com/"}. + #{link_to "Olivier Lacan", "http://olivierlacan.com/"}. - unless config.gauges_id.blank? :javascript From 201f2f1d097b74eafbd89944a47d277a44b44485 Mon Sep 17 00:00:00 2001 From: Arthur Maltson Date: Sat, 20 Aug 2016 00:39:16 -0400 Subject: [PATCH 24/24] Modified per PR comment --- CHANGELOG.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index df1ae97..490a04c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,7 +1,8 @@ # Change Log All notable changes to this project will be documented in this file. -This project adheres to [Semantic Versioning](http://semver.org/). -The format conforms to [Keep a Changelog](http://keepachangelog.com/). + +The format is based on [Keep a Changelog](http://keepachangelog.com/) +and this project adheres to [Semantic Versioning](http://semver.org/). ## [Unreleased] ### Added