Merge remote-tracking branch 'olivierlacan/master'

.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

.gitignore

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

.ruby-version

@@ -1 +1 @@
-2.3.0
+2.3.1

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 translation from @magol
 
 ## [0.3.0] - 2015-12-03
 ### Added

CONTRIBUTING.md

@@ -1,7 +1 @@
-Hi there,
+See [README](README.md#development).
-
-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.

Gemfile

@@ -1,12 +1,12 @@
 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"
 gem "middleman-minify-html"
 gem "middleman-syntax"
-gem 'middleman-gh-pages'
+gem "middleman-gh-pages"
-
 gem "redcarpet"
+gem "pry"

Gemfile.lock

@@ -1,165 +1,149 @@
 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)
+    addressable (2.4.0)
-    autoprefixer-rails (6.0.3)
+    autoprefixer-rails (6.4.0.1)
       execjs
-      json
+    backports (3.6.8)
-    capybara (2.4.4)
+    coderay (1.1.1)
-      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)
     coffee-script (2.4.1)
       coffee-script-source
       execjs
-    coffee-script-source (1.9.1.1)
+    coffee-script-source (1.10.0)
-    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)
     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)
+    eventmachine (1.2.0.1)
-    execjs (2.6.0)
+    execjs (2.7.0)
-    ffi (1.9.10)
+    fast_blank (1.0.0)
+    fastimage (2.0.0)
+      addressable (~> 2)
+    ffi (1.9.14)
     haml (4.0.7)
       tilt
-    hike (1.2.3)
+    hamster (3.0.0)
-    hooks (0.4.1)
+      concurrent-ruby (~> 1.0)
-      uber (~> 0.0.14)
+    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)
+    kramdown (1.11.1)
-    listen (3.0.3)
+    listen (3.0.8)
-      rb-fsevent (>= 0.9.3)
+      rb-fsevent (~> 0.9, >= 0.9.4)
-      rb-inotify (>= 0.9)
+      rb-inotify (~> 0.9, >= 0.9.7)
-    middleman (3.4.0)
+    memoist (0.14.0)
+    method_source (0.8.2)
+    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-cli (= 4.1.10)
-      middleman-sprockets (>= 3.1.2)
+      middleman-core (= 4.1.10)
       sass (>= 3.4.0, < 4.0)
-      uglifier (~> 2.5)
+    middleman-autoprefixer (2.7.0)
-    middleman-autoprefixer (2.6.1)
+      autoprefixer-rails (>= 6.3.1, < 7.0.0)
-      autoprefixer-rails (~> 6.0.1)
       middleman-core (>= 3.3.3)
-    middleman-blog (3.5.3)
+    middleman-blog (4.0.1)
-      addressable (~> 2.3.5)
+      addressable (~> 2.3)
-      middleman-core (~> 3.2)
+      middleman-core (>= 4.0.0)
       tzinfo (>= 0.3.0)
-    middleman-core (3.4.0)
+    middleman-cli (4.1.10)
-      activesupport (~> 4.1)
+      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)
+      listen (~> 3.0.0)
-      padrino-helpers (~> 0.12.3)
+      memoist (~> 0.14)
+      padrino-helpers (~> 0.13.0)
+      parallel
       rack (>= 1.4.5, < 2.0)
-      thor (>= 0.15.2, < 2.0)
+      sass (>= 3.4)
-      tilt (~> 1.4.1, < 2.0)
+      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-syntax (3.0.0)
-      middleman-core (>= 3.3)
+      middleman-core (>= 3.2)
-      sprockets (~> 2.12.1)
+      rouge (~> 2.0)
-      sprockets-helpers (~> 1.1.0)
+    minitest (5.9.0)
-      sprockets-sass (~> 1.3.0)
+    padrino-helpers (0.13.2)
-    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)
       i18n (~> 0.6, >= 0.6.7)
-      padrino-support (= 0.12.5)
+      padrino-support (= 0.13.2)
-      tilt (~> 1.4.1)
+      tilt (>= 1.4.1, < 3)
-    padrino-support (0.12.5)
+    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)
+      slop (~> 3.4)
     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-fsevent (0.9.7)
-    rb-inotify (0.9.5)
+    rb-inotify (0.9.7)
       ffi (>= 0.5.0)
     redcarpet (3.3.3)
-    rouge (1.10.1)
+    rouge (2.0.5)
-    sass (3.4.19)
+    sass (3.4.22)
-    sprockets (2.12.4)
+    servolux (0.12.0)
-      hike (~> 1.2)
+    slop (3.6.0)
-      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 (3.0.1)
-    uglifier (2.7.2)
+      execjs (>= 0.3.0, < 3)
-      execjs (>= 0.3.0)
-      json (>= 1.8.0)
-    xpath (2.0.0)
-      nokogiri (~> 1.3)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
   addressable
-  middleman (~> 3.4.0)
+  middleman (~> 4.1.0)
   middleman-autoprefixer
   middleman-blog
   middleman-gh-pages
   middleman-livereload
   middleman-minify-html
   middleman-syntax
+  pry
   redcarpet
 
 BUNDLED WITH
-   1.10.6
+   1.12.0

README.md

@@ -1,169 +1,46 @@
-# 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™
+Don’t let your friends dump git logs into CHANGELOGs™
 
-### What’s a change log?
+This repository generates http://keepachangelog.com/.
-A change log is a file which contains a curated, chronologically ordered
-list of notable changes for each version of a project.
 
