Merge remote-tracking branch 'olivierlacan/master'

This commit is contained in:
Emre Erkan 2016-08-06 20:32:17 +03:00
commit a42dc89796
21 changed files with 615 additions and 348 deletions

View File

@ -11,6 +11,7 @@ root = true
# use the same settings everywhere
[*]
end_of_line = lf
charset = utf-8
insert_final_newline = true
indent_style = space
indent_size = 2

1
.gitignore vendored
View File

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

View File

@ -1 +1 @@
2.3.0
2.3.1

View File

@ -6,6 +6,7 @@ This project adheres to [Semantic Versioning](http://semver.org/).
### Added
- zh-CN and zh-TW translations from @tianshuo.
- de translation from @mpbzh.
- sv translation from @magol
## [0.3.0] - 2015-12-03
### Added

View File

@ -1,7 +1 @@
Hi there,
Please open a pull request with any suggestions you have.
Edit files in [`source/`](source/). Each sub-directory is a different language translation of [`source/index.haml`](source/index.haml).
You will need a maintainer to run `rake publish` for you once changes are merged in in order to update keepachangelog.com.
See [README](README.md#development).

View File

@ -1,12 +1,12 @@
source "https://rubygems.org"
gem "addressable"
gem "middleman", "~>3.4.0"
gem "middleman", "~> 4.1.0"
gem "middleman-autoprefixer"
gem "middleman-blog"
gem "middleman-livereload"
gem "middleman-minify-html"
gem "middleman-syntax"
gem 'middleman-gh-pages'
gem "middleman-gh-pages"
gem "redcarpet"
gem "pry"

View File

@ -1,165 +1,149 @@
GEM
remote: https://rubygems.org/
specs:
activesupport (4.2.4)
activesupport (4.2.7)
i18n (~> 0.7)
json (~> 1.7, >= 1.7.7)
minitest (~> 5.1)
thread_safe (~> 0.3, >= 0.3.4)
tzinfo (~> 1.1)
addressable (2.3.8)
autoprefixer-rails (6.0.3)
addressable (2.4.0)
autoprefixer-rails (6.4.0.1)
execjs
json
capybara (2.4.4)
mime-types (>= 1.16)
nokogiri (>= 1.3.3)
rack (>= 1.0.0)
rack-test (>= 0.5.4)
xpath (~> 2.0)
chunky_png (1.3.4)
backports (3.6.8)
coderay (1.1.1)
coffee-script (2.4.1)
coffee-script-source
execjs
coffee-script-source (1.9.1.1)
compass (1.0.3)
chunky_png (~> 1.2)
compass-core (~> 1.0.2)
compass-import-once (~> 1.0.5)
rb-fsevent (>= 0.9.3)
rb-inotify (>= 0.9)
sass (>= 3.3.13, < 3.5)
compass-core (1.0.3)
multi_json (~> 1.0)
sass (>= 3.3.0, < 3.5)
coffee-script-source (1.10.0)
compass-import-once (1.0.5)
sass (>= 3.2, < 3.5)
concurrent-ruby (1.0.2)
contracts (0.13.0)
dotenv (2.1.1)
em-websocket (0.5.1)
eventmachine (>= 0.12.9)
http_parser.rb (~> 0.6.0)
erubis (2.7.0)
eventmachine (1.0.8)
execjs (2.6.0)
ffi (1.9.10)
eventmachine (1.2.0.1)
execjs (2.7.0)
fast_blank (1.0.0)
fastimage (2.0.0)
addressable (~> 2)
ffi (1.9.14)
haml (4.0.7)
tilt
hike (1.2.3)
hooks (0.4.1)
uber (~> 0.0.14)
hamster (3.0.0)
concurrent-ruby (~> 1.0)
hashie (3.4.4)
htmlcompressor (0.2.0)
http_parser.rb (0.6.0)
i18n (0.7.0)
json (1.8.3)
kramdown (1.9.0)
listen (3.0.3)
rb-fsevent (>= 0.9.3)
rb-inotify (>= 0.9)
middleman (3.4.0)
kramdown (1.11.1)
listen (3.0.8)
rb-fsevent (~> 0.9, >= 0.9.4)
rb-inotify (~> 0.9, >= 0.9.7)
memoist (0.14.0)
method_source (0.8.2)
middleman (4.1.10)
coffee-script (~> 2.2)
compass (>= 1.0.0, < 2.0.0)
compass-import-once (= 1.0.5)
execjs (~> 2.0)
haml (>= 4.0.5)
kramdown (~> 1.2)
middleman-core (= 3.4.0)
middleman-sprockets (>= 3.1.2)
middleman-cli (= 4.1.10)
middleman-core (= 4.1.10)
sass (>= 3.4.0, < 4.0)
uglifier (~> 2.5)
middleman-autoprefixer (2.6.1)
autoprefixer-rails (~> 6.0.1)
middleman-autoprefixer (2.7.0)
autoprefixer-rails (>= 6.3.1, < 7.0.0)
middleman-core (>= 3.3.3)
middleman-blog (3.5.3)
addressable (~> 2.3.5)
middleman-core (~> 3.2)
middleman-blog (4.0.1)
addressable (~> 2.3)
middleman-core (>= 4.0.0)
tzinfo (>= 0.3.0)
middleman-core (3.4.0)
activesupport (~> 4.1)
middleman-cli (4.1.10)
thor (>= 0.17.0, < 2.0)
middleman-core (4.1.10)
activesupport (~> 4.2)
addressable (~> 2.3)
backports (~> 3.6)
bundler (~> 1.1)
capybara (~> 2.4.4)
contracts (~> 0.13.0)
dotenv
erubis
hooks (~> 0.3)
execjs (~> 2.0)
fast_blank
fastimage (~> 2.0)
hamster (~> 3.0)
hashie (~> 3.4)
i18n (~> 0.7.0)
listen (~> 3.0.3)
padrino-helpers (~> 0.12.3)
listen (~> 3.0.0)
memoist (~> 0.14)
padrino-helpers (~> 0.13.0)
parallel
rack (>= 1.4.5, < 2.0)
thor (>= 0.15.2, < 2.0)
tilt (~> 1.4.1, < 2.0)
sass (>= 3.4)
servolux
tilt (~> 1.4.1)
uglifier (~> 3.0)
middleman-gh-pages (0.0.3)
rake (> 0.9.3)
middleman-livereload (3.4.3)
middleman-livereload (3.4.6)
em-websocket (~> 0.5.1)
middleman-core (>= 3.3)
rack-livereload (~> 0.3.15)
middleman-minify-html (3.4.1)
htmlcompressor (~> 0.2.0)
middleman-core (>= 3.2)
middleman-sprockets (3.4.2)
middleman-core (>= 3.3)
sprockets (~> 2.12.1)
sprockets-helpers (~> 1.1.0)
sprockets-sass (~> 1.3.0)
middleman-syntax (2.0.0)
middleman-core (~> 3.2)
rouge (~> 1.0)
mime-types (2.6.2)
mini_portile (0.6.2)
minitest (5.8.1)
multi_json (1.11.2)
nokogiri (1.6.6.2)
mini_portile (~> 0.6.0)
padrino-helpers (0.12.5)
middleman-syntax (3.0.0)
middleman-core (>= 3.2)
rouge (~> 2.0)
minitest (5.9.0)
padrino-helpers (0.13.2)
i18n (~> 0.6, >= 0.6.7)
padrino-support (= 0.12.5)
tilt (~> 1.4.1)
padrino-support (0.12.5)
padrino-support (= 0.13.2)
tilt (>= 1.4.1, < 3)
padrino-support (0.13.2)
activesupport (>= 3.1)
parallel (1.9.0)
pry (0.10.3)
coderay (~> 1.1.0)
method_source (~> 0.8.1)
slop (~> 3.4)
rack (1.6.4)
rack-livereload (0.3.16)
rack
rack-test (0.6.3)
rack (>= 1.0)
rake (10.4.2)
rb-fsevent (0.9.6)
rb-inotify (0.9.5)
rb-fsevent (0.9.7)
rb-inotify (0.9.7)
ffi (>= 0.5.0)
redcarpet (3.3.3)
rouge (1.10.1)
sass (3.4.19)
sprockets (2.12.4)
hike (~> 1.2)
multi_json (~> 1.0)
rack (~> 1.0)
tilt (~> 1.1, != 1.3.0)
sprockets-helpers (1.1.0)
sprockets (~> 2.0)
sprockets-sass (1.3.1)
sprockets (~> 2.0)
tilt (~> 1.1)
rouge (2.0.5)
sass (3.4.22)
servolux (0.12.0)
slop (3.6.0)
thor (0.19.1)
thread_safe (0.3.5)
tilt (1.4.1)
tzinfo (1.2.2)
thread_safe (~> 0.1)
uber (0.0.15)
uglifier (2.7.2)
execjs (>= 0.3.0)
json (>= 1.8.0)
xpath (2.0.0)
nokogiri (~> 1.3)
uglifier (3.0.1)
execjs (>= 0.3.0, < 3)
PLATFORMS
ruby
DEPENDENCIES
addressable
middleman (~> 3.4.0)
middleman (~> 4.1.0)
middleman-autoprefixer
middleman-blog
middleman-gh-pages
middleman-livereload
middleman-minify-html
middleman-syntax
pry
redcarpet
BUNDLED WITH
1.10.6
1.12.0

189
README.md
View File

@ -1,169 +1,46 @@
# Keep a CHANGELOG
# Keep a CHANGELOG [![version](https://img.shields.io/badge/version-0.3.0-blue.svg)][CHANGELOG]
## Dont let your friends dump git logs into CHANGELOGs™
Dont let your friends dump git logs into CHANGELOGs™
### Whats a change log?
A change log is a file which contains a curated, chronologically ordered
list of notable changes for each version of a project.
This repository generates http://keepachangelog.com/.
<a href="CHANGELOG.md" title="An example of a CHANGELOG file."><iframe src="CHANGELOG.md" width="570" height="350" seamless="seamless" style="border: 1px solid #aaa; padding: 1em; margin: 0 0.5em;"></iframe></a>
## Development
### Dependencies
### Whats the point of a change log?
To make it easier for users and contributors to see precisely what
notable changes have been made between each release (or version) of the project.
- Ruby ([see version][ruby-version], [rbenv][rbenv] recommended)
- Bundler (`gem install bundler`)
### Why should I care?
Because software tools are for people. If you dont care, why are
you contributing to open source? Surely, there must be a kernel (ha!)
of care somewhere in that lovely little brain of yours.
### Installation
I [talked with Adam Stacoviak and Jerod Santo on The Changelog][thechangelog]
(fitting, right?) podcast about why maintainers and
contributors should care, and the motivations behind this project.
If you can spare the time (1:06), its a good listen.
- `git clone https://github.com/olivierlacan/keep-a-changelog.git`
- `cd keep-a-changelog`
- `bundle install`
- `middleman` starts the local development server at http://localhost:4567
### What makes a good change log?
Im glad you asked.
### Deployment
- `rake publish` builds and pushes to the `gh-pages` branch
A good change log sticks to these principles:
### Translations
- Its made for humans, not machines, so legibility is crucial.
- Easy to link to any section (hence Markdown over plain text).
- One sub-section per version.
- List releases in reverse-chronological order (newest on top).
- Write all dates in `YYYY-MM-DD` format. (Example: `2012-06-02` for `June 2nd, 2012`.) Its international, [sensible](https://xkcd.com/1179/), and language-independent.
- Explicitly mention whether the project follows [Semantic Versioning][semver].
- Each version should:
- List its release date in the above format.
- Group changes to describe their impact on the project, as follows:
- `Added` for new features.
- `Changed` for changes in existing functionality.
- `Deprecated` for once-stable features removed in upcoming releases.
- `Removed` for deprecated features removed in this release.
- `Fixed` for any bug fixes.
- `Security` to invite users to upgrade in case of vulnerabilities.
Create a new directory in [`source/`][source] named after the ISO 639-1 code
for the language you wish to translate Keep a CHANGELOG to. For example,
assuming you want to translate to French Canadian:
- create the `source/fr-CA` directory.
- duplicate the `source/en-US/index.html.haml` file in `source/fr-CA`.
- edit `source/fr-CA/index.html.haml` until your translation is ready.
- commit your changes to your own [fork][fork]
- submit a [Pull Request][pull-request] with your changes
### How can I minimize the effort required?
Always have an `"Unreleased"` section at the top for keeping track of any
changes.
It may take some time to review your submitted Pull Request. Try to involve a
few native speakers of the language you're translating to in the Pull Request
comments. They'll help review your translation for simple mistakes and give us
a better idea of whether your translation is accurate.
This serves two purposes:
- People can see what changes they might expect in upcoming releases
- At release time, you just have to change `"Unreleased"` to the version number
and add a new `"Unreleased"` header at the top.
### What makes unicorns cry?
Alright…lets get into it.
- **Dumping a diff of commit logs.** Just dont do that, youre helping nobody.
- **Not emphasizing deprecations.** When people upgrade from one version to
another, it should be painfully clear when something will break.
- **Dates in region-specific formats.** In the U.S., people put the month first
("06-02-2012" for June 2nd, 2012, which makes *no* sense), while many people
in the rest of the world write a robotic-looking "2 June 2012", yet pronounce
it differently. "2012-06-02" works logically from largest to smallest, doesn't
overlap in ambiguous ways with other date formats, and is an
[ISO standard](http://www.iso.org/iso/home/standards/iso8601.htm). Thus, it
is the recommended date format for change logs.
Theres more. Help me collect those unicorn tears by
[opening an issue][issues]
or a pull request.
### Is there a standard change log format?
Sadly, no. Calm down. I know you're furiously rushing to find that link
to the GNU change log style guide, or the two-paragraph GNU NEWS file
"guideline". The GNU style guide is a nice start but it is sadly naive.
There's nothing wrong with being naive but when people need
guidance it's rarely very helpful. Especially when there are many
situations and edge cases to deal with.
This project [contains what I hope will become a better CHANGELOG file convention][CHANGELOG].
I don't think the status quo is good enough, and I think that as a community we
can come up with better conventions if we try to extract good practices from
real software projects. Please take a look around and remember that
[discussions and suggestions for improvements are welcome][issues]!
### What should the change log file be named?
Well, if you cant tell from the example above, `CHANGELOG.md` is the
best convention so far.
Some projects also use `HISTORY.txt`, `HISTORY.md`, `History.md`, `NEWS.txt`,
`NEWS.md`, `News.txt`, `RELEASES.txt`, `RELEASE.md`, `releases.md`, etc.
Its a mess. All these names only makes it harder for people to find it.
### Why cant people just use a `git log` diff?
Because log diffs are full of noise — by nature. They could not make a suitable
change log even in a hypothetical project run by perfect humans who never make
typos, never forget to commit new files, never miss any part of a refactoring.
The purpose of a commit is to document one atomic step in the process by which
the code evolves from one state to another. The purpose of a change log is to
document the noteworthy differences between these states.
As is the difference between good comments and the code itself,
so is the difference between a change log and the commit log:
one describes the *why*, the other the how.
### Can change logs be automatically parsed?
Its difficult, because people follow wildly different formats and file names.
[Vandamme][vandamme] is a Ruby gem
created by the [Gemnasium][gemnasium] team and which parses
many (but not all) open source project change logs.
### Why do you alternate between spelling it "CHANGELOG" and "change log"?
"CHANGELOG" is the name of the file itself. It's a bit shouty but it's a
historical convention followed by many open source projects. Other
examples of similar files include [`README`](README.md), [`LICENSE`](LICENSE),
and [`CONTRIBUTING`](CONTRIBUTING.md).
The uppercase naming (which in old operating systems made these files stick
to the top) is used to draw attention to them. Since they're important
metadata about the project, they could be useful to anyone intending to use
or contribute to it, much like [open source project badges][shields].
When I refer to a "change log", I'm talking about the function of this
file: to log changes.
### What about yanked releases?
Yanked releases are versions that had to be pulled because of a serious
bug or security issue. Often these versions don't even appear in change
logs. They should. This is how you should display them:
`## 0.0.5 - 2014-12-13 [YANKED]`
The `[YANKED]` tag is loud for a reason. It's important for people to
notice it. Since it's surrounded by brackets it's also easier to parse
programmatically.
### Should you ever rewrite a change log?
Sure. There are always good reasons to improve a change log. I regularly open
pull requests to add missing releases to open source projects with unmaintained
change logs.
It's also possible you may discover that you forgot to address a breaking change
in the notes for a version. It's obviously important for you to update your
change log in this case.
### How can I contribute?
This document is not the **truth**; its my carefully considered
opinion, along with information and examples I gathered.
Although I provide an actual [CHANGELOG][] on [the GitHub repo][gh],
I have purposefully not created a proper *release* or clear list of rules
to follow (as [SemVer.org][semver] does, for instance).
This is because I want our community to reach a consensus. I believe the
discussion is as important as the end result.
So please [**pitch in**][gh].
Thank you for your help improving software one changelog at a time!
[CHANGELOG]: ./CHANGELOG.md
[gemnasium]: https://gemnasium.com
[gh]: https://github.com/olivierlacan/keep-a-changelog
[issues]: https://github.com/olivierlacan/keep-a-changelog/issues
[semver]: http://semver.org
[shields]: http://shields.io
[thechangelog]: http://5by5.tv/changelog/127
[vandamme]: https://github.com/tech-angels/vandamme/
[rbenv]: https://github.com/rbenv/rbenv
[ruby-version]: .ruby-version
[source]: source/
[pull-request]: https://help.github.com/articles/creating-a-pull-request/
[fork]: https://help.github.com/articles/fork-a-repo/

View File

@ -3,12 +3,33 @@
# --------------------------------------
# ----- Site ----- #
$last_version = "0.3.0"
$languages = {
de: "Deutsch",
en: "English",
"es-ES" => "Español",
"pt-BR" => "Brazilian Portugese",
ru: "Pyccкий",
"zh-CN" => "简体中文",
"zh-TW" => " 繁體中文",
"sv" => "Svenska"
}
activate :i18n,
lang_map: $languages,
mount_at_root: :en
activate :i18n, langs: [:en, 'es-ES', 'pt-BR', :ru, 'zh-CN', 'zh-TW'], :mount_at_root => :en
set :gauges_id, ''
set :publisher_url, 'https://www.facebook.com/olivier.lacan.5'
set :site_url, 'http://keepachangelog.com'
redirect "index.html", to: "en/#{$last_version}/index.html"
$languages.each do |language|
language_param = language.last.parameterize
redirect "#{language.first}/index.html", to: "#{language.first}/#{$last_version}/index.html"
end
# ----- Assets ----- #
set :css_dir, 'assets/stylesheets'
@ -37,7 +58,7 @@ set :markdown, {
helpers do
def path_to_url(path)
Addressable::URI.join(site_url, path).normalize.to_s
Addressable::URI.join(config.site_url, path).normalize.to_s
end
end

1
routes.rb Normal file
View File

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

View File

@ -2,6 +2,7 @@
description: Keep a Changelog
title: Keep a Changelog
language: de
version: 0.3.0
---
:markdown
@ -9,11 +10,13 @@ language: de
## Lass deine Freunde nicht CHANGELOGs mit git logs füllen™
Version **#{current_page.metadata[:page][:version]}**
### Was ist ein Changelog?
Ein Changelog ist eine Datei, welche eine nachgeführte, chronologisch sortierte
Liste aller relevanten Änderungen für jede Version eines Projektes enthält.
%pre.changelog= File.read(File.expand_path("../../../CHANGELOG.md", __FILE__))
%pre.changelog= File.read("CHANGELOG.md")
:markdown
### Was ist der Zweck eines Changelogs?

View File

@ -2,6 +2,7 @@
description: Keep a Changelog
title: Keep a Changelog
language: en
version: 0.3.0
---
:markdown
@ -9,11 +10,13 @@ language: en
## Dont let your friends dump git logs into CHANGELOGs™
Version **#{current_page.metadata[:page][:version]}**
### Whats a change log?
A change log is a file which contains a curated, chronologically ordered
list of notable changes for each version of a project.
%pre.changelog= File.read(File.expand_path("../../CHANGELOG.md", __FILE__))
%pre.changelog= File.read("CHANGELOG.md")
:markdown
### Whats the point of a change log?

View File

@ -2,6 +2,7 @@
description: Mantenga un Changelog
title: Mantenga un Changelog
language: es-ES
version: 0.3.0
---
:markdown
@ -9,11 +10,13 @@ language: es-ES
## No dejes que tus amigos copien y peguen git logs en los CHANGELOGs™
Version **#{current_page.metadata[:page][:version]}**
### Qué es un registro de cambios (change log)?
Un registro de cambios o “change log” de ahora en adelante, es un archivo que contiene una lista en orden cronológico sobre los cambios que vamos haciendo en cada reléase (o versión) de nuestro proyecto.
%pre.changelog= File.read(File.expand_path("../../../CHANGELOG.md", __FILE__))
%pre.changelog= File.read("CHANGELOG.md")
:markdown
### Cuál es el propósito del change log?

183
source/index.html.haml Normal file
View File

@ -0,0 +1,183 @@
---
description: Keep a Changelog
title: Keep a Changelog
language: en
version: 0.3.0
---
:markdown
# Keep a CHANGELOG
## Dont let your friends dump git logs into CHANGELOGs™
Version **#{current_page.metadata[:page][:version]}**
### Whats a change log?
A change log is a file which contains a curated, chronologically ordered
list of notable changes for each version of a project.
%pre.changelog= File.read("CHANGELOG.md")
:markdown
### Whats the point of a change log?
To make it easier for users and contributors to see precisely what
notable changes have been made between each release (or version) of the project.
### Why should I care?
Because software tools are for people. If you dont care, why are
you contributing to open source? Surely, there must be a kernel (ha!)
of care somewhere in that lovely little brain of yours.
I [talked with Adam Stacoviak and Jerod Santo on The Changelog][thechangelog]
(fitting, right?) podcast about why maintainers and
contributors should care, and the motivations behind this project.
If you can spare the time (1:06), its a good listen.
### What makes a good change log?
Im glad you asked.
A good change log sticks to these principles:
- Its made for humans, not machines, so legibility is crucial.
- Easy to link to any section (hence Markdown over plain text).
- One sub-section per version.
- List releases in reverse-chronological order (newest on top).
- Write all dates in `YYYY-MM-DD` format. (Example: `2012-06-02` for `June 2nd, 2012`.) Its international, [sensible](http://xkcd.com/1179/), and language-independent.
- Explicitly mention whether the project follows [Semantic Versioning][semver].
- Each version should:
- List its release date in the above format.
- Group changes to describe their impact on the project, as follows:
- `Added` for new features.
- `Changed` for changes in existing functionality.
- `Deprecated` for once-stable features removed in upcoming releases.
- `Removed` for deprecated features removed in this release.
- `Fixed` for any bug fixes.
- `Security` to invite users to upgrade in case of vulnerabilities.
### How can I minimize the effort required?
Always have an `"Unreleased"` section at the top for keeping track of any
changes.
This serves two purposes:
- People can see what changes they might expect in upcoming releases
- At release time, you just have to change `"Unreleased"` to the version number
and add a new `"Unreleased"` header at the top.
### What makes unicorns cry?
Alright…lets get into it.
- **Dumping a diff of commit logs.** Just dont do that, youre helping nobody.
- **Not emphasizing deprecations.** When people upgrade from one version to
another, it should be painfully clear when something will break.
- **Dates in region-specific formats.** In the U.S., people put the month first
("06-02-2012" for June 2nd, 2012, which makes *no* sense), while many people
in the rest of the world write a robotic-looking "2 June 2012", yet pronounce
it differently. "2012-06-02" works logically from largest to smallest, doesn't
overlap in ambiguous ways with other date formats, and is an
[ISO standard](http://www.iso.org/iso/home/standards/iso8601.htm). Thus, it
is the recommended date format for change logs.
Theres more. Help me collect those unicorn tears by
[opening an issue][issues]
or a pull request.
### Is there a standard change log format?
Sadly, no. Calm down. I know you're furiously rushing to find that link
to the GNU change log style guide, or the two-paragraph GNU NEWS file
"guideline". The GNU style guide is a nice start but it is sadly naive.
There's nothing wrong with being naive but when people need
guidance it's rarely very helpful. Especially when there are many
situations and edge cases to deal with.
This project [contains what I hope will become a better CHANGELOG file convention][CHANGELOG].
I don't think the status quo is good enough, and I think that as a community we
can come up with better conventions if we try to extract good practices from
real software projects. Please take a look around and remember that
[discussions and suggestions for improvements are welcome][issues]!
### What should the change log file be named?
Well, if you cant tell from the example above, `CHANGELOG.md` is the
best convention so far.
Some projects also use `HISTORY.txt`, `HISTORY.md`, `History.md`, `NEWS.txt`,
`NEWS.md`, `News.txt`, `RELEASES.txt`, `RELEASE.md`, `releases.md`, etc.
Its a mess. All these names only makes it harder for people to find it.
### Why cant people just use a `git log` diff?
Because log diffs are full of noise — by nature. They could not make a suitable
change log even in a hypothetical project run by perfect humans who never make
typos, never forget to commit new files, never miss any part of a refactoring.
The purpose of a commit is to document one atomic step in the process by which
the code evolves from one state to another. The purpose of a change log is to
document the noteworthy differences between these states.
As is the difference between good comments and the code itself,
so is the difference between a change log and the commit log:
one describes the *why*, the other the how.
### Can change logs be automatically parsed?
Its difficult, because people follow wildly different formats and file names.
[Vandamme][vandamme] is a Ruby gem
created by the [Gemnasium][gemnasium] team and which parses
many (but not all) open source project change logs.
### Why do you alternate between spelling it "CHANGELOG" and "change log"?
"CHANGELOG" is the name of the file itself. It's a bit shouty but it's a
historical convention followed by many open source projects. Other
examples of similar files include [`README`][README], [`LICENSE`][LICENSE],
and [`CONTRIBUTING`][CONTRIBUTING].
The uppercase naming (which in old operating systems made these files stick
to the top) is used to draw attention to them. Since they're important
metadata about the project, they could be useful to anyone intending to use
or contribute to it, much like [open source project badges][shields].
When I refer to a "change log", I'm talking about the function of this
file: to log changes.
### What about yanked releases?
Yanked releases are versions that had to be pulled because of a serious
bug or security issue. Often these versions don't even appear in change
logs. They should. This is how you should display them:
`## 0.0.5 - 2014-12-13 [YANKED]`
The `[YANKED]` tag is loud for a reason. It's important for people to
notice it. Since it's surrounded by brackets it's also easier to parse
programmatically.
### Should you ever rewrite a change log?
Sure. There are always good reasons to improve a change log. I regularly open
pull requests to add missing releases to open source projects with unmaintained
change logs.
It's also possible you may discover that you forgot to address a breaking change
in the notes for a version. It's obviously important for you to update your
change log in this case.
### How can I contribute?
This document is not the **truth**; its my carefully considered
opinion, along with information and examples I gathered.
Although I provide an actual [CHANGELOG][] on [the GitHub repo][gh],
I have purposefully not created a proper *release* or clear list of rules
to follow (as [SemVer.org][semver] does, for instance).
This is because I want our community to reach a consensus. I believe the
discussion is as important as the end result.
So please [**pitch in**][gh].
[CHANGELOG]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md
[CONTRIBUTING]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CONTRIBUTING.md
[LICENSE]: https://github.com/olivierlacan/keep-a-changelog/blob/master/LICENSE
[README]: https://github.com/olivierlacan/keep-a-changelog/blob/master/README.md
[gemnasium]: https://gemnasium.com/
[gh]: https://github.com/olivierlacan/keep-a-changelog
[issues]: https://github.com/olivierlacan/keep-a-changelog/issues
[semver]: http://semver.org/
[shields]: http://shields.io/
[thechangelog]: http://5by5.tv/changelog/127
[vandamme]: https://github.com/tech-angels/vandamme/

View File

@ -8,7 +8,7 @@
-# Open Graph
%meta{property: 'og:article:publisher', content: publisher_url}
%meta{property: 'og:article:publisher', content: config.publisher_url}
%meta{property: 'og:title', content: current_page.data.title}
%meta{property: 'og:type', content: 'article'}
%meta{property: 'og:url', content: path_to_url(current_page.url)}
@ -31,13 +31,9 @@
%header{role: "banner"}
%nav.locales{role: "navigation"}
%ul
%li= link_to 'english [en]', '/', {rel: "alternate", lang: "en", hreflang: "en"}
%li= link_to 'español [es-ES]', '/es-ES/', {rel: "alternate", lang: "es-ES", hreflang: "es-ES"}
%li= link_to 'português brasileiro [pt-BR]', '/pt-BR/', {rel: "alternate", lang: "pt-BR", hreflang: "pt-BR"}
%li= link_to 'pyccкий [ru]', '/ru/', {rel: "alternate", lang: "ru", hreflang: "ru"}
%li= link_to '简体中文 [zh-CN]', '/zh-CN/', {rel: "alternate", lang: "zh-CN", hreflang: "zh-CN"}
%li= link_to '繁體中文 [zh-TW]', '/zh-TW/', {rel: "alternate", lang: "zh-TW", hreflang: "zh-TW"}
%li= link_to 'german [de]', '/de/', {rel: "alternate", lang: "de", hreflang: "de"}
- $languages.each do |language|
%li= link_to "#{language.last} [#{language.first}]", "/#{language.first}/",
{ rel: "alternate", lang: "#{language}", hreflang: "#{language}" }
.main{role: "main"}= yield
@ -51,7 +47,7 @@
#{link_to "Olivier Lacan", "http://olivierlacan.com/"} from
#{link_to "Code School", "https://www.codeschool.com/"}.
- unless gauges_id.blank?
- unless config.gauges_id.blank?
:javascript
var _gauges = _gauges || [];
(function() {
@ -59,7 +55,7 @@
t.type = 'text/javascript';
t.async = true;
t.id = 'gauges-tracker';
t.setAttribute('data-site-id', '#{gauges_id}');
t.setAttribute('data-site-id', '#{config.gauges_id}');
t.src = '//secure.gaug.es/track.js';
var s = document.getElementsByTagName('script')[0];
s.parentNode.insertBefore(t, s);

View File

@ -2,6 +2,7 @@
description: Mantenha um CHANGELOG
title: Mantenha um CHANGELOG
language: pt-BR
version: 0.3.0
---
:markdown
@ -9,13 +10,15 @@ language: pt-BR
## Não deixe seus amigos despejar logs de commits em CHANGELOGs™
Version **#{current_page.metadata[:page][:version]}**
### O que é um change log?
Um *change log* é um arquivo que contém uma lista selecionada, ordenada
cronologicamente de mudanças significativas para cada versão de um projeto
open source.
%pre.changelog= File.read(File.expand_path("../../../CHANGELOG.md", __FILE__))
%pre.changelog= File.read("CHANGELOG.md")
:markdown
### Para que serve um *change log*?

View File

@ -2,6 +2,7 @@
description: Ведите Changelog
title: Ведите Changelog
language: ru
version: 0.3.0
---
:markdown
@ -9,13 +10,15 @@ language: ru
## Не позволяйте друзьям сливать логи гита в CHANGELOG™
Version **#{current_page.metadata[:page][:version]}**
### Что такое лог изменений?
Лог изменений это файл, который содержит поддерживаемый, упорядоченный в
хронологическом порядке список значимых изменений для каждой версии проекта с
открытым исходным кодом.
%pre.changelog= File.read(File.expand_path("../../../CHANGELOG.md", __FILE__))
%pre.changelog= File.read("CHANGELOG.md")
:markdown
### Для чего нужен лог изменений?

View File

@ -0,0 +1,187 @@
---
description: Håll en ändringslogg
title: Håll en ändringslogg
language: sv
version: 0.3.0
---
:markdown
# Håll en CHANGELOG
## Låt inte dina vänner slänga in en git logs i CHANGELOG™
Version **#{current_page.metadata[:page][:version]}**
### Vad är en ändringslogg?
En ändringslogg är en fil innehållandes en sammanfattad, kronologiskt ordnad
lista över ändringar för varje version av ett projekt.
%pre.changelog= File.read("CHANGELOG.md")
:markdown
### Vad är meningen med en ändringslogg?
För att göra det enkelt för användare och medarbetare att se exakt vilka
viktiga ändringar som har gjort mellan varje utgåva (eller version) av projektet.
### Varför ska jag bry mig?
Därför att mjukvaruverktyg är för människor. Om du inte bryr dig, varför
bidrar du till öppen källkod? Visst finns det väl någon del i din vackra
hjärna som bryr sig.
Jag [pratade med Adam Stacoviak och Jerod Santo på The Changelog][thechangelog]
(passande, eller hur?) podcast om varför ansvariga och bidragsgivare bör bry sig,
och motiveringen bakom detta projekt.
Om du kan avvara lite tid (1:06), rekommenderar jag att lyssna på det.
### Vad gör en bra ändringslogg?
Jag är glad att du frågade.
En bra ändringslogg håller sig till dessa principer:
- Den är skapad för människor, inte maskiner, så läsbarhet är avgörande.
- Lätt att länka till valfri sektion (därav Markdown framför klartext).
- En undersektion per version.
- Lista utgåvor i omvänd kronologisk ordning (nyast högst upp).
- Skriv alla datum på formatet `YYYY-MM-DD`
(exempel: `2012-06-02` för 2:a juni 2012). Det är internationellt,
[förnuftigt](http://xkcd.com/1179/) och språkoberoende.
- Ange uttryckligen att projektet följer [Semantisk versionshantering][SemVer].
- Varje version bör:
- Ange datum då utgåvan släptes på formatet angivet ovan.
- Gruppera ändringar för att beskriva deras inverkan på projektet enligt följande:
- `Added` för nya funktioner.
- `Changed` för ändringar på existerande funktionalitet.
- `Deprecated` för tidigare stabila funktioner som tas bort i nästa utgåva.
- `Removed` för funktioner tidigare markerade som `deprecated` som tas bort i denna version.
- `Fixed` för buggfixar.
- `Security` för att uppmana användare att uppgradera vid fall av sårbarheter.
### Hur kan jag minimera den insats som krävs?
Ha alltid en sektion kallas `"Unreleased"` högst upp för att hålla reda på
alla ändringar.
Detta tjänar två syften:
- Folk kan se vilka ändringar som kan förväntas i kommande utgåvor
- Vid lansering behöver du bara ändra `"Unreleased"` till versionsnumret
och lägga till en ny `"Unreleased"` högst upp.
### Vad får änglarna att gråta?
Okej...låt oss gå genom det.
- **Dumpa ut en diff från commit-loggen.** Gör helt enkelt inte så, du hjälper ingen.
- **Inte betona `deprecations`.** När folk uppgraderar från en version till
en annan ska det vara smärtsamt uppenbart om något förväntas gå sönder.
- **Datum i region-specifikt format.** I USA lägger folk månaden föst
("06-02-2012" för 2:a juni 2012, vilket bara är *konstigt*), medan många
andra runt om i världen skriver "2 June 2012" men uttala det annorlunda.
"2012-06-02" fungerar logiskt från största till minsta, inte överlappar på ett
tvetydligt sätt med andra datumformat, och det är en
[ISO-standard](http://www.iso.org/iso/home/standards/iso8601.htm). Dessutom
är det rekommenderat datumformat för ändringsloggar.
Det finns mer. Hjälp mig att samla tårarna från änglarna genom att
[öppna en issue][issues]
eller en pull-förfrågan.
### Finns det ett standardformat på ändringsloggar?
Tyvärr inte. Men lugn. Jag vet att du frustrerad kommer att rusa iväg för att hitta
den där länken till GUS:s format för ändringsloggar, eller den två stycken långa
GNU NEWS-filen med "guideline". Stilguiden från GNU är en bra start, men den är
tyvärr allt för naiv. Det är inget fel med att vara naiv, men när människor
behöver vägledning är det inte speciellt hjälpsamt. Speciellt när det är många
olika situationer och specialfall att hantera.
Detta projekt [innehåller vad jag hoppas kommer att bli en bättre filkonvention
för CHANGELOG][CHANGELOG]. Jag tror inte att status quo är tillräckligt bra,
och jag tror att vi tillsammans kan komma fram till en bättre konvention
om vi försöker att plocka ut bra erfarenheter från riktiga mjukvaruprojekt.
Titta runt och kom ihåg att [diskussioner och förbättringsförslag är välkomna][issues]!
### Vad bör filen med ändringsloggen heta?
Tja, om du inte kan lista ut det från exemplen ovan är `CHANGELOG.md`
den bästa konvention hittills.
En del projekt använder också `HISTORY.txt`, `HISTORY.md`, `History.md`, `NEWS.txt`,
`NEWS.md`, `News.txt`, `RELEASES.txt`, `RELEASE.md`, `releases.md`, etc.
Det är en verklig röra. Alla dessa namn gör det bara svårare för människor att hitta.
### Varför kan folk inte bara använda en diff från `git log`?
Eftersom logg-diffar av naturen är fulla med brus. Det kan inte ens användas
för att göra en lämplig ändringslogg ens i ett hypotetiskt projekt drivet av
perfekta människor som aldrig skriver fel, aldrig glömmer att checka in nya filer
eller aldrig glömmer någon del av en refaktorering. Syftet med en commit är att
dokumentera ett enskilt steg i processen då koden utvecklas från ett tillstånd till
ett annat. Syftet med en ändringslogg är att dokumentera de anmärkningsvärda
skillnaderna mellan dessa tillstånd.
På samma sätt som det är skillnad mellan bra kommentarer och själva koden,
är det skillnad mellan ändringsloggen och commit-loggen:
en beskriver "varför" och den andra "hur".
### Kan ändringsloggar bli automatiskt tolkade?
Det är svårt då människor följer vitt olika format och filnamn.
[Vandamme][vandamme] är en Ruby gem
skapad av gruppen bakom [Gemnasium][gemnasium] som tolkar många (men inte alla)
ändringsloggar för öppen källkod.
### Varför alternerar du mellan att skriva det som "CHANGELOG" och "ändringslogg"?"
"CHANGELOG" är namnet på själva filen. Det sticker ut lite, men det är en
historisk konvention använt i många öppen källkodsprojekt. Andra
exempel på liknande filer är [`README`][README], [`LICENSE`][LICENSE]
och [`CONTRIBUTING`][CONTRIBUTING].
De stora bokstäverna i namnen (som gjorde att de i äldre operativsystem
hamnade högst upp) används för att dra uppmärksamhet till dem. Då de är
viktig metadata om projektet borde de vara användbara för att alla som
vill använda eller bidra till det, ungefär som [open source project badges][shields].
När jag refererar till "ändringslogg" pratar jag om syftet med denna fil:
att logga ändringar.
### Hur är det med brådskande utgåvor ("yanked")?
Brådskande utgåvor är versioner som måste släppas p.g.a. alvarliga
buggar eller säkerhetsproblem. Oftast brukar dessa versioner inte ens
finnas med i ändringsloggarna. De borde det. Så här borde du visa dem:
`## 0.0.5 - 2014-12-13 [YANKED]`
Taggen `[YANKED]` står ut av en anledning, det är viktigt för människor
att se den. Då den är omsluten med hakparenteser är det också lättare
för ett program att tolka.
### Borde du någonsin förändra en ändringslogg?
Självklart. Det finns alltid en bra anlending att förbättra en ändringslogg.
Jag öppnar regelbundet pull requests för att lägga till saknade utgåvor
för öppen källkodsprojekt som inte tar hand om sin ändringslogg.
Det kan också hända att du upptäcker att du glömt att ta upp en icke
bakåtkompatibel förändring i en version. I sådana fall är det självklart
viktigt att uppdatera din ändringslogg.
### Hur kan jag bidra?
Detta dokument är inte **sanningen**, det är en noga övervägd åsikt
tillsammans med information och exempel jag har samlat på mig.
Även om jag tillhandahåller en [CHANGELOG][] i min [GitHub repo][gh],
har jag avsiktligt inte skapat en egentlig *utgåva* eller en tydlig lista
med regler att följa (som t.ex. [SemVer.org][semver] gör).
Detta beror på att jag vill att vår gemenskap ska nå samförstånd. Jag
tror att diskussionen är lika viktig som slutresultatet.
Så välkomna att [**diskutera**]][gh].
[CHANGELOG]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md
[CONTRIBUTING]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CONTRIBUTING.md
[LICENSE]: https://github.com/olivierlacan/keep-a-changelog/blob/master/LICENSE
[README]: https://github.com/olivierlacan/keep-a-changelog/blob/master/README.md
[gemnasium]: https://gemnasium.com/
[gh]: https://github.com/olivierlacan/keep-a-changelog
[issues]: https://github.com/olivierlacan/keep-a-changelog/issues
[semver]: http://semver.org/
[shields]: http://shields.io/
[thechangelog]: http://5by5.tv/changelog/127
[vandamme]: https://github.com/tech-angels/vandamme/

View File

@ -2,6 +2,7 @@
description: 如何维护更新日志
title: 如何维护更新日志
language: zh-CN
version: 0.3.0
---
:markdown
@ -9,12 +10,14 @@ language: zh-CN
## 更新日志绝对不应该是git日志的堆砌物
Version **#{current_page.metadata[:page][:version]}**
### 更新日志是什么?
更新日志Change Log是一个由人工编辑以时间为倒叙的列表。
这个列表记录所有版本的重大变动。
%pre.changelog= File.read(File.expand_path("../../../CHANGELOG.md", __FILE__))
%pre.changelog= File.read("CHANGELOG.md")
:markdown
### 为何要提供更新日志?

View File

@ -2,6 +2,7 @@
description: 如何維護更新日誌
title: 如何維護更新日誌
language: zh-TW
version: 0.3.0
---
:markdown
@ -9,12 +10,14 @@ language: zh-TW
## 更新日誌絕對不應該是git日誌的堆砌物
Version **#{current_page.metadata[:page][:version]}**
### 更新日誌是什麽?
更新日誌Change Log是壹個由人工編輯以時間為倒敘的列表。
這個列表記錄所有版本的重大變動。
%pre.changelog= File.read(File.expand_path("../../../CHANGELOG.md", __FILE__))
%pre.changelog= File.read("CHANGELOG.md")
:markdown
### 為何要提供更新日誌?