Merge pull request #110 from olivierlacan/versioning

Start versioning from 0.3.0

.gitignore

@@ -3,3 +3,4 @@
 /.cache
 /.sass-cache
 /build
+/_site

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"

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

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: "en/#{$last_version}/index.html"
+
+$languages.each do |language|
+  language_param = language.last.parameterize
+  redirect "#{language.first}/index.html", to: "#{language.first}/#{$last_version}/index.html"
+end
+
 # ----- Assets ----- #
 
 set :css_dir, 'assets/stylesheets'

routes.rb

@@ -0,0 +1 @@
+redirect "/", to: "/0.3.0/"

source/de/0.3.0/index.haml

@@ -2,6 +2,7 @@
 description: Keep a Changelog
 title: Keep a Changelog
 language: de
+version: 0.3.0
 ---
 
 :markdown
@@ -9,11 +10,13 @@ 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, "CHANGELOG.md"))
 
 :markdown
   ### Was ist der Zweck eines Changelogs?

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/

source/es-ES/0.3.0/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, "CHANGELOG.md"))
 
 :markdown
   ### Cuál es el propósito del change log?

source/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, "CHANGELOG.md"))
 
 :markdown
   ### What’s the point of a change log?

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
 

source/pt-BR/0.3.0/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, "CHANGELOG.md"))
 
 :markdown
   ### Para que serve um *change log*?

source/ru/0.3.0/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, "CHANGELOG.md"))
 
 :markdown
   ### Для чего нужен лог изменений?

source/zh-CN/0.3.0/index.haml

@@ -2,6 +2,7 @@
 description: 如何维护更新日志
 title: 如何维护更新日志
 language: zh-CN
+version: 0.3.0
 ---
 
 :markdown
@@ -9,12 +10,14 @@ 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, "CHANGELOG.md"))
 
 :markdown
   ### 为何要提供更新日志？

source/zh-TW/0.3.0/index.haml

@@ -2,6 +2,7 @@
 description: 如何維護更新日誌
 title: 如何維護更新日誌
 language: zh-TW
+version: 0.3.0
 ---
 
 :markdown
@@ -9,12 +10,14 @@ 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, "CHANGELOG.md"))
 
 :markdown
   ### 為何要提供更新日誌？