-<a href="CHANGELOG.md" title="An example of a CHANGELOG file."><iframe src="CHANGELOG.md" width="570" height="350" seamless="seamless" style="border: 1px solid #aaa; padding: 1em; margin: 0 0.5em;"></iframe></a>
+## Development
+### Dependencies
 
-### What’s the point of a change log?
+- Ruby ([see version][ruby-version], [rbenv][rbenv] recommended)
-To make it easier for users and contributors to see precisely what
+- Bundler (`gem install bundler`)
-notable changes have been made between each release (or version) of the project.
 
-### Why should I care?
+### Installation
-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]
+- `git clone https://github.com/olivierlacan/keep-a-changelog.git`
-(fitting, right?) podcast about why maintainers and
+- `cd keep-a-changelog`
-contributors should care, and the motivations behind this project.
+- `bundle install`
-If you can spare the time (1:06), it’s a good listen.
+- `middleman` starts the local development server at http://localhost:4567
 
-### What makes a good change log?
+### Deployment
-I’m glad you asked.
+- `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.
+Create a new directory in [`source/`][source] named after the ISO 639-1 code 
-- Easy to link to any section (hence Markdown over plain text).
+for the language you wish to translate Keep a CHANGELOG to. For example, 
-- One sub-section per version.
+assuming you want to translate to French Canadian:
-- List releases in reverse-chronological order (newest on top).
+- create the `source/fr-CA` directory.
-- 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.
+- duplicate the `source/en-US/index.html.haml` file in `source/fr-CA`.
-- Explicitly mention whether the project follows [Semantic Versioning][semver].
+- edit `source/fr-CA/index.html.haml` until your translation is ready.
-- Each version should:
+- commit your changes to your own [fork][fork]
-  - List its release date in the above format.
+- submit a [Pull Request][pull-request] with your changes
-  - 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?
+It may take some time to review your submitted Pull Request. Try to involve a 
-Always have an `"Unreleased"` section at the top for keeping track of any
+few native speakers of the language you're translating to in the Pull Request
-changes.
+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:
+Thank you for your help improving software one changelog at a time!
-
-- 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].
 
 [CHANGELOG]: ./CHANGELOG.md
-[gemnasium]: https://gemnasium.com
+[rbenv]: https://github.com/rbenv/rbenv
-[gh]: https://github.com/olivierlacan/keep-a-changelog
+[ruby-version]: .ruby-version
-[issues]: https://github.com/olivierlacan/keep-a-changelog/issues
+[source]: source/
-[semver]: http://semver.org
+[pull-request]: https://help.github.com/articles/creating-a-pull-request/
-[shields]: http://shields.io
+[fork]: https://help.github.com/articles/fork-a-repo/
-[thechangelog]: http://5by5.tv/changelog/127
-[vandamme]: https://github.com/tech-angels/vandamme/

config.rb

@@ -3,12 +3,33 @@
 # --------------------------------------
 
 # ----- 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" => " 繁體中文",
+  "sv"    => "Svenska"
+}
+
+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'
@@ -37,7 +58,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
 

routes.rb

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

source/de/0.3.0/index.html.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("CHANGELOG.md")
 
 :markdown
   ### Was ist der Zweck eines Changelogs?

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

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

source/index.html.haml

@@ -0,0 +1,183 @@
+---
+description: Keep a Changelog
+title: Keep a Changelog
+language: en
+version: 0.3.0
+---
+
+: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("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/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)}
@@ -31,13 +31,9 @@
       %header{role: "banner"}
         %nav.locales{role: "navigation"}
           %ul
-            %li= link_to 'english [en]', '/', {rel: "alternate", lang: "en", hreflang: "en"}
+            - $languages.each do |language|
-            %li= link_to 'español [es-ES]', '/es-ES/', {rel: "alternate", lang: "es-ES", hreflang: "es-ES"}
+              %li= link_to "#{language.last} [#{language.first}]", "/#{language.first}/",
-            %li= link_to 'português brasileiro [pt-BR]', '/pt-BR/', {rel: "alternate", lang: "pt-BR", hreflang: "pt-BR"}
+              { rel: "alternate", lang: "#{language}", hreflang: "#{language}" }
-            %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"}
 
       .main{role: "main"}= yield
 
@@ -51,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() {
@@ -59,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);

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

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

source/sv/0.3.0/index.html.haml

@@ -0,0 +1,187 @@
+---
+description: Håll en ändringslogg
+title: Håll en ändringslogg
+language: sv
+version: 0.3.0
+---
+
+:markdown
+  # Håll en CHANGELOG
+
+  ## 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("CHANGELOG.md")
+
+: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 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), 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.  
+  - 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 versionsnumret
+    och lägga till en ny `"Unreleased"` högst upp.
+
+  ### 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 
+    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 rekommenderat datumformat för ändringsloggar.
+
+
+  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 
+  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. 
+
+  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 [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. 
+
+  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 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 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, 
+  ä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.
+  
+  ### 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].
+  
+  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:
+  att logga ändringar.
+
+  ### 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]`
+
+  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 
+  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. 
+  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 
+  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 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 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 
+  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
+  [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/zh-CN/0.3.0/index.html.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("CHANGELOG.md")
 
 :markdown
   ### 为何要提供更新日志？

source/zh-TW/0.3.0/index.html.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("CHANGELOG.md")
 
 :markdown
   ### 為何要提供更新日誌？