Merge pull request #153 from olivierlacan/0-4-0

1.0.0

CHANGELOG.md

@@ -6,18 +6,41 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 ### Added
-- zh-CN and zh-TW translations from @tianshuo.
+- "Why keep a changelog?" section.
-- de translation from @mpbzh.
+- "Who needs a changelog?" section.
-- it-IT translation from @roalz.
+- "How do I make a changelog?" section.
-- sv translation from @magol.
+- "Frequently Asked Questions" section.
-- tr-TR translation from @karalamalar.
+- New "Guiding Principles" sub-section to "How do I make a changelog?".
-- fr translation from @zapashcanon.
+- 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 +50,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,7 +117,8 @@ 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.

Gemfile.lock

@@ -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)
@@ -146,4 +146,4 @@ DEPENDENCIES
   redcarpet
 
 BUNDLED WITH
-   1.12.0
+   1.13.6

config.rb

@@ -3,21 +3,84 @@
 # --------------------------------------
 
 # ----- 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.
+$last_version = (Dir.entries("source/en") - %w[. ..]).last
+
+# 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",
+    notice: ""
-  "es-ES" => "Español",
+  },
-  "fr"    => "Français",
+  "de"    => {
-  "it-IT" => "Italiano",
+    name: "Deutsch",
-  "pt-BR" => "Brazilian Portugese",
+    notice: "Die neuste version (#{$last_version}) ist noch nicht auf Deutsch
-  "ru"    => "Pyccкий",
+    verfügbar, aber du kannst sie dir <a href='/en/'>auf Englisch durchlesen</a>
-  "sl"    => "Slovenščina",
+    und <a href='#{issues_url}'>bei der Übersetzung mithelfen</a>."
-  "sv"    => "Svenska",
+  },
-  "tr-TR" => "Türkçe",
+  "en"    => {
-  "zh-CN" => "简体中文",
+    default: true,
-  "zh-TW" => " 繁體中文"
+    name: "English",
+    notice: ""
+  },
+  "es-ES" => {
+    name: "Español",
+    notice: "Aún no está disponible la última versión (#{$last_version}) en
+    español, pero 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>."
+  },
+  "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",
+    notice: ""
+  },
+  "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",
+    notice: ""
+  },
+  "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",
+    notice: ""
+  },
+  "zh-CN" => {
+    name: "简体中文",
+    notice: ""
+  },
+  "zh-TW" => {
+    name: "繁體中文",
+    notice: ""
+  }
 }
 
 activate :i18n,
@@ -31,8 +94,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 +114,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 +202,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,32 @@
-//= 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(header of faqHeaders){
+    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(paragraph of paragraphs) {
+      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,97 @@
-$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

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/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,316 @@
+---
+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's 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.
+    Although I provide an actual #{link_to "CHANGELOG", changelog} on
+    #{link_to "the GitHub repo", gh}, I have purposefully not created a
+    proper <em>release</em> or clear list of rules to follow (as
+    #{link_to "SemVer.org", semver} does, for instance).
+
+  %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}
+    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.

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/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

@@ -20,31 +20,55 @@
     %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'
+    = stylesheet_link_tag 'application'
+    = javascript_include_tag 'all'
 
   %body
     %article
       %header{ role: "banner" }
+        = 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}/",
+              - selected = current_page.metadata[:page][:language] == language.first
-              { rel: "alternate", lang: "#{language.first}", hreflang: "#{language.first}" }
+              %option{ selected: selected, label: language.last[:name], value: language.first }
 
-      .main{role: "main"}= yield
+      .main{ role: "main" }
+        - if current_page.metadata[:page][:version] != $last_version
+          - code = current_page.metadata[:page][:language]
+          - versions = Dir.entries("source/#{code}") - %w[. ..]
+          - if versions.include?($last_version)
+            = link_to "Version #{$last_version}", "#{code}/#{$last_version}"
+          - else
+            - if $languages[code][:notice]
+              %p.last-version-notice= $languages[code][:notice]
+            - else
+              %p
+                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

@@ -18,7 +18,7 @@ version: 0.3.0
   cronologicamente, de mudanças significativas para cada versão de um projeto
   *open source*.
 
-%pre.changelog= File.read("CHANGELOG.md")
+  <pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
 
 :markdown
   ### Para que serve um *changelog*?

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
   ### 為何要提供更新日誌？
   為了讓用戶和開發人員更好知道每一個版本有哪些區別。