Merge remote-tracking branch 'olivierlacan/master'

CHANGELOG.md

@@ -1,23 +1,51 @@
-# Change Log
+# Changelog
 All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
+
+## [1.0.0] - 2017-06-20
 ### Added
-- zh-CN and zh-TW translations from @tianshuo.
+- New visual identity by @tylerfortune8.
-- de translation from @mpbzh.
+- Version navigation.
-- it-IT translation from @roalz.
+- Links to latest released version in previous versions.
-- sv translation from @magol.
+- "Why keep a changelog?" section.
-- tr-TR translation from @karalamalar.
+- "Who needs a changelog?" section.
-- fr translation from @zapashcanon.
+- "How do I make a changelog?" section.
+- "Frequently Asked Questions" section.
+- New "Guiding Principles" sub-section to "How do I make a changelog?".
+- Simplified and Traditional Chinese translations from @tianshuo.
+- German translation from @mpbzh.
+- Italian translation from @roalz.
+- Swedish translation from @magol.
+- Turkish translation from @karalamalar.
+- French translation from @zapashcanon.
+- Brazilian Portugese translation from @aisamu.
+- Polish translation from @amielucha.
 
 ### Changed
+- Start using "changelog" over "change log" since it's the common usage.
 - Start versioning based on the current English version at 0.3.0 to help
 translation authors keep things up-to-date.
-- Fix typos in zh-CN translation.
+- Rewrite "What makes unicorns cry?" section.
-- Fix typos in pt-BR translation.
+- Rewrite "Ignoring Deprecations" sub-section to clarify the ideal
+  scenario.
+- Improve "Commit log diffs" sub-section to further argument against
+  them.
+- Merge "Why can’t people just use a git log diff?" with "Commit log
+  diffs"
+- Fix typos in Simplified Chinese and Traditional Chinese translations.
+- Fix typos in Brazilian Portugese translation.
+- Fix typos in Turkish translation.
+- Fix typos in Czech translation.
+- Fix typos in Swedish translation.
+- Improve phrasing in French translation.
+- Fix phrasing and spelling in German translation.
+
+### Removed
+- Section about "changelog" vs "CHANGELOG".
 
 ## [0.3.0] - 2015-12-03
 ### Added
@@ -27,8 +55,8 @@ translation authors keep things up-to-date.
 
 ## [0.2.0] - 2015-10-06
 ### Changed
-- Remove exclusionary mentions of "open source" since this project can benefit
+- Remove exclusionary mentions of "open source" since this project can
-both "open" and "closed" source projects equally.
+benefit both "open" and "closed" source projects equally.
 
 ## [0.1.0] - 2015-10-06
 ### Added
@@ -94,13 +122,15 @@ notable changes.
 
 ## 0.0.1 - 2014-05-31
 ### Added
-- This CHANGELOG file to hopefully serve as an evolving example of a standardized open source project CHANGELOG.
+- This CHANGELOG file to hopefully serve as an evolving example of a
+  standardized open source project CHANGELOG.
 - CNAME file to enable GitHub Pages custom domain
 - README now contains answers to common questions about CHANGELOGs
 - Good examples and basic guidelines, including proper date formatting.
 - Counter-examples: "What makes unicorns cry?"
 
-[Unreleased]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.3.0...HEAD
+[Unreleased]: https://github.com/olivierlacan/keep-a-changelog/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.3.0...v1.0.0
 [0.3.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.8...v0.1.0

CODE_OF_CONDUCT.md

@@ -0,0 +1,46 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at hi@olivierlacan.com. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

Gemfile.lock

@@ -8,14 +8,14 @@ GEM
       thread_safe (~> 0.3, >= 0.3.4)
       tzinfo (~> 1.1)
     addressable (2.4.0)
-    autoprefixer-rails (6.4.0.1)
+    autoprefixer-rails (6.7.7.2)
       execjs
     backports (3.6.8)
     coderay (1.1.1)
     coffee-script (2.4.1)
       coffee-script-source
       execjs
-    coffee-script-source (1.10.0)
+    coffee-script-source (1.12.2)
     compass-import-once (1.0.5)
       sass (>= 3.2, < 3.5)
     concurrent-ruby (1.0.2)
@@ -117,7 +117,7 @@ GEM
     rb-fsevent (0.9.7)
     rb-inotify (0.9.7)
       ffi (>= 0.5.0)
-    redcarpet (3.3.3)
+    redcarpet (3.4.0)
     rouge (2.0.5)
     sass (3.4.22)
     servolux (0.12.0)
@@ -127,7 +127,7 @@ GEM
     tilt (1.4.1)
     tzinfo (1.2.2)
       thread_safe (~> 0.1)
-    uglifier (3.0.1)
+    uglifier (3.2.0)
       execjs (>= 0.3.0, < 3)
 
 PLATFORMS
@@ -146,4 +146,4 @@ DEPENDENCIES
   redcarpet
 
 BUNDLED WITH
-   1.12.0
+   1.13.6

README.md

@@ -1,6 +1,8 @@
-# Keep a CHANGELOG [![version](https://img.shields.io/badge/version-0.3.0-blue.svg)][CHANGELOG]
+# <img src="https://d3vv6lp55qjaqc.cloudfront.net/items/1L1w0v431V0d1K410f3Y/keepAChangelog-logo-dark.svg" height=150 alt="Keep a Changelog" />
 
-Don’t let your friends dump git logs into CHANGELOGs™
+[![version][version-badge]][CHANGELOG] [![license][license-badge]][LICENSE]
+
+Don’t let your friends dump git logs into changelogs™
 
 This repository generates http://keepachangelog.com/.
 
@@ -15,19 +17,20 @@ This repository generates http://keepachangelog.com/.
 - `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
+- `bundle exec middleman` starts the local development server at http://localhost:4567
 
 ### Deployment
-- `rake publish` builds and pushes to the `gh-pages` branch 
+- `bundle exec rake publish` builds and pushes to the `gh-pages` branch
 
 ### Translations
 
 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, 
+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`.
+- duplicate the `source/en/1.0.0/index.html.haml` file in `source/fr-CA`.
-- edit `source/fr-CA/index.html.haml` until your translation is ready.
+- edit `source/fr-CA/1.0.0/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
 
@@ -39,8 +42,11 @@ a better idea of whether your translation is accurate.
 Thank you for your help improving software one changelog at a time!
 
 [CHANGELOG]: ./CHANGELOG.md
+[LICENSE]: ./LICENSE
 [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/
+[version-badge]: https://img.shields.io/badge/version-1.0.0-blue.svg
+[license-badge]: https://img.shields.io/badge/license-MIT-blue.svg

config.rb

@@ -3,21 +3,83 @@
 # --------------------------------------
 
 # ----- Site ----- #
-$last_version = "0.3.0"
+# Last version should be the latest English version since the manifesto is first
+# written in English, then translated into other languages later.
+$versions = (Dir.entries("source/en") - %w[. ..])
+$last_version = $versions.last
+$previous_version = $versions[$versions.index($last_version) - 1]
+
+# This list of languages populates the language navigation.
+issues_url = 'https://github.com/olivierlacan/keep-a-changelog/issues'
 $languages = {
-  "cs"    => "Čeština",
+  "cs"    => {
-  "de"    => "Deutsch",
+    name: "Čeština"
-  "en"    => "English",
+  },
-  "es-ES" => "Español",
+  "de"    => {
-  "fr"    => "Français",
+    name: "Deutsch",
-  "it-IT" => "Italiano",
+    notice: "Die neuste version (#{$last_version}) ist noch nicht auf Deutsch
-  "pt-BR" => "Brazilian Portugese",
+    verfügbar, aber du kannst sie dir <a href='/en/'>auf Englisch durchlesen</a>
-  "ru"    => "Pyccкий",
+    und <a href='#{issues_url}'>bei der Übersetzung mithelfen</a>."
-  "sl"    => "Slovenščina",
+  },
-  "sv"    => "Svenska",
+  "en"    => {
-  "tr-TR" => "Türkçe",
+    default: true,
-  "zh-CN" => "简体中文",
+    name: "English",
-  "zh-TW" => " 繁體中文"
+    new: "A new version is available"
+  },
+  "es-ES" => {
+    name: "Español",
+    notice: "La última versión (#{$last_version}) aun no está disponible en
+    Español, por ahora puedes <a href='/en/'>leerla en Inglés</a> y
+    <a href='#{issues_url}'>ayudar a traducirla</a>."
+  },
+  "fr"    => {
+    name: "Français",
+    notice: "La dernière version (#{$last_version}) n'est pas encore disponible
+    en français, mais vous pouvez la <a href='/en/'>lire en anglais</a> pour
+    l'instant et <a href='#{issues_url}'>aider à la traduire</a>.",
+    new: "Une nouvelle version est disponible"
+  },
+  "it-IT" => {
+    name: "Italiano",
+    notice: "L'ultima versione (#{$last_version}) non è ancora disponibile in
+    Italiano, ma la potete <a href='/en/'>leggere in Inglese</a> per ora e
+    potete <a href='#{issues_url}'>contribuire a tradurla</a>."
+  },
+  "pl-PL" => {
+    name: "Polskie"
+  },
+  "pt-BR" => {
+    name: "Brazilian Portugese",
+    notice: "A última versão (#{$last_version}) ainda não está disponível em
+    Português mas nesse momento você pode <a href='/en/'>lê-la em inglês</a> e
+    <a href='#{issues_url}'>ajudar em sua tradução</a>."
+  },
+  "ru"    => {
+    name: "Pyccкий",
+    notice: "Самая последняя версия (#{$last_version}) ещё пока не переведена на
+    русский, но вы можете <a href='/en/'>прочитать её на английском</a> и <a
+    href='#{issues_url}'>помочь с переводом</a>."
+  },
+  "sl"    => {
+    name: "Slovenščina"
+  },
+  "sv"    => {
+    name: "Svenska",
+    notice: "Den senaste versionen (#{$last_version}) är ännu inte tillgänglig på Svenska,
+    men du kan <a href='/en/'>läsa det på engelska</a> och även <a
+    href='#{issues_url}'>hjälpa till att översätta det</a>."
+  },
+  "tr-TR" => {
+    name: "Türkçe"
+  },
+  "zh-CN" => {
+    name: "简体中文",
+    notice: "最新版 (#{$last_version}) 暂时还没有翻译到简体中文，您可以阅读最新的英语版，并且帮助翻译，不胜感激。"
+  },
+  "zh-TW" => {
+    name: "繁體中文",
+    notice: "最新版 (#{$last_version}) 暫時還沒有翻譯到繁體中文，您可以閱讀最新的英語版，並且幫助翻譯，不勝感激。"
+  }
 }
 
 activate :i18n,
@@ -31,8 +93,9 @@ set :site_url, 'http://keepachangelog.com'
 redirect "index.html", to: "en/#{$last_version}/index.html"
 
 $languages.each do |language|
-  language_param = language.last.parameterize
+  code = language.first
-  redirect "#{language.first}/index.html", to: "#{language.first}/#{$last_version}/index.html"
+  versions = Dir.entries("source/#{code}") - %w[. ..]
+  redirect "#{code}/index.html", to: "#{code}/#{versions.last}/index.html"
 end
 
 # ----- Assets ----- #
@@ -50,12 +113,38 @@ activate :automatic_image_sizes
 
 activate :syntax
 set :markdown_engine, :redcarpet
-set :markdown, {
+
+## Override default Redcarpet renderer in order to define a class
+class CustomMarkdownRenderer < Redcarpet::Render::HTML
+  def doc_header
+    %Q[<nav role="navigation" class="toc">#{@header}</nav>]
+  end
+
+  def header(text, header_level)
+    slug = text.parameterize
+    tag_name = "h#{header_level}"
+    anchor_link = "<a id='#{slug}' class='anchor' href='##{slug}' aria-hidden='true'></a>"
+    header_tag_open = "<#{tag_name} id='#{slug}'>"
+
+    output = ""
+    output << header_tag_open
+    output << anchor_link
+    output << text
+    output << "</#{tag_name}>"
+
+    output
+  end
+end
+
+$markdown_config = {
   fenced_code_blocks: true,
   footnotes: true,
   smartypants: true,
-  tables: true
+  tables: true,
+  with_toc_data: true,
+  renderer: CustomMarkdownRenderer
 }
+set :markdown, $markdown_config
 
 # --------------------------------------
 #   Helpers
@@ -112,3 +201,23 @@ activate :autoprefixer do |config|
   config.browsers = ['last 2 versions', 'Explorer >= 10']
   config.cascade  = false
 end
+
+# Haml doesn't pick up on Markdown configuration so we have to remove the
+# default Markdown Haml filter and reconfigure one that follows our
+# global configuration.
+
+module Haml::Filters
+  remove_filter("Markdown") #remove the existing Markdown filter
+
+  module Markdown
+    include Haml::Filters::Base
+
+    def renderer
+      $markdown_config[:renderer]
+    end
+
+    def render(text)
+      Redcarpet::Markdown.new(renderer.new($markdown_config)).render(text)
+    end
+  end
+end

routes.rb

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

source/assets/images/keep-a-changelog-mark.svg

@@ -0,0 +1 @@
+<svg id="Layer_1" data-name="Layer 1" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 187.05 184.89"><defs><style>.cls-1{fill:#f4e0c2;}</style></defs><title>Artboard 1 copy 3</title><path class="cls-1" d="M62.09,6.5c-15.39,3.08-27.7,10.71-36.6,22.67C14.11,44.48,7.71,63.39,5.36,88.69c-.92,10,.06,20.05,1.34,31.18a73.74,73.74,0,0,0,15.86,38.56c6.9,8.56,14.82,14.18,24.2,17.19a88.55,88.55,0,0,0,24.67,4.25,45.42,45.42,0,0,0,5.88-.25l3.08-.31c4.24-.43,8.49-.86,12.73-1.37a158.36,158.36,0,0,0,54.68-16.7c14.84-7.75,25.22-19.18,30.84-34,2.62-6.88,3.87-12.67,3.87-18.08a33.91,33.91,0,0,0-.47-5.64c-3-17.59-9.14-32.75-18.9-46.33-12.09-16.83-24.32-28.68-38.48-37.31C103.11,6.76,82.64,2.38,62.09,6.5Zm29.73,8.13c20.19,4.42,38,14.81,52.92,30.87,16.92,18.2,26.56,37.31,29.49,58.42.53,3.91-.09,8.24-.71,12-2.87,17.21-12.3,30.05-28,38.16a155.31,155.31,0,0,1-53,16.14c-4.13.49-8.28.91-13,1.39l-.65.07a50.59,50.59,0,0,1-12.26-.23h0c-5.11-.72-10.89-1.55-16.45-2.87-13.07-3.11-22.7-12-29.42-27.06-5.06-11.37-7.68-24-8-38.7a132.53,132.53,0,0,1,8.5-50.28C25.83,40.4,32.46,27,46.85,19.86,61,12.82,75.74,11.11,91.83,14.63Z"/><path class="cls-1" d="M39.83,44.82C28.74,60.48,23,78.7,22.74,99a74.87,74.87,0,0,0,5.94,32.45c8,19,22.58,30.06,42.21,32,20.68,2,41-2.82,60.49-14.33a60.07,60.07,0,0,0,20.5-19.41,52.54,52.54,0,0,0,8.64-28.54c0-16-7.51-33.07-22.55-50.76a47.36,47.36,0,0,0-5.21-5.23c-23-19.78-44.72-25.81-66.87-18.4C54.05,30.67,45.78,36.43,39.83,44.82ZM148.43,121a50.36,50.36,0,0,1-21.5,22.1c-16.67,9.11-31.92,13.14-47.77,12.67H79c-11.47.45-21.38-2.36-30.31-8.6-5.18-3.61-9.18-8.89-12.24-16.15A80.91,80.91,0,0,1,30,99.42a93.56,93.56,0,0,1,7.57-35.9,89.91,89.91,0,0,1,6.47-12l1.2-2C50.2,41.33,58,37.4,68.19,34c16-5.27,31.72-2.55,49.55,8.56C130.93,50.82,141.12,63,148,78.87,154.56,93.81,154.69,108,148.43,121Z"/><path class="cls-1" d="M104.8,48c-17.06-7.52-32.45-5.88-45.72,4.88C48.76,61.24,42.58,73,39.63,89.81a53.56,53.56,0,0,0,5,34.12c7.85,15.19,20.7,23,37.17,22.56h.06c21.88-1.15,37.79-9.24,48.62-24.76a41.46,41.46,0,0,0,7.84-24,43,43,0,0,0-1.79-12.12C131.2,67.6,120.54,54.95,104.8,48ZM81.6,138.55h-.29c-7.43.59-14.75-1.67-21.77-6.73A27.13,27.13,0,0,1,50,119.1a56.51,56.51,0,0,1-3.8-20.17,62.68,62.68,0,0,1,5.52-25c5-11.51,12.75-18.51,23.78-21.4,9.07-2.36,18.1-1.45,27.59,2.8,13.78,6.16,22.73,17.25,26.62,33s-2,31.1-15.28,40.11C103.49,135.83,92.75,139.14,81.6,138.55Z"/><path class="cls-1" d="M83.47,105.25v14.12H74.93V68.46h8.54V96.28l9.11-9.89h11.16L89.9,100.87l16.81,18.5H95.9Z"/></svg>

source/assets/javascripts/all.js

@@ -1 +1,34 @@
-//= require_tree .
+document.addEventListener("DOMContentLoaded", function(){
+  var select = document.querySelector('.locales select');
+  select.addEventListener('change', function(event){
+    origin = window.location.origin;
+    languageCode = event.currentTarget.selectedOptions[0].value
+    window.location.replace(origin + "/" + languageCode)
+  });
+
+  var faqHeaders = document.querySelectorAll('.frequently-asked-questions h4');
+
+  for (var i = 0; i < faqHeaders.length; ++i) {
+    header = faqHeaders[i]
+    header.addEventListener('click', toggleVisibility);
+  }
+
+  function toggleVisibility(event) {
+    element = event.target;
+    element.classList.toggle('is-visible')
+
+    lastParagraph = element.nextElementSibling;
+    paragraphs = [];
+    paragraphs.push(lastParagraph);
+
+    while (lastParagraph.nextElementSibling.tagName == "P") {
+      lastParagraph = lastParagraph.nextElementSibling;
+      paragraphs.push(lastParagraph)
+    }
+
+    for (var i = 0; i < paragraphs.length; ++i) {
+      paragraph = paragraphs[i]
+      paragraph.classList.toggle('is-visible');
+    }
+  }
+});

source/assets/stylesheets/anchors.sass

@@ -0,0 +1,17 @@
+.anchor
+  display: none
+  font-style: normal
+  font-weight: normal
+  position: absolute
+  right: 100%
+  top: 0
+
+.anchor::before
+  line-height: 3.2
+  content: "∞"
+  color: $color-ocre
+  padding-right: 0.1em
+
+.anchor:hover
+  a
+    text-decoration: none

source/assets/stylesheets/application.css.sass

@@ -1,123 +1,99 @@
-$base-font-family: "Carrois Gothic", "Helvetica Neue", Helvetica, Arial, sans-serif
+$base-font-family: 'Muli', "Helvetica Neue", Helvetica, Arial, sans-serif
 $source-code-font-family: "Source Code Pro", monospace
 
+$color-black: #342828
+$color-white: #FFFFFF
+$color-ocre: #E05735
+$color-gold: #faa930
+$color-bark: #3F2B2D
+$color-sand: #FEECD3
+$color-light-sand: lighten($color-sand, 10%)
+
+@import "layout"
+@import "anchors"
+@import "sections"
+
 html
-  font: 14px/1.4 $base-font-family
+  font: 16px/1.4 $base-font-family
-  color: #333
+  color: #342828
+  background-color: $color-sand
 
 a
-  color: #E10FCE
+  color: $color-ocre
-  font-weight: bold
   text-decoration: none
 
 a:hover
   text-decoration: underline
 
 h1
-  color: #C647BF
+  color: $color-ocre
-  font-size: 4.1em
+  font-size: 3.2em
   font-weight: bold
-  font-family: $source-code-font-family
+  font-family: $base-font-family
   margin-bottom: 0
   line-height: 1
-  word-spacing: -0.3em
+  text-transform: lowercase
+  width: 50%
 
 h2
-  margin-top: 0
+  font-size: 1.2em
+  margin-top: 0.2em
   margin-bottom: 2em
 
 h1, h2
-  text-align: center
+  text-align: left
 
 h3
   font-size: 1.3em
-  font-family: $source-code-font-family
+  font-family: $base-font-family
-  margin-bottom: 0
+  margin-bottom: 1em
   position: relative
   padding-left: .1em
 
 h3:hover .anchor, h3:focus .anchor
   display: block
 
-.anchor
-  display: none
-  font-style: normal
-  font-weight: normal
-  position: absolute
-  right: 100%
-  top: 0
-
-.anchor::before
-  content: '¶'
-
-.anchor:hover
-  text-decoration: none
-
 h3 ~ p
   margin-top: 0
 
-article
+h1, h2, h3
-  margin: 0 auto
+  margin-top: 0
-  width: 640px
-
-article p
-  font-size: 1.3em
-
-article code
-  border-radius: 0.315em
-  border: 1px solid #ccc
-  padding: 0 0.3em 0.040em
-  font-size: 0.9em
-
-article img
-  margin: 0 auto
-  max-width: 100%
-  text-align: center
-  display: block
-  box-shadow: rgba(0, 0, 0, 0.37) 0px 0px 6px
-  border-radius: 7px
-  padding: 0.4em 0.9em
-
-article > ul
-  font-size: 1.2em
-  padding-left: 0
-
-article > ul ul
-  padding-left: 1em
-
-article ul
-  line-height: 1.5
-  list-style-position: inside
-  list-style-type: square
-
-footer
-  font-size: .7em
-  border-top: 1px solid #e9e6e1
-  margin-top: 1em
-  margin-bottom: 2em
   padding-top: 1em
 
-.license
+.about
-  float: left
+  text-align: center
 
 .about
-  float: right
-
-.about, .license
   margin-top: 0
 
-.changelog
+header
-  border: 1px solid #aaa
+  .locales, .mark
-  margin: 0 0.5em
+    margin-bottom: -2em
-  padding: 1em
+    margin-top: 2em
-  overflow-x: auto
+    margin-right: 2em
-  height: 20em
+
+  .mark
+    margin-left: 3em
+    float: left
+
+.footer
+  line-height: 2.2
+
+  .mark
+    float: left
+
+.locales
+  float: right
 
 .locales li
+  float: right
+  font-size: 0.7em
   display: inline
   list-style-type: none
-  padding-right: 20px
   white-space: nowrap
 
 pre, code
+  background-color: $color-light-sand
   font-family: $source-code-font-family
+code
+  white-space: nowrap

source/assets/stylesheets/layout.sass

@@ -0,0 +1,43 @@
+$break-small: em(480px)
+$break-medium: em(800px)
+$break-large: em(1024px)
+
+article
+  margin: 0 auto
+  width: 65em
+
+.main
+  background-color: $color-white
+  margin-bottom: 2em
+
+  div
+    padding-left: 20%
+    padding-right: 20%
+    padding-bottom: 3em
+
+    aside
+      background-color: lighten(desaturate($color-bark, 5%), 10%)
+      margin-bottom: -3em
+      margin-left: -35%
+      margin-right: -35%
+      margin-top: 3em
+      padding: 2em 20%
+      text-align: center
+
+    aside &
+      background-position: top
+
+article p
+  font-size: 1.3em
+
+article code
+  border-radius: 0.315em
+  border: 1px solid #ccc
+  padding: 0 0.3em 0.040em
+  font-size: 0.9em
+
+article ul
+  font-size: 1.1em
+  line-height: 1.5
+  list-style-type: square
+  padding-left: 1em

source/assets/stylesheets/legacy.css.sass

@@ -0,0 +1,127 @@
+$base-font-family: "Carrois Gothic", "Helvetica Neue", Helvetica, Arial, sans-serif
+$source-code-font-family: "Source Code Pro", monospace
+
+html
+  font: 14px/1.4 $base-font-family
+  color: #333
+
+a
+  color: #E10FCE
+  font-weight: bold
+  text-decoration: none
+
+a:hover
+  text-decoration: underline
+
+h1
+  color: #C647BF
+  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
+  margin-bottom: 2em
+
+h1, h2
+  text-align: center
+
+h3
+  font-size: 1.3em
+  font-family: $source-code-font-family
+  margin-bottom: 0
+  position: relative
+  padding-left: .1em
+
+h3:hover .anchor, h3:focus .anchor
+  display: block
+
+.anchor
+  display: none
+  font-style: normal
+  font-weight: normal
+  position: absolute
+  right: 100%
+  top: 0
+
+.anchor::before
+  content: '¶'
+
+.anchor:hover
+  text-decoration: none
+
+h3 ~ p
+  margin-top: 0
+
+article
+  margin: 0 auto
+  width: 640px
+
+article p
+  font-size: 1.3em
+
+article code
+  border-radius: 0.315em
+  border: 1px solid #ccc
+  padding: 0 0.3em 0.040em
+  font-size: 0.9em
+
+article img
+  margin: 0 auto
+  max-width: 100%
+  text-align: center
+  display: block
+  box-shadow: rgba(0, 0, 0, 0.37) 0px 0px 6px
+  border-radius: 7px
+  padding: 0.4em 0.9em
+
+article > ul
+  font-size: 1.2em
+  padding-left: 0
+
+article > ul ul
+  padding-left: 1em
+
+article ul
+  line-height: 1.5
+  list-style-position: inside
+  list-style-type: square
+
+footer
+  font-size: .7em
+  border-top: 1px solid #e9e6e1
+  margin-top: 1em
+  margin-bottom: 2em
+  padding-top: 1em
+
+.license
+  float: left
+
+.about
+  float: right
+
+.about, .license
+  margin-top: 0
+
+.changelog
+  border: 1px solid #aaa
+  margin: 0 0.5em
+  padding: 1em
+  overflow-x: auto
+  height: 20em
+
+.locales li
+  display: inline
+  list-style-type: none
+  padding-right: 20px
+  white-space: nowrap
+
+pre, code
+  font-family: $source-code-font-family
+
+.newer, .last-version-notice
+  text-align: center
+  margin: 1em

source/assets/stylesheets/sections.sass

@@ -0,0 +1,180 @@
+div.header
+  padding-top: 5em
+  padding-bottom: 0.1em
+  background-color: $color-ocre
+  background-image: image-url("bg-hero@2x.png")
+  background-size: 100%
+
+  h1
+    color: $color-sand
+
+  h2
+    font-weight: normal
+
+  a
+    color: $color-black
+
+  .title
+    width: 80%
+    margin: 0 auto
+    margin-bottom: -2em
+
+  .changelog
+    background-color: $color-white
+    box-shadow: 0px 4px 12px 0px hsla(0, 0%, 0%, 0.2)
+    font-size: 0.8em
+    height: 20em
+    margin-bottom: -14em
+    margin-left: 0.5em
+    margin-right: 0.5em
+    margin-top: 1em
+    overflow-x: auto
+    padding: 1em
+
+div.answers
+  margin-top: 12em
+  padding-left: 25%
+  padding-right: 25%
+  background-color: $color-white
+
+  h3
+    font-size: 1.7em
+    color: $color-ocre
+
+  a
+    color: $color-gold
+
+  p
+    font-size: 1em
+
+.good-practices
+  background-color: $color-gold
+  background-image: image-url("bg-img1@2x.png")
+  background-position: bottom left
+  background-repeat: no-repeat
+  background-size: 100%
+  padding-top: 2em
+
+  a.anchor
+    color: $color-black
+
+  h3
+    font-size: 1.6em
+    font-weight: bold
+    width: 50%
+
+  h4
+    padding-left: 15em
+
+  ul
+    font-size: 1em
+    padding-left: 16em
+
+  p
+    a
+      color: $color-white
+      text-decoration: underline
+
+div.bad-practices
+  color: $color-white
+  background-color: $color-bark
+  background-image: image-url("bg-img2@2x.png")
+  background-position: bottom left
+  background-repeat: no-repeat
+  background-size: 100%
+  padding-top: 3em
+
+  code
+    color: $color-black
+    background-color: desaturate(lighten($color-bark, 50%), 10%)
+    border: none
+
+  p, aside
+    a
+      color: $color-gold
+      text-decoration: underline
+
+  aside
+    a
+      text-decoration: none
+
+  h3
+    font-size: 1.7em
+    color: $color-gold
+    float: left
+    width: 35%
+
+  h4, p
+    padding-left: 12em
+  p
+    clear: left
+    font-size: 1em
+
+div.effort
+  padding-top: 2em
+  padding-left: 25%
+  padding-right: 25%
+  background-color: $color-white
+
+  h3
+    font-size: 1.6em
+    font-weight: bold
+    color: $color-ocre
+
+div.frequently-asked-questions
+  padding-top: 2em
+  padding-left: 25%
+  padding-right: 25%
+  background-color: $color-white
+
+  h2
+    color: $color-ocre
+
+  h3
+    color: $color-ocre
+    margin-bottom: 1.5em
+    font-size: 1.7em
+
+  h4
+    cursor: pointer
+    border-bottom: 1px solid transparentize($color-bark, 0.8)
+    padding: 0 1.1em 1.3em 0
+
+    &:after
+      content: "⌄"
+      text-align: right
+      float: right
+      font-size: 2.8em
+      line-height: 0.4
+      margin-right: -0.3em
+
+
+    &.is-visible:after
+      content: "-"
+
+  h4 ~ p
+    display: none
+    font-size: 0.9em
+
+  h4 ~ p.is-visible
+    display: inherit
+
+.footer
+  font-size: .6em
+  font-weight: normal
+  border-top: 1px solid #e9e6e1
+  padding-top: 1em
+  padding-left: 2em
+  padding-right: 2em
+
+  background-color: $color-ocre
+  color: $color-sand
+
+  a
+    color: $color-white
+    text-decoration: underline
+
+  &:after
+    content: ""
+    display: table
+    clear: both

source/assets/stylesheets/table-of-contents.sass

@@ -0,0 +1,29 @@
+.toc
+  position: fixed
+  z-index: 9999
+  top: 10%
+  left: 0
+
+  ul
+    list-style-position: inside
+    list-style-type: decimal-leading-zero
+    padding: 0 0 0 1em
+    li
+      padding-left: 1em
+      line-height: 2
+      a
+        padding: 0 1em
+        line-height: 2
+        display: none
+
+        span
+          display: none
+
+    li:hover
+      color: $color-sand
+      background: $color-black
+    li:hover a
+      color: $color-sand
+      font-weight: bold
+      background-color: $color-black
+      display: inline-block

source/cs/0.3.0/index.html.haml

@@ -16,9 +16,8 @@ version: 0.3.0
   Changelog je soubor, který obsahuje organizovaný, chronologicky seřazený
   seznam podstatných změn pro každou verzi daného projektu.
 
-%pre.changelog= File.read("CHANGELOG.md")
+  <pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
 
-:markdown
   ### Co je smyslem changelogu?
   Usnadnit uživatelům a přispěvatelům přesné zobrazení podstatných změn, které
   byly provedeny mezi jednotlivými vydáními (verzemi) daného projektu.

source/de/0.3.0/index.html.haml

@@ -17,9 +17,8 @@ version: 0.3.0
   Liste aller erheblichen Änderungen enthält, die zwischen Veröffentlichungen (oder Versionen)
   des Projekts umgesetzt wurden.
 
-%pre.changelog= File.read("CHANGELOG.md")
+  <pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
 
-:markdown
   ### Was ist der Zweck eines Changelogs?
   Es Benutzern und Entwicklern einfacher zu machen, gerade die beachtenswerten Änderungen, welche
   zwischen Veröffentlichungen (oder Versionen) des Projekts gemacht wurden, zu sehen.

source/en/0.3.0/index.html.haml

@@ -16,9 +16,8 @@ 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("CHANGELOG.md")
+  <pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
 
-: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.

source/en/1.0.0/index.html.haml

@@ -0,0 +1,311 @@
+---
+description: Keep a Changelog
+title: Keep a Changelog
+language: en
+version: 1.0.0
+---
+
+- changelog = "https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md"
+- gemnasium = "https://gemnasium.com/"
+- gh = "https://github.com/olivierlacan/keep-a-changelog"
+- issues = "https://github.com/olivierlacan/keep-a-changelog/issues"
+- semver = "http://semver.org/"
+- shields = "http://shields.io/"
+- thechangelog = "http://5by5.tv/changelog/127"
+- vandamme = "https://github.com/tech-angels/vandamme/"
+- iso = "http://www.iso.org/iso/home/standards/iso8601.htm"
+- ghr = "https://help.github.com/articles/creating-releases/"
+
+.header
+  .title
+    %h1 Keep a Changelog
+    %h2 Don’t let your friends dump git logs into changelogs.
+
+  = link_to changelog do
+    Version
+    %strong= current_page.metadata[:page][:version]
+
+  %pre.changelog= File.read("CHANGELOG.md")
+
+.answers
+  %h3#what
+    %a.anchor{ href: "#what", aria_hidden: "true" }
+    What is a changelog?
+
+  %p
+    A changelog is a file which contains a curated, chronologically
+    ordered list of notable changes for each version of a project.
+
+  %h3#why
+    %a.anchor{ href: "#why", aria_hidden: "true" }
+    Why keep a changelog?
+
+  %p
+    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.
+
+  %h3#who
+    %a.anchor{ href: "#who", aria_hidden: "true" }
+    Who needs a changelog?
+
+  %p
+    People do. Whether consumers or developers, the end users of
+    software are human beings who care about what's in the sofware. When
+    the software changes, people want to know why and how.
+
+.good-practices
+  %h3#how
+    %a.anchor{ href: "#how", aria_hidden: "true" }
+    How do I make a good changelog?
+
+  %h4#principles
+    %a.anchor{ href: "#principles", aria_hidden: "true" }
+    Guiding Principles
+
+  %ul
+    %li
+      Changelogs are <em>for humans</em>, not machines.
+    %li
+      There should be an entry for every single version.
+    %li
+      The same types of changes should be grouped.
+    %li
+      Versions and sections should be linkable.
+    %li
+      The latest version comes first.
+    %li
+      The release date of each versions is displayed.
+    %li
+      Mention whether you follow #{link_to "Semantic Versioning", semver}.
+
+  %a.anchor{ href: "#types", aria_hidden: "true" }
+  %h4#types Types of changes
+
+  %ul
+    %li
+      %code Added
+      for new features.
+    %li
+      %code Changed
+      for changes in existing functionality.
+    %li
+      %code Deprecated
+      for soon-to-be removed features.
+    %li
+      %code Removed
+      for now removed features.
+    %li
+      %code Fixed
+      for any bug fixes.
+    %li
+      %code Security
+      in case of vulnerabilities.
+
+.effort
+
+  %h3#effort
+    %a.anchor{ href: "#effort", aria_hidden: "true" }
+    How can I reduce the effort required to maintain a changelog?
+
+  %p
+    Keep an <code>Unreleased</code> section at the top to track upcoming
+    changes.
+
+  %p This serves two purposes:
+
+  %ul
+    %li
+      People can see what changes they might expect in upcoming releases
+    %li
+      At release time, you can move the <code>Unreleased</code> section
+      changes into a new release version section.
+
+.bad-practices
+  %h3#bad-practices
+    %a.anchor{ href: "#bad-practices", aria_hidden: "true" }
+    Can changelogs be bad?
+
+  %p Yes. Here are a few ways they can be less than useful.
+
+  %h4#log-diffs
+    %a.anchor{ href: "#log-diffs", aria_hidden: "true" }
+    Commit log diffs
+
+  %p
+    Using commit log diffs as changelogs is a bad idea: they're full of
+    noise. Things like merge commits, commits with obscure titles,
+    documentation changes, etc.
+
+  %p
+    The purpose of a commit is to document a step in the evolution of
+    the source code. Some projects clean up commits, some don't.
+
+  %p
+    The purpose of a changelog entry is to document the noteworthy
+    difference, often across multiple commits, to communicate them
+    clearly to end users.
+
+  %h4#ignoring-deprecations
+    %a.anchor{ href: "#ignoring-deprecations", aria_hidden: "true" }
+    Ignoring Deprecations
+
+  %p
+    When people upgrade from one version to another, it should be
+    painfully clear when something will break. It should be possible to
+    upgrade to a version that lists deprecations, remove what's
+    deprecated, then upgrade to the version where the deprecations
+    become removals.
+
+  %p
+    If you do nothing else, list deprecations, removals, and any
+    breaking changes in your changelog.
+
+
+  %h4#confusing-dates
+    %a.anchor{ href: "#confusing-dates", aria_hidden: "true" }
+    Confusing Dates
+
+  %p
+    In the U.S., people put the month first (<code>06-02-2012</code> for
+    June 2nd, 2012), while many people in the rest of the world write a
+    robotic-looking <code>2 June 2012</code>, yet pronounce it
+    differently. <code>2012-06-02</code> works logically from largest to
+    smallest, doesn't overlap in ambiguous ways with other date formats,
+    and is an #{link_to "ISO standard", iso}. Thus, it is the
+    recommended date format for changelogs.
+
+  %aside
+    There’s more. Help me collect these antipatterns by
+    = link_to "opening an issue", "#issues"
+    or a pull request.
+
+.frequently-asked-questions
+  %h3#frequently-asked-questions
+    %a.anchor{ href: "#frequently-asked-questions", aria_hidden: "true" }
+    Frequently Asked Questions
+
+  %h4#standard
+    %a.anchor{ href: "#standard", aria_hidden: "true" }
+    Is there a standard changelog format?
+
+  %p
+    Not really. There's the GNU changelog style guide, or the two-
+    paragraph-long GNU NEWS file "guideline". Both are inadequate or
+    insufficient.
+
+  %p
+    This project aims to be
+    = link_to "a better changelog convention.", changelog
+    It comes from observing good practices in the open source
+    community and gathering them.
+
+  %p
+    Healthy criticism, discussion and suggestions for improvements
+    = link_to "are welcome.", issues
+
+
+  %h4#filename
+    %a.anchor{ href: "#filename", aria_hidden: "true" }
+    What should the changelog file be named?
+
+  %p
+    Call it <code>CHANGELOG.md</code>. Some projects use
+    <code>HISTORY</code>, <code>NEWS</code> or <code>RELEASES</code>.
+
+  %p
+    While it's easy to think that the name of your changelog file
+    doesn't matter that much, why make it harder for your end users to
+    consistently find notable changes?
+
+  %h4#github-releases
+    %a.anchor{ href: "#github-releases", aria_hidden: "true" }
+    What about GitHub Releases?
+
+  %p
+    It's a great initiative. #{link_to "Releases", ghr} can be used to
+    turn simple git tags (for example a tag named <code>v1.0.0</code>)
+    into rich release notes by manually adding release notes or it can
+    pull annotated git tag messages and turn them into notes.
+
+  %p
+    GitHub Releases create a non-portable changelog that can only be
+    displayed to users within the context of GitHub. It's possible to
+    make them look very much like the Keep a Changelog format, but it
+    tends to be a bit more involved.
+
+  %p
+    The current version of GitHub releases is also arguably not very
+    discoverable by end-users, unlike the typical uppercase files
+    (<code>README</code>, <code>CONTRIBUTING</code>, etc.). Another
+    minor issue is that the interface doesn't currently offer links to
+    commit logs between each release.
+
+  %h4#automatic
+    %a.anchor{ href: "#automatic", aria_hidden: "true" }
+    Can changelogs be automatically parsed?
+
+  %p
+    It’s difficult, because people follow wildly different formats and
+    file names.
+
+  %p
+    #{link_to "Vandamme", vandamme} is a Ruby gem created by the
+    #{link_to "Gemnasium", gemnasium} team and which parses many (but
+    not all) open source project changelogs.
+
+
+  %h4#yanked
+    %a.anchor{ href: "#yanked", aria_hidden: "true" }
+    What about yanked releases?
+
+  %p
+    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:
+
+  %p <code>## 0.0.5 - 2014-12-13 [YANKED]</code>
+
+  %p
+    The <code>[YANKED]</code> 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.
+
+
+  %h4#rewrite
+    %a.anchor{ href: "#rewrite", aria_hidden: "true" }
+    Should you ever rewrite a changelog?
+
+  %p
+    Sure. There are always good reasons to improve a changelog. I
+    regularly open pull requests to add missing releases to open source
+    projects with unmaintained changelogs.
+
+  %p
+    It's also possible you may discover that you forgot to address a
+    breaking change in the notes for a version. It's obviously important
+    for you to update your changelog in this case.
+
+
+  %h4#contribute
+    %a.anchor{ href: "#contribute", aria_hidden: "true" }
+    How can I contribute?
+
+  %p
+    This document is not the <strong>truth</strong>; it’s my carefully
+    considered opinion, along with information and examples I gathered.
+
+  %p
+    This is because I want our community to reach a consensus. I believe
+    the discussion is as important as the end result.
+
+  %p
+    So please <strong>#{link_to "pitch in", gh}</strong>.
+
+.press
+  %h3 Conversations
+  %p
+    I went on #{link_to "The Changelog podcast", thechangelog}
+    to talk about why maintainers and contributors should care about changelogs,
+    and also about the motivations behind this project.

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

@@ -16,9 +16,8 @@ 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("CHANGELOG.md")
+  <pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
 
-:markdown
   ### Cuál es el propósito del change log?
 
   Para que les sea más fácil a los usuarios y contribuyentes, ver exactamente los cambios notables que se han hecho entre cada versión (o versiones) del proyecto.

source/fr/0.3.0/index.html.haml

@@ -17,9 +17,8 @@ version: 0.3.0
   une liste triée chronologiquement des changements notables pour chaque
   version d’un projet
 
-%pre.changelog= File.read("CHANGELOG.md")
+  <pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
 
-:markdown
   ### Quel est l’intérêt d’un change log ?
   Il permet aux utilisateurs et aux contributeurs de voir plus simplement
   les changements notables qui ont été réalisés entre chaque publication

source/fr/1.0.0/index.html.haml

@@ -0,0 +1,317 @@
+---
+description: Tenez un Changelog
+title: Tenez un Changelog
+language: fr
+version: 1.0.0
+---
+
+- changelog = "https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md"
+- gemnasium = "https://gemnasium.com/"
+- gh = "https://github.com/olivierlacan/keep-a-changelog"
+- issues = "https://github.com/olivierlacan/keep-a-changelog/issues"
+- semver = "http://semver.org/"
+- shields = "http://shields.io/"
+- thechangelog = "http://5by5.tv/changelog/127"
+- vandamme = "https://github.com/tech-angels/vandamme/"
+- iso = "http://www.iso.org/iso/home/standards/iso8601.htm"
+- ghr = "https://help.github.com/articles/creating-releases/"
+
+.header
+  .title
+    %h1 Tenez un Changelog
+    %h2 Ne laissez pas vos amis utiliser les logs git comme changelogs
+
+  = link_to changelog do
+    Version
+    %strong= current_page.metadata[:page][:version]
+
+  %pre.changelog= File.read("CHANGELOG.md")
+
+.answers
+  %h3#what
+    %a.anchor{ href: "#what", aria_hidden: "true" }
+    Qu'est-ce qu'un changelog ?
+
+  %p
+    Un changelog (journal de modifications) est un fichier qui contient
+    une liste triée chronologiquement des changements notables pour
+    chaque version d’un projet
+
+  %h3#why
+    %a.anchor{ href: "#why", aria_hidden: "true" }
+    Pourquoi tenir un changelog ?
+
+  %p
+    Pour permettre aux utilisateurs et contributeurs de voir précisement
+    quel changements notables ont été faits entre chaque publication
+    (ou version) d'un projet.
+
+  %h3#who
+    %a.anchor{ href: "#who", aria_hidden: "true" }
+    Qui a besoin d'un changelog ?
+
+  %p
+    Tout le monde. Qu'ils soient consomateurs ou developeurs, les
+    utilisateurs de logiciels sont des êtres humains qui se soucient
+    de connaître le contenu des logiciels qu'ils utilisent. Quand un
+    logiciel change, ces même personnes veulent savoir comment et pourquoi.
+
+.good-practices
+  %h3#how
+    %a.anchor{ href: "#how", aria_hidden: "true" }
+    Comment créer un bon changelog ?
+
+  %h4#principles
+    %a.anchor{ href: "#principles", aria_hidden: "true" }
+    Principes Directeurs
+
+  %ul
+    %li
+      Les changelogs sont <em>pour les êtres humains</em>, pas les machines.
+    %li
+      Il doit il y avoir une section pour chaque version.
+    %li
+      Les changements similaires doivent être groupés.
+    %li
+      Les versions et sections doivent être liables.
+    %li
+      La version la plus récente se situe en haut du fichier.
+    %li
+      La date de publication de chaque version est indiquée.
+    %li
+      Indiquer si le projet respecte le #{link_to "Versionnage Sémantique", semver}.
+
+  %a.anchor{ href: "#types", aria_hidden: "true" }
+  %h4#types Types de changements
+
+  %ul
+    %li
+      %code Added
+      pour les nouvelles fonctionnalités.
+    %li
+      %code Changed
+      pour les changements aux fonctionnalités préexistantes.
+    %li
+      %code Deprecated
+      pour les fonctionnalités qui seront bientôt supprimées.
+    %li
+      %code Removed
+      pour les fonctionnalités désormais supprimées.
+    %li
+      %code Fixed
+      pour les corrections de bugs.
+    %li
+      %code Security
+      en cas de vulnerabilités.
+
+.effort
+
+  %h3#effort
+    %a.anchor{ href: "#effort", aria_hidden: "true" }
+    Comment puis-je minimiser le travail nécessaire pour maintenir un changelog ?
+
+  %p
+    Gardez une section <code>Unreleased</code> en haut du fichier afin de lister
+    tous les changements qui n'ont pas encore été publiés.
+
+  %p Cela rempli deux objectifs:
+
+  %ul
+    %li
+      Les gens peuvent voir les changements auxquels ils peuvent s’attendrent
+      dans les prochaines publications.
+    %li
+      Au moment de la publication, vous pouvez déplacer les changements listés
+      dans la section <code>Unreleased</code> dans la section d'une nouvelle
+      version.
+
+.bad-practices
+  %h3#bad-practices
+    %a.anchor{ href: "#bad-practices", aria_hidden: "true" }
+    Est-ce que les changelogs peuvent être mauvais ?
+
+  %p Oui. Voici quelques exemples de changelogs plutôt inutiles.
+
+  %h4#log-diffs
+    %a.anchor{ href: "#log-diffs", aria_hidden: "true" }
+    Diffs de journaux git
+
+  %p
+    Utiliser des diffs de journaux git en tant que changelogs est une mauvaise
+    idée: ils sont remplis de bruit. Les journaux git sont remplis de choses
+    comme des commits de merge, des commits avec des titres obscures, des
+    changements concernant la documentation, etc.
+
+  %p
+    Le but d'un commit est de documenter une étape dans l'évolution du code
+    source. Certains projets nettoient leurs commits, d'autres non.
+
+  %p
+    Le but d'une section de changelog est de documenter la difference notable
+    entre deux versions, souvent à travers de multiples commits, afin de la
+    communiquer clairement aux utilisateurs.
+
+  %h4#ignoring-deprecations
+    %a.anchor{ href: "#ignoring-deprecations", aria_hidden: "true" }
+    Ignorer les dépréciations
+
+  %p
+    Lorsque l'on passe d'une version d'un logiciel à une autre, il devrait être
+    très clair si quelque chose peut ne pas fonctionner. Il devrait être
+    possible de mettre à jour vers un version qui offre une liste des
+    fonctionnalités dépréciées, de retirer ce qui est déprécié, puis de mettre
+    à jour vers la version où les dépréciations deviennent des suppressions de
+    fonctionnalités.
+
+  %p
+    Si vous ne faites rien d'autre, listez les dépréciations, les supressions de
+    fonctionnalités, et tous les changements non rétrocompatibles dans votre
+    changelog.
+
+
+  %h4#confusing-dates
+    %a.anchor{ href: "#confusing-dates", aria_hidden: "true" }
+    Dates confuses
+
+  %p
+    Aux États-Unis, les gens mettent le mois en premier (<code>06-02-2012</code>
+    pour le 2 Juin 2012), tandis que beaucoup de gens dans le reste du monde
+    l’écrivent de la façon robotique suivante "2 Juin 2012", alors qu’ils le
+    prononcent différement. <code>2012-06-02</code> fonctionne logiquement, du plus grand
+    au plus petit, ne laisse pas place à la confusion avec un autre format et
+    est un #{link_to "standard ISO", iso}. C'est pour cela que ce format de date
+    est recommandé pour les change logs.
+
+  %aside
+    Il y en a d’autres. Aidez-moi à collecter ces anti-patrons en
+    #{link_to "ouvrant une issue", "#issues"} ou une pull request.
+
+.frequently-asked-questions
+  %h3#frequently-asked-questions
+    %a.anchor{ href: "#frequently-asked-questions", aria_hidden: "true" }
+    Questions fréquemment posées
+
+  %h4#standard
+    %a.anchor{ href: "#standard", aria_hidden: "true" }
+    Y a-t-il un format de changelog standard ?
+
+  %p
+    Pas vraiment. Il y a le guide de style GNU pour les changelogs, ou les
+    instructions GNU de deux paragraphes pour les fichiers NEWS. Ces deux
+    resources sont inappropriées et insuffisantes.
+
+  %p
+    Ce projet vise à devenir
+    = link_to "une meilleure convention pour les changelogs.", changelog
+    Il a pour origine l'observation et le rassemblement des bonne pratiques dans
+    la communauté open source.
+
+  %p
+    Les critiques constructives, discussions et suggestions pour améliorer ce
+    projet #{link_to "sont les bienvenues.", issues}.
+
+
+  %h4#filename
+    %a.anchor{ href: "#filename", aria_hidden: "true" }
+    Comment doit-être nommé le fichier de change log ?
+
+  %p
+    Nommez le <code>CHANGELOG.md</code>. Certains projects utilisent
+    <code>HISTORY</code>, <code>NEWS</code> ou <code>RELEASES</code>.
+
+  %p
+    Même s'il est facile d'imaginer que le nom d'un fichier de changelog n'a
+    pas grant interêt, pourquoi rendre la tâche difficile que nécessaire pour
+    les utilisateurs qui cherchent à trouver les changements notables de votre
+    projet ?
+
+  %h4#github-releases
+    %a.anchor{ href: "#github-releases", aria_hidden: "true" }
+    Quid de GitHub Releases ?
+
+  %p
+    C'est une excellente initiative. #{link_to "Releases", ghr} peut être
+    utilisé pour transformer de simples tags git (par exemple un tag nommé
+    <code>v1.0.0</code>) en notes de publication riches soit en ajoutant
+    manuellement des notes soit en utilisant les messages de tags gits annotés
+    et en les transformant en notes.
+
+  %p
+    GitHub Releases crée un changelog non-portable qui n'est visible par les
+    utilisateurs qu'à l'interieur du context de GitHub. Il est possible de
+    suivre le même format que Keep a Changelog, mais c'est plus difficile.
+
+  %p
+    La version actuelle de GitHub Releases est également difficile à découvrir
+    pour les utilisateurs, contrairement aux fichiers en majuscules typiques
+    (<code>README</code>, <code>CONTRIBUTING</code>, etc.). Un autre soucis
+    mineur est que l'interface ne permet pas actuellement d'offrir des liens
+    vers les journaux git entre chaque publication.
+
+  %h4#automatic
+    %a.anchor{ href: "#automatic", aria_hidden: "true" }
+    Les change logs peuvent-ils être parsés automatiquement ?
+
+  %p
+    C'est difficile, parce que les gens suivent des formats et utilisent des noms
+    de fichiers très différents.
+
+  %p
+    #{link_to "Vandamme", vandamme} est une Ruby gem créée par l'équipe
+    #{link_to "Gemnasium", gemnasium} qui parse les change logs de
+    beaucoup (mais pas tous) de projets open source.
+
+
+  %h4#yanked
+    %a.anchor{ href: "#yanked", aria_hidden: "true" }
+    Qu'en est-il des publications "yanked" (retirées) ?
+
+  %p
+    Les publications yanked sont des version qui ont dû être retirées du fait d'un
+    sérieux bug ou d'un problème de sécurité. Souvent ces version n'apparaissent
+    même pas dans les changelogs. Elles devraient. Voilà comment les afficher:
+
+  %p <code>## 0.0.5 - 2014-12-13 [YANKED]</code>
+
+  %p
+    Le tag <code>[YANKED]</code> n'est pas mis en avant pour rien. Il est
+    important qu'il soit remarqué. Il est également plus facile à digérer pour
+    un programme puisqu'il est entouré par des crochets.
+
+
+  %h4#rewrite
+    %a.anchor{ href: "#rewrite", aria_hidden: "true" }
+    Devriez-vous réécrire un changelog ?
+
+  %p
+    Bien sûr. Il y a toujours de bonnes raisons d'améliorer un changelog.
+    J'ouvre souvent des pull requests pour ajouter des publications manquantes sur
+    des projets open source avec des changelogs non-maintenus.
+
+  %p
+    Il est aussi possible que vous découvriez que vous aviez oublié de mentionner
+    un changement majeur dans les notes de version. Il est évidemment important
+    que vous mettiez votre changelog à jour dans ce cas.
+
+
+  %h4#contribute
+    %a.anchor{ href: "#contribute", aria_hidden: "true" }
+    Comment puis-je contribuer ?
+
+  %p
+    Ce document n'est pas la **vérité**; c'est mon opinion soigneusement
+    réfléchie, accompagnée d'informations et d'exemples que j'ai rassemblés.
+
+  %p
+    C'est parce que je veux que notre communauté atteigne un consensus. Je crois
+    que la discussion est aussi importante que le résultat final.
+
+  %p
+    Donc s'il vous plaît, <strong>#{link_to "participez", gh}</strong>.
+
+.press
+  %h3 Conversations
+  %p
+    J'ai participé au podcast #{link_to "The Changelog", thechangelog}
+    pour expliquer pourquoi les mainteneurs et contributeurs doivent se
+    soucier des changelogs et également des motivations derrière ce projet.

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

@@ -13,9 +13,8 @@ language: it-IT
   Un change log è un file che contiene una lista curata e ordinata cronologicamente
   delle modifiche degne di nota per ogni versione di un progetto.
 
-%pre.changelog= File.read("CHANGELOG.md")
+  <pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
 
-:markdown
   ### A cosa serve un change log?
   Per rendere facile agli utilizzatori e contribuenti vedere con precisione quali modifiche
   importanti sono state fatte tra ogni release (o versione) del progetto.

source/layouts/layout.html.haml

@@ -1,3 +1,10 @@
+// Variables
+- latest_version = current_page.metadata[:page][:version] == $last_version
+- language_code = current_page.metadata[:page][:language]
+- versions = Dir.entries("source/#{language_code}") - %w[. ..]
+- current_version = current_page.metadata[:page][:version]
+- newer_version_available = File.exists?("source/#{language_code}/#{$last_version}")
+
 !!! 5
 %html
   %head{ lang: current_page.data.language }
@@ -20,31 +27,68 @@
     %link{ rel: 'canonical', href: path_to_url(current_page.url) }
 
     %title= current_page.data.title
-    = stylesheet_link_tag '//fonts.googleapis.com/css?family=Carrois+Gothic|Source+Code+Pro:400,700'
-    = stylesheet_link_tag 'application'
 
-    :javascript
+    %link{ rel: "stylesheet", href: "https://fonts.googleapis.com/css?family=Muli:400,700" }
-      try{Typekit.load();}catch(e){}
+    = stylesheet_link_tag '//fonts.googleapis.com/css?family=Source+Code+Pro:400,700'
+    - if latest_version
+      = stylesheet_link_tag 'application'
+    - else
+      = stylesheet_link_tag 'legacy'
+    = javascript_include_tag 'all'
 
   %body
     %article
       %header{ role: "banner" }
+        - if latest_version
+          = image_tag "keep-a-changelog-mark.svg", width: 100, class: "mark"
         %nav.locales{ role: "navigation" }
-          %ul
+          %select
             - $languages.each do |language|
-              %li= link_to "#{language.last} [#{language.first}]", "/#{language.first}/",
+              - version_exists = File.exists?("source/#{language.first}/#{$last_version}")
-              { rel: "alternate", lang: "#{language}", hreflang: "#{language}" }
+              - selected = language_code == language.first
+              - if version_exists
+                %option{ selected: selected, label: "#{$last_version} #{language.last[:name]}", value: language.first }
+              - else
+                - previous_version = File.exists?("source/#{language.first}/#{$previous_version}")
+                - if previous_version
+                  %option{ selected: selected, label: "#{$previous_version} #{language.last[:name]}", value: language.first }
 
-      .main{role: "main"}= yield
+      .main{ role: "main" }
+        - if !latest_version
+          - if versions.include?($last_version)
+            %p.newer
+              - if $languages[language_code][:new]
+                = "#{$languages[language_code][:new]}: "
+              - else
+                There is a newer version available:
+              = link_to "#{$languages[language_code][:name]} #{$last_version}", "/#{language_code}/#{$last_version}"
+          - else
+            - if $languages[language_code][:notice]
+              %p.last-version-notice= $languages[language_code][:notice]
+            - else
+              %p.last-version-notice
+                The latest version (#{$last_version}) is not yet available in
+                this language but
+                = link_to "you can read it in English", "/en/#{$last_version}"
+                for now and
+                = link_to "help translate ", "https://github.com/olivierlacan/keep-a-changelog/issues"
+                it.
+
+        = yield
+
+        %footer.footer.clearfix{ role: "banner" }
+          = image_tag "keep-a-changelog-mark.svg", width: 30, class: "mark"
 
-      %footer.clearfix{role: "banner"}
-        %p.license
-          This project is
-          #{link_to "MIT Licensed", "http://choosealicense.com/licenses/mit/"}.
           %p.about
-          #{link_to "Typed", "https://github.com/olivierlacan/keep-a-changelog/"}
+            This project is
-          with trepidation by
+            = link_to "MIT Licensed", "http://choosealicense.com/licenses/mit/"
-          #{link_to "Olivier Lacan", "http://olivierlacan.com/"}.
+            \ //
+            = link_to "Created & maintained", "https://github.com/olivierlacan/keep-a-changelog/"
+            by
+            = link_to "Olivier Lacan", "http://olivierlacan.com/"
+            \ //
+            Designed by
+            = link_to "Tyler Fortune", "http://tylerfortune.me/"
 
   - unless config.gauges_id.blank?
     :javascript

source/pl-PL/0.3.0/index.html.haml

@@ -0,0 +1,144 @@
+---
+description: Prowadź Changelog
+title: Prowadź Changelog
+language: pl-PL
+version: 0.3.0
+---
+
+:markdown
+  # Prowadź CHANGELOG
+
+  ## Nie pozwól, by twoi znajomi wklejali logi gita do CHANGELOGów™
+
+  Wersja **#{current_page.metadata[:page][:version]}**
+
+  ### Czym jest changelog?
+  Changelog, inaczej rejestr zmian lub historia zmian, to plik zawierający chronologicznie uporządkowaną listę istotnych zmian dla każdej wersji projektu.
+
+  <pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
+
+  ### Co jest celem prowadzenia changelogu?
+  Changelog pomaga użytkownikom zrozumieć, jakie znaczące zmiany zostały wprowadzone w każdej wersji projektu.
+
+  ### Dlaczego miałoby mi zależeć?
+  Ponieważ narzędzia informatyczne są dla ludzi. Jeśli ci nie zależy,
+  dlaczego przyczyniasz się do powstawania otwartego oprogramowania (open source)?
+
+  Rozmawiałem na podcaście ["The Changelog" z Adamem Stacoviakiem i Jerodem Santo][thechangelog]
+  (odpowiednia nazwa, prawda?) o tym, dlaczego osobom wspierającym otwarte programowanie powinno zależeć,
+  oraz o celach samego projektu. Jeśli masz chwilę (1:06), zapraszam do posłuchania - warto.
+
+  ### Co składa się na dobry changelog?
+  Cieszę się, że zapytałeś.
+
+  Dobry changelog trzyma się następujących zasad:
+
+  - Jest stworzony dla ludzi, nie maszyn, więc liczy się czytelność.
+  - Prostota dodawania linków do każdego rozdziału (dlatego używa się Markdown zamiast prostego tekstu).
+  - Jeden podrozdział dla każdej wersji.
+  - Wyszczególniaj wydania w odwrotnym porządku chronologicznym (najnowsza na górze).
+  - Wszystkie daty zapisuj w formacie `YYYY-MM-DD`. (Przykład: `2012-06-02` dla `2 czerwca 2012 r.`). To [rozsądny](http://xkcd.com/1179/), niezależny od języka międzynarodowy format.
+  - Zawsze określaj, czy projekt jest zgodny z [Semantycznym Wersjonowaniem][semver].
+  - Każda wersja powinna:
+    - Zawierać datę w wyżej wymienionym formacie.
+    - Grupować zmiany w celu opisu ich wpływu na projekt, w następujący sposób:
+      - `Added` dla nowych funkcji.
+      - `Changed` dla zmian w istniejącej funkcjonalności.
+      - `Deprecated` (przestarzałe) dla uprzednio stabilnych funkcji, które zostaną usunięte w przyszłych wydaniach projektu.
+      - `Removed` dla przestarzałych funkcji usuniętych w bieżącej wersji.
+      - `Fixed` dla poprawionych błędów (bugów).
+      - `Security` w celu poinformowania użytkowników o zalecanej aktualizacji naprawiającej luki bezpieczeństwa.
+
+  ### Jak mogę zminimalizować wysiłek wkładany w prowadzenie changelogu?
+  Zawsze umieszczaj rozdział `"Unreleased"` na szczycie dokumentu, w celu śledzenia wszelkich zmian.
+
+  Ta praktyka ma dwa cele:
+
+  - Użytkownicy widzą, jakich zmian mogą się spodziewać w nadchodzących wydaniach.
+  - W momencie aktualizacji, musisz jedynie zastąpić `"Unreleased"` wersją projektu oraz dodać nowy nagłówek `"Unreleased"` na samej górze.
+
+  ### Co sprawia, że jednorożce płaczą?
+  Dobrze... zabierzmy się za to.
+
+  - **Wrzucanie logów diff z zamieszczonymi zmianami.** Po prostu tego nie rób. Nikomu tym nie pomagasz.
+  - **Niewyszczególnianie przestarzałych funkcji.** Użytkownik powinien zostać wyraźnie poinformowany, że coś przestanie działać po aktualizacji.
+  - **Daty w formatach regionalnych.** W USA ludzie zapisują miesiąc na samym początku daty ("06-02-2012" dla 2 czerwca 2012 r.,
+    co nie ma *najmniejszego* sensu), podczas gdy gdzie indziej wiele osób pisze "2 czerwiec 2012", jednak wymawia to w inny sposób.
+    "2012-06-02" to logiczny format zapisywany od największej, do najmniejszej wartości oraz nie pokrywa się z innymi formatami w niejednoznaczny sposób.
+    Jest to jednocześnie [standard ISO](http://www.iso.org/iso/home/standards/iso8601.htm). To wszystko sprawia, że jest to rekomendowany format zapisywania daty w changelogach.
+
+  To jeszcze nie koniec. Pomóż mi zebrać wszystkie łzy jednorożców [zgłaszając problem][issues] lub wprowadzając zmianę poprzez pull request.
+
+  ### Czy istnieje standardowy format changelogu?
+  Niestety nie, ale spokojnie. Wiem, że spieszysz wkleić link do tego przewodnika stylu changelogu GNU, czy do dwóch paragrafów "wytycznych" GNU NEWS.
+  Przewodnik stylu GNU to dobry, ale niestety naiwny początek. Nie ma nic złego w byciu naiwnym, ale gdy ludzie potrzebują wytycznych, bycie naiwnym rzadko pomaga.
+  Szczególnie, gdy istnieje wiele sytuacji i szczególnych przypadków z którymi trzeba się zmierzyć.
+
+  Mam nadzieję, że ten projekt zostanie uznany [lepszym standardem pliku CHANGELOG][CHANGELOG].
+
+  Nie uważam, że status quo jest wystarczające i myślę, że jako społeczność, możemy stworzyć lepsze konwencje,
+  jeśli spróbujemy zastosować dobre praktyki stosowane w prawdziwych projektach informatycznych.
+  Proszę, zapoznaj się z projektem i pamiętaj, że [dyskusja i sugestie są zawsze mile widziane][issues]!
+
+  ### Jak powinien być nazwany plik changelog?
+  Jeśli nie potrafisz wywnioskować z powyższego przykładu, `CHANGELOG.md` to do tej pory najlepsza konwencja.
+
+  Niektóre projekty również stosują `HISTORY.txt`, `HISTORY.md`, `History.md`, `NEWS.txt`,
+  `NEWS.md`, `News.txt`, `RELEASES.txt`, `RELEASE.md`, `releases.md`, itd.
+
+  Straszny bałagan. Wszystkie te nazwy sprawiają, że jeszcze ciężej jest odnaleźć ten plik.
+
+  ### Dlaczego nie mielibyśmy po prostu stosować raportu `git log`?
+  Ponieważ logi typu diff są z natury zagmatwane. Nawet przy hipotetycznym projekcie stworzonym przez doskonałe istoty ludzkie, które nigdy nie popełniają literówek,
+  nigdy nie zapominają o zsynchronizowaniu nowo dodanych plików czy nigdy niczego nie pomijają podczas refaktoryzacji kodu, logi diff nie mogłyby zastąpić changelogu.
+  Celem `git commit` jest udokumentowanie jednego kroku w procesie, dzięki któremu kod ewoluuje z jednego stanu w kolejny. Celem changelogu jest udokumentowanie tych różnic pomiędzy stanami kodu, które są godne uwagi.
+
+  Różnica między changelogiem a logiem diff, tak samo jak różnica między dobrymi komentarzami a kodem, jest następująca: pierwsze opisuje *dlaczego*, drugie - *jak*.
+
+  ### Czy changelog może być generowany automatycznie?
+  To nie takie proste, ponieważ ludzie stosują bardzo różne formaty oraz nazwy plików.
+
+  [Vandamme][vandamme] to gem Ruby stworzony przez ekipę [Gemnasium][gemnasium], parsujący changelogi wielu (ale nie wszystkich) projektów open source.
+
+  ### Dlaczego czasem stosujesz pisownię "CHANGELOG", a czasem "changelog"?
+  "CHANGELOG" to nazwa samego pliku. Wygląda to dość głośno, ale taka jest historyczna konwencja przyjęta przez wiele projektów open source. Inne przykłady podobnych plików to [`README`][README], [`LICENSE`][LICENSE],
+  oraz [`CONTRIBUTING`][CONTRIBUTING].
+
+  Zapis wielkimi literami (dzięki któremu w starszych systemach operacyjnch pliki zostają umieszczone na szczycie listy) ma na celu zwrócenie na nie uwagi.
+  Jako że są to ważne informacje dotyczące projektu, mogą być one użyteczne dla każdego, kto zamierza korzystać lub wnieść weń wkład. Ida ta zbliżona jest do [odznaczeń przy projektach open source][shields].
+
+  Gdy stosuję pisownię "changelog", mówię o samej funkcji tego pliku: rejestrowaniu zmian.
+
+  ### A co z błędnymi wersjami (yanked)?
+  Są to wersje opublikowane błędnie, czyli takie, które musiały zostać wycofane ze względu na poważny błąd lub lukę bezpieczeństwa. Często takie wersje projektu nie pojawiają się nawet w changelogu, a powinny.
+  Oto jak taka wersja powinna wyglądać:
+
+  `## 0.0.5 - 2014-12-13 [YANKED]`
+
+  Tag `[YANKED]` jest celowo zapisany wielkimi literami. Ważne jest, by został on dostrzeżony. Dzięki temu, że jest ujęty w nawias, może być z łatwością generowany automatycznie.
+
+  ### Czy powinno się kiedykolwiek poprawiać changelog?
+  Oczywiście. Zawsze istnieją powody, by ulepszyć changelog. Często zdarza mi się edytować changelogi w projektach open source w których pominięto udokumentowanie istotnych zmian.
+
+  Może się również zdarzyć, że odkryjesz, iż podczas przygotowywania notatek dla wersji projektu, zapomniałeś udokumentować istotną zmianę, która ma wpływ na działanie aplikacji.
+  Ważne jest, by zaktualizować changelog szczególnie jeśli jest to zmiana, która w istotny sposób wpływa na kompatybilność aplikacji.
+
+  ### Jak mogę wnieść wkład w projekt?
+  Ten dokument to nie jedna i jedyna **prawda**; to moja starannie sformułowana opinia wraz z informacją i przykładami które zebrałem.
+  Pomimo tego, że prowadzę właściwy [CHANGELOG][] na [GitHubie][gh], celowo nie stworzyłem poprawnego *releasu* czy jasno sprecyzowanych wytycznych (tak jak np. na [SemVer.org][semver]).
+
+  Chcę, by nasza społeczność uzgodniła jak CHANGELOG ma wyglądać. Wierzę, że dyskusja jest niezbędna do osiągnięcia końcowego rezultatu.
+
+  Więc proszę, [**dołącz do projektu**][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/pt-BR/0.3.0/index.html.haml

@@ -12,130 +12,127 @@ version: 0.3.0
 
   Version **#{current_page.metadata[:page][:version]}**
 
-  ### O que é um change log?
+  ### O que é um *changelog*?
 
   Um *changelog* é um arquivo que contém uma lista selecionada, ordenada
   cronologicamente, de mudanças significativas para cada versão de um projeto
-  open source.
+  *open source*.
 
-%pre.changelog= File.read("CHANGELOG.md")
+  <pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
 
 :markdown
   ### Para que serve um *changelog*?
 
-  Para facilitar para os usuários e contribuidores verem precisamente quais
+  Para facilitar que usuários e contribuidores vejam precisamente quais
   mudanças significativas foram realizadas entre cada versão publicada.
 
   ### Por que eu deveria me importar?
 
   Porque softwares são feitos para pessoas. Se você não liga, por que está
-  contribuindo a projetos open source? Certamente deve haver um fundo de
+  contribuindo com projetos *open source*? Certamente deve haver um fundo de
   carinho em algum lugar desse seu amável cerebrinho.
 
   Eu [conversei com Adam Stacoviak e Jerod Santo no podcast do The
-  Changelog][thechangelog] (faz sentido, hein?) sobre o por quê mantenedores e
+  Changelog][thechangelog] (faz sentido, hein?) sobre por que mantenedores e
-  contribuidores open source devem se importar, e as motivações por trás deste
+  contribuidores *open source* devem se importar e as motivações por trás desse
-  projeto. Se você tem o tempo (1:06), é um bom programa.
+  projeto. Se você tem tempo (1:06), é um bom programa.
 
   ### O que faz um *changelog* ser bom?
 
   Que bom que perguntou.
 
-  Um bom change log não foge desses princípios:
+  Um bom *changelog* se atém a esses princípios:
 
   - É feito para seres humanos, não máquinas, então legibilidade é crucial.
-  - Ser fácil de referenciar (*linkar*) qualquer seção (por isso Markdown ao
+  - É fácil de referenciar (*linkar*) qualquer seção (por isso Markdown ao
     invés de puro texto).
-  - Uma sub-seção por versão.
+  - Uma subseção por versão.
   - Lista as versões publicadas em ordem cronológica decrescente (mais novo em
     cima).
-  - Escreva todas as datas no formato `AAAA-MM-DD`. (Exemplo: `2012-06-02` para
+  - Usa todas as datas no formato `AAAA-MM-DD`. (Exemplo: `2012-06-02` para
     `2 de Junho de 2012`.) É internacional, [sensato](http://xkcd.com/1179/), e
     independente de língua.
-  - Explicite se o projeto segue [Versionamento Semântico][semver].
+  - Menciona explicitamente se o projeto segue o [Versionamento Semântico][semver].
   - Cada versão deve:
     - Listar sua data de publicação no formato acima.
     - Agrupar mudanças descrevendo seus impactos no projeto, como segue:
-      - `Added` para novas funcionalidades.
+      - `Added`/`Adicionado` para novas funcionalidades.
-      - `Changed` para mudanças em funcionalidades existentes.
+      - `Changed`/`Modificado` para mudanças em funcionalidades existentes.
-      - `Deprecated` para funcionalidades uma vez estáveis removidas das
+      - `Deprecated`/`Obsoleto` para funcionalidades estáveis que foram removidas das
-        próximas publicações.
+        próximas versões.
-      - `Removed` para funcionalidades removidas desta versão.
+      - `Removed`/`Removido` para funcionalidades removidas desta versão.
-      - `Fixed` para qualquer correção de bug.
+      - `Fixed`/`Consertado` para qualquer correção de bug.
-      - `Security` para convidar usuários a atualizar em caso de
+      - `Security`/`Segurança` para incentivar usuários a atualizarem em caso de
         vulnerabilidades.
 
   ### Como eu posso minimizar o esforço exigido?
 
-  Mantenha sempre uma seção `Unreleased` no topo para manter o controle de
+  Mantenha sempre uma seção `"Unreleased"`\`"A publicar"` no topo para manter o controle de
   quaisquer mudanças.
 
   Isso serve a dois propósitos:
 
   - As pessoas podem ver quais mudanças elas podem esperar em publicações
     futuras.
-  - No momento da publicação, você tem que somente mudar `Unreleased` para o
+  - No momento da publicação, você apenas tem de mudar o `"Unreleased"`\`"A publicar"` para o
-    número de versão e adicionar um novo cabeçalho `Unreleased` no topo.
+    número de versão e adicionar um novo cabeçalho `"Unreleased"`\`"A publicar"` no topo.
 
   ### O que faz os unicórnios chorarem?
 
   Tudo bem... vamos lá.
 
-  - Despejar logs de commits. Simplesmente não faça isso, não está
+  - **Despejar logs de commits.** Simplesmente não faça isso, você não está
     ajudando ninguém.
-  - Não dar ênfase nas descontinuações. Quando as pessoas atualizam de uma
+  - **Não dar ênfase nas obsolências.** Quando as pessoas atualizam de uma versão
-    versão para outra, deve ser dolorosamente claro quando algo irá quebrar.
+    para outra, deve ser incrivelmente claro quando algo irá parar de funcionar.
-  - Datas em formatos específicos de uma região. Nos Estados Unidos, as pessoas
+  - **Datas em formatos específicos de uma região.** Nos Estados Unidos, as pessoas
     colocam o mês primeiro ("06-02-2012" para 2 de Junho de 2012, o que *não*
     faz sentido), enquanto muitos no resto do mundo escrevem em aspecto
     robótico "2 Junho 2012", e mesmo assim leem de forma diferente.
     "2012-06-02" funciona de maneira lógica do maior para o menor, não
-    sobrescreve de maneira ambígua outros formatos, e é um [padrão
+    se confunde de maneira ambígua com outros formatos, e é um [padrão
     ISO](http://www.iso.org/iso/home/standards/iso8601.htm).  Portanto, é o
     formato recomendado para *changelogs*.
 
-  Tem mais. Ajude me a coletar essas lágrimas de unicórnio [abrindo uma
+  Tem mais. Ajude-me a coletar essas lágrimas de unicórnio [abrindo uma
-  issue][issues] ou um pull request.
+  issue][issues] ou um *pull request*.
 
   ### Existe um padrão de formato de *changelog*?
 
-  Infelizmente, não. Calma. Eu sei que você está indo impetuosamente achar
+  Infelizmente, não. Calma. Eu sei que você está buscando furiosamente
-  aquele link do guia de estilo de *change log* GNU, ou o arquivo "guideline"
+  aquele link do guia GNU de estilo de *changelog*, ou o arquivo "guideline"
-  de dois paragráfos de GNU NEWS. O estilo GNU é um bom começo mas é ingênuo. 
+  de dois paragráfos do GNU NEWS. O estilo GNU é um bom começo mas, infelizmente, é ingênuo.
-  Não há nada de errado em ser ingênuo mas quando as pessoas precisam de 
+  Não há nada de errado em ser ingênuo mas, quando as pessoas precisam de orientação,
-  orientação isso raramente ajuda. Especialmente quando existem muitas 
+  raramente ajuda. Especialmente quando existem muitas situações excepcionais
-  situações excepcionais e casos extremos com os quais se deve lidar.
+  para lidar.
 
   Este projeto [contém o que eu espero se tornar um melhor padrão de arquivo
-  CHANGELOG][CHANGELOG]. Não acho que o status é bom o suficiente, e acho que
+  CHANGELOG][CHANGELOG] para todos os projetos *open source*. Eu não acredito que o status quo 
-  como uma comunidade nós podemos definir melhores padrões se tentarmos extrair
+  seja bom o suficiente, e acho que, como uma comunidade, nós podemos encontrar novas convenções
-  boas práticas de projetos de software reais. Então por favor dê um olhada e 
+  se tentarmos extrair boas práticas de projetos de software reais. Por favor, dê uma olhada e 
-  lembre que [discussões e sugestões para melhorias são bem-vindas][issues]!
+  lembre-se de que [discussões e sugestões de melhorias são bem-vindas][issues]!
 
   ### Qual deve ser o nome do arquivo *changelog*?
 
-  Bom, se você não notou no exemplo acima, `CHANGELOG.md` é a melhor padrão até
+  Bom, se você não notou no exemplo acima, `CHANGELOG.md` é a melhor convenção até agora.
-  agora.
 
   Alguns outros projetos também utilizam `HISTORY.txt`, `HISTORY.md`,
   `History.md`, `NEWS.txt`, `NEWS.md`, `News.txt`, `RELEASES.txt`,
   `RELEASE.md`, `releases.md`, etc.
 
-  É uma bagunça. Todos esses nome só dificultam que as pessoas o achem.
+  É uma bagunça. Todos esses nomes só dificultam encontrar o *changelog*.
 
-  ### Por quê as pessoas não podem simplesmente utilizar `git log`?
+  ### Por que as pessoas não podem simplesmente utilizar `git log`?
 
-  Porque os logs do Git são cheios de ruído — por natureza. Eles não poderiam
+  Porque os logs do Git são cheios de ruído — por natureza. Eles não serviriam como um 
-  escrever um change log adequado mesmo em um projeto hipotético desenvolvido
+  changelog adequado mesmo em um projeto hipotético executado por humanos perfeitos, que
-  por humanos perfeitos que nunca cometem erros de grafia, nunca esquecem de
+  nunca erram uma letra, nunca esquecem de *commitar* arquivos, nunca cometem deslizes
-  realizar commit de novos arquivos e nunca esquecem de nenhuma parte da
+  em uma refatoração. O propósito de um *commit* é documentar um passo atômico no 
-  refatoração. O propósito de um commit é documentar um passo atômico no
+  processo pelo qual o código evolui de um estado a outro. O propósito de um *changelog*
-  processo no qual o código evolui de um estado a outro. O propósito de um
+  é documentar as diferenças relevantes entre esses estados.
-  change log é documentar diferenças notáveis entre estes estados.
   
-  Assim como são as diferenças entre bons comentários e o próprio código, há
+  A mesma diferença que existe entre bons comentários e o código em si existe entre o 
-  a diferença entre o change log e o commit log: um descreve o porquê e o 
+  *changelog* e o *commit log*: um descreve o *porquê*, o outro descreve o *como*.
-  outro o como.
 
   ### Podem os *changelogs* ser automaticamente interpretados?
 
@@ -143,22 +140,22 @@ version: 0.3.0
   radicalmente diferentes.
 
   [Vandamme][vandamme] é uma gem criada pelo time [Gemnasium][gemnasium] que
-  interpreta muitos (mas não todos) change logs de projetos open source.
+  interpreta muitos (mas não todos) *changelogs* de projetos *open source*.
 
   ### Por que você alterna entre as grafias "CHANGELOG" e "changelog"?
 
   "CHANGELOG" é o nome do arquivo em si. É um pouco chamativo mas é uma
-  convenção histórica seguida por muitos projetos open source. Outros exemplos
+  convenção histórica seguida por muitos projetos *open source*. Outros exemplos
   similares de arquivo incluem [`README`][README], [`LICENSE`][LICENSE], e
   [`CONTRIBUTING`][CONTRIBUTING].
 
-  O nome em letras maiúsculas (o que, em sistemas operacionais antigos, fazia
+  O nome em letras maiúsculas (o que em sistemas operacionais antigos faziam
-  estes arquivos ficarem no topo da lista) é utilizado para chamar atenção para
+  estes arquivos ficarem no topo da lista) é utilizado para chamar atenção.
-  eles. Já que são importante metadados sobre o projeto, eles podem ser úteis
+  Por conterem importantes metadados do projeto, *changelogs* são úteis a
-  a qualquer um pretendendo usar ou contribuir com ele, assim como os [as
+  qualquer um que pretenda utilizar ou contribuir com o projeto, da maneira
-  badges de projeto open source][shields].
+  equivalente às [badges de projetos *open source*][shields].
 
-  Quando eu me refiro a "*change log*", eu estou falando sobre a função deste
+  Quando eu me refiro a "*changelog*", eu estou falando sobre a função desse
   arquivo: listar mudanças.
 
   ### E sobre as publicações removidas?
@@ -169,19 +166,19 @@ version: 0.3.0
 
   `## 0.0.5 - 2014-12-13 [YANKED]`
   
-  A tag `[YANKED]` é chamativa por uma razão. É importante que as pessoas a
+  A tag `[YANKED]`/`[REMOVIDA]` é chamativa por uma razão. É importante que
-  notem. E já que é cercada por colchetes é mais fácil detectá-la
+  as pessoas a notem. Além disso, já que é cercada por colchetes, é mais
-  programaticamente.
+  fácil detectá-la programaticamente.
 
-  ### Se você deveria reescrever um change log?
+  ### Devemos alterar o *changelog* em alguma circunstância?
  
-  Claro. Sempre existem boas razões para melhorar um change log. Eu abro os pull
+  Claro. Sempre existem bons motivos para melhorar um *changelog*. Eu regularmente
-  requests regularmente para adicionar releases que faltam a projetos open source
+  abro *pull requests* para adicionar versões faltantes em projetos *open source*
-  com change logs sem manutenção.
+  com *changelogs* abandonados.
 
-  É também possível que você descubra que esqueceu de registrar uma mudança
+  Também é possível que você perceba que se esqueceu de registrar mudanças
-  crucial nas anotações de uma versão. É obviamente importante que você atualize
+  importantes nas notas de uma versão. É obviamente importante que você atualize
-  seu change log neste caso.
+  seu *changelog* nesse caso.
 
   ### Como eu posso contribuir?
 
@@ -194,7 +191,7 @@ version: 0.3.0
   Fiz isso porque eu gostaria que nossa comunidade chegasse a um consenso. Eu
   acredito que a discussão é tão importante quanto o resultado final.
 
-  Então por favor [entre em campo][gh].
+  Então, por favor, [entre em campo][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

source/ru/0.3.0/index.html.haml

@@ -18,9 +18,8 @@ version: 0.3.0
   хронологическом порядке список значимых изменений для каждой версии проекта с
   открытым исходным кодом.
 
-%pre.changelog= File.read("CHANGELOG.md")
+  <pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
 
-:markdown
   ### Для чего нужен лог изменений?
 
   Чтобы пользователи и контрибьюторы могли с меньшими усилиями точно

source/sl/0.3.0/index.html.haml

@@ -16,9 +16,8 @@ version: 0.3.0
   Dnevnik sprememb je datoteka, ki vsebuje kuriran, kronološko urejen
   seznam opaznih sprememb za vsako verzijo projekta.
 
-%pre.changelog= File.read("CHANGELOG.md")
+  <pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
 
-:markdown
   ### Kaj je smisel dnevnika sprememb?
   Za poenostavitev, da uporabniki in prispevajoči sodelavci natančno vidijo, katere
   opazne spremembe so bile narejene med vsako izdajo (ali verzijo) projekta.

source/sv/0.3.0/index.html.haml

@@ -16,9 +16,8 @@ version: 0.3.0
   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")
+  <pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
 
-: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 gjorts mellan varje utgåva (eller version) av projektet.

source/tr-TR/0.3.0/index.html.haml

@@ -14,9 +14,8 @@ version: 0.3.0
   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("CHANGELOG.md")
+  <pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
 
-: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.

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

@@ -17,9 +17,8 @@ version: 0.3.0
   这个列表记录所有版本的重大变动。
 
 
-%pre.changelog= File.read("CHANGELOG.md")
+  <pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
 
-:markdown
   ### 为何要提供更新日志？
   为了让用户和开发人员更好知道每一个版本有哪些区别。
 

source/zh-TW/0.3.0/index.html.haml

@@ -17,9 +17,8 @@ version: 0.3.0
   這個列表記錄所有版本的重大變動。
 
 
-%pre.changelog= File.read("CHANGELOG.md")
+  <pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
 
-:markdown
   ### 為何要提供更新日誌？
   為了讓用戶和開發人員更好知道每一個版本有哪些區別。