mirror of
https://github.com/olivierlacan/keep-a-changelog.git
synced 2025-09-26 11:19:22 +02:00
Merge remote-tracking branch 'upstream/master'
# Conflicts: # CHANGELOG.md # source/layouts/layout.html.haml
This commit is contained in:
roalz
commit
b850716d1c
@ -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
1
.gitignore
vendored
@ -3,3 +3,4 @@
|
||||
/.cache
|
||||
/.sass-cache
|
||||
/build
|
||||
/_site
|
||||
|
||||
@ -1 +1 @@
|
||||
2.3.0
|
||||
2.3.1
|
||||
|
||||
10
CHANGELOG.md
10
CHANGELOG.md
@ -1,12 +1,20 @@
|
||||
# Change Log
|
||||
All notable changes to this project will be documented in this file.
|
||||
This project adheres to [Semantic Versioning](http://semver.org/).
|
||||
|
||||
The format is based on [Keep a Changelog](http://keepachangelog.com/)
|
||||
and this project adheres to [Semantic Versioning](http://semver.org/).
|
||||
|
||||
## [Unreleased]
|
||||
### Added
|
||||
- zh-CN and zh-TW translations from @tianshuo.
|
||||
- de translation from @mpbzh.
|
||||
- it-IT translation from @roalz.
|
||||
- sv translation from @magol.
|
||||
- tr-TR translation from @karalamalar.
|
||||
|
||||
### Changed
|
||||
- Start versioning based on the current English version at 0.3.0 to help
|
||||
translation authors keep things up-to-date.
|
||||
|
||||
## [0.3.0] - 2015-12-03
|
||||
### Added
|
||||
|
||||
@ -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).
|
||||
|
||||
6
Gemfile
6
Gemfile
@ -1,12 +1,12 @@
|
||||
source "https://rubygems.org"
|
||||
|
||||
gem "addressable"
|
||||
gem "middleman", "~>3.4.0"
|
||||
gem "middleman", "~> 4.1.0"
|
||||
gem "middleman-autoprefixer"
|
||||
gem "middleman-blog"
|
||||
gem "middleman-livereload"
|
||||
gem "middleman-minify-html"
|
||||
gem "middleman-syntax"
|
||||
gem 'middleman-gh-pages'
|
||||
|
||||
gem "middleman-gh-pages"
|
||||
gem "redcarpet"
|
||||
gem "pry"
|
||||
|
||||
172
Gemfile.lock
172
Gemfile.lock
@ -1,165 +1,149 @@
|
||||
GEM
|
||||
remote: https://rubygems.org/
|
||||
specs:
|
||||
activesupport (4.2.4)
|
||||
activesupport (4.2.7)
|
||||
i18n (~> 0.7)
|
||||
json (~> 1.7, >= 1.7.7)
|
||||
minitest (~> 5.1)
|
||||
thread_safe (~> 0.3, >= 0.3.4)
|
||||
tzinfo (~> 1.1)
|
||||
addressable (2.3.8)
|
||||
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
189
README.md
@ -1,169 +1,46 @@
|
||||
# Keep a CHANGELOG
|
||||
# Keep a CHANGELOG [][CHANGELOG]
|
||||
|
||||
## Don’t let your friends dump git logs into CHANGELOGs™
|
||||
Don’t let your friends dump git logs into CHANGELOGs™
|
||||
|
||||
### What’s a change log?
|
||||
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
|
||||
|
||||
### 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.
|
||||
- Ruby ([see version][ruby-version], [rbenv][rbenv] recommended)
|
||||
- Bundler (`gem install bundler`)
|
||||
|
||||
### Why should I care?
|
||||
Because software tools are for people. If you don’t care, why are
|
||||
you contributing to open source? Surely, there must be a kernel (ha!)
|
||||
of care somewhere in that lovely little brain of yours.
|
||||
### 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), it’s 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?
|
||||
I’m glad you asked.
|
||||
### Deployment
|
||||
- `rake publish` builds and pushes to the `gh-pages` branch
|
||||
|
||||
A good change log sticks to these principles:
|
||||
### Translations
|
||||
|
||||
- It’s made for humans, not machines, so legibility is crucial.
|
||||
- Easy to link to any section (hence Markdown over plain text).
|
||||
- One sub-section per version.
|
||||
- List releases in reverse-chronological order (newest on top).
|
||||
- Write all dates in `YYYY-MM-DD` format. (Example: `2012-06-02` for `June 2nd, 2012`.) It’s international, [sensible](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…let’s get into it.
|
||||
|
||||
- **Dumping a diff of commit logs.** Just don’t do that, you’re helping nobody.
|
||||
- **Not emphasizing deprecations.** When people upgrade from one version to
|
||||
another, it should be painfully clear when something will break.
|
||||
- **Dates in region-specific formats.** In the U.S., people put the month first
|
||||
("06-02-2012" for June 2nd, 2012, which makes *no* sense), while many people
|
||||
in the rest of the world write a robotic-looking "2 June 2012", yet pronounce
|
||||
it differently. "2012-06-02" works logically from largest to smallest, doesn't
|
||||
overlap in ambiguous ways with other date formats, and is an
|
||||
[ISO standard](http://www.iso.org/iso/home/standards/iso8601.htm). Thus, it
|
||||
is the recommended date format for change logs.
|
||||
|
||||
There’s more. Help me collect those unicorn tears by
|
||||
[opening an issue][issues]
|
||||
or a pull request.
|
||||
|
||||
### Is there a standard change log format?
|
||||
Sadly, no. Calm down. I know you're furiously rushing to find that link
|
||||
to the GNU change log style guide, or the two-paragraph GNU NEWS file
|
||||
"guideline". The GNU style guide is a nice start but it is sadly naive.
|
||||
There's nothing wrong with being naive but when people need
|
||||
guidance it's rarely very helpful. Especially when there are many
|
||||
situations and edge cases to deal with.
|
||||
|
||||
This project [contains what I hope will become a better CHANGELOG file convention][CHANGELOG].
|
||||
I don't think the status quo is good enough, and I think that as a community we
|
||||
can come up with better conventions if we try to extract good practices from
|
||||
real software projects. Please take a look around and remember that
|
||||
[discussions and suggestions for improvements are welcome][issues]!
|
||||
|
||||
### What should the change log file be named?
|
||||
Well, if you can’t tell from the example above, `CHANGELOG.md` is the
|
||||
best convention so far.
|
||||
|
||||
Some projects also use `HISTORY.txt`, `HISTORY.md`, `History.md`, `NEWS.txt`,
|
||||
`NEWS.md`, `News.txt`, `RELEASES.txt`, `RELEASE.md`, `releases.md`, etc.
|
||||
|
||||
It’s a mess. All these names only makes it harder for people to find it.
|
||||
|
||||
### Why can’t people just use a `git log` diff?
|
||||
Because log diffs are full of noise — by nature. They could not make a suitable
|
||||
change log even in a hypothetical project run by perfect humans who never make
|
||||
typos, never forget to commit new files, never miss any part of a refactoring.
|
||||
The purpose of a commit is to document one atomic step in the process by which
|
||||
the code evolves from one state to another. The purpose of a change log is to
|
||||
document the noteworthy differences between these states.
|
||||
|
||||
As is the difference between good comments and the code itself,
|
||||
so is the difference between a change log and the commit log:
|
||||
one describes the *why*, the other the how.
|
||||
|
||||
### Can change logs be automatically parsed?
|
||||
It’s difficult, because people follow wildly different formats and file names.
|
||||
|
||||
[Vandamme][vandamme] is a Ruby gem
|
||||
created by the [Gemnasium][gemnasium] team and which parses
|
||||
many (but not all) open source project change logs.
|
||||
|
||||
### Why do you alternate between spelling it "CHANGELOG" and "change log"?
|
||||
"CHANGELOG" is the name of the file itself. It's a bit shouty but it's a
|
||||
historical convention followed by many open source projects. Other
|
||||
examples of similar files include [`README`](README.md), [`LICENSE`](LICENSE),
|
||||
and [`CONTRIBUTING`](CONTRIBUTING.md).
|
||||
|
||||
The uppercase naming (which in old operating systems made these files stick
|
||||
to the top) is used to draw attention to them. Since they're important
|
||||
metadata about the project, they could be useful to anyone intending to use
|
||||
or contribute to it, much like [open source project badges][shields].
|
||||
|
||||
When I refer to a "change log", I'm talking about the function of this
|
||||
file: to log changes.
|
||||
|
||||
### What about yanked releases?
|
||||
Yanked releases are versions that had to be pulled because of a serious
|
||||
bug or security issue. Often these versions don't even appear in change
|
||||
logs. They should. This is how you should display them:
|
||||
|
||||
`## 0.0.5 - 2014-12-13 [YANKED]`
|
||||
|
||||
The `[YANKED]` tag is loud for a reason. It's important for people to
|
||||
notice it. Since it's surrounded by brackets it's also easier to parse
|
||||
programmatically.
|
||||
|
||||
### Should you ever rewrite a change log?
|
||||
Sure. There are always good reasons to improve a change log. I regularly open
|
||||
pull requests to add missing releases to open source projects with unmaintained
|
||||
change logs.
|
||||
|
||||
It's also possible you may discover that you forgot to address a breaking change
|
||||
in the notes for a version. It's obviously important for you to update your
|
||||
change log in this case.
|
||||
|
||||
### How can I contribute?
|
||||
This document is not the **truth**; it’s my carefully considered
|
||||
opinion, along with information and examples I gathered.
|
||||
Although I provide an actual [CHANGELOG][] on [the GitHub repo][gh],
|
||||
I have purposefully not created a proper *release* or clear list of rules
|
||||
to follow (as [SemVer.org][semver] does, for instance).
|
||||
|
||||
This is because I want our community to reach a consensus. I believe the
|
||||
discussion is as important as the end result.
|
||||
|
||||
So please [**pitch in**][gh].
|
||||
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/
|
||||
|
||||
26
config.rb
26
config.rb
@ -3,12 +3,34 @@
|
||||
# --------------------------------------
|
||||
|
||||
# ----- Site ----- #
|
||||
$last_version = "0.3.0"
|
||||
$languages = {
|
||||
"es-ES" => "Español",
|
||||
"pt-BR" => "Brazilian Portugese",
|
||||
"sv" => "Svenska",
|
||||
"zh-CN" => "简体中文",
|
||||
"zh-TW" => " 繁體中文",
|
||||
de: "Deutsch",
|
||||
en: "English",
|
||||
ru: "Pyccкий",
|
||||
"tr-TR" => "Türkçe"
|
||||
}
|
||||
|
||||
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 +59,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
|
||||
|
||||
|
||||
@ -15,11 +15,12 @@ a:hover
|
||||
|
||||
h1
|
||||
color: #C647BF
|
||||
font-size: 3.8em
|
||||
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
|
||||
@ -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?
|
||||
@ -2,6 +2,7 @@
|
||||
description: Keep a Changelog
|
||||
title: Keep a Changelog
|
||||
language: en
|
||||
version: 0.3.0
|
||||
---
|
||||
|
||||
:markdown
|
||||
@ -9,11 +10,13 @@ language: en
|
||||
|
||||
## Don’t let your friends dump git logs into CHANGELOGs™
|
||||
|
||||
Version **#{current_page.metadata[:page][:version]}**
|
||||
|
||||
### What’s a change log?
|
||||
A change log is a file which contains a curated, chronologically ordered
|
||||
list of notable changes for each version of a project.
|
||||
|
||||
%pre.changelog= File.read(File.expand_path("../../CHANGELOG.md", __FILE__))
|
||||
%pre.changelog= File.read("CHANGELOG.md")
|
||||
|
||||
:markdown
|
||||
### What’s the point of a change log?
|
||||
@ -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
183
source/index.html.haml
Normal file
@ -0,0 +1,183 @@
|
||||
---
|
||||
description: Keep a Changelog
|
||||
title: Keep a Changelog
|
||||
language: en
|
||||
version: 0.3.0
|
||||
---
|
||||
|
||||
:markdown
|
||||
# Keep a CHANGELOG
|
||||
|
||||
## Don’t let your friends dump git logs into CHANGELOGs™
|
||||
|
||||
Version **#{current_page.metadata[:page][:version]}**
|
||||
|
||||
### What’s a change log?
|
||||
A change log is a file which contains a curated, chronologically ordered
|
||||
list of notable changes for each version of a project.
|
||||
|
||||
%pre.changelog= File.read("CHANGELOG.md")
|
||||
|
||||
:markdown
|
||||
### What’s the point of a change log?
|
||||
To make it easier for users and contributors to see precisely what
|
||||
notable changes have been made between each release (or version) of the project.
|
||||
|
||||
### Why should I care?
|
||||
Because software tools are for people. If you don’t care, why are
|
||||
you contributing to open source? Surely, there must be a kernel (ha!)
|
||||
of care somewhere in that lovely little brain of yours.
|
||||
|
||||
I [talked with Adam Stacoviak and Jerod Santo on The Changelog][thechangelog]
|
||||
(fitting, right?) podcast about why maintainers and
|
||||
contributors should care, and the motivations behind this project.
|
||||
If you can spare the time (1:06), it’s a good listen.
|
||||
|
||||
### What makes a good change log?
|
||||
I’m glad you asked.
|
||||
|
||||
A good change log sticks to these principles:
|
||||
|
||||
- It’s made for humans, not machines, so legibility is crucial.
|
||||
- Easy to link to any section (hence Markdown over plain text).
|
||||
- One sub-section per version.
|
||||
- List releases in reverse-chronological order (newest on top).
|
||||
- Write all dates in `YYYY-MM-DD` format. (Example: `2012-06-02` for `June 2nd, 2012`.) It’s international, [sensible](http://xkcd.com/1179/), and language-independent.
|
||||
- Explicitly mention whether the project follows [Semantic Versioning][semver].
|
||||
- Each version should:
|
||||
- List its release date in the above format.
|
||||
- Group changes to describe their impact on the project, as follows:
|
||||
- `Added` for new features.
|
||||
- `Changed` for changes in existing functionality.
|
||||
- `Deprecated` for once-stable features removed in upcoming releases.
|
||||
- `Removed` for deprecated features removed in this release.
|
||||
- `Fixed` for any bug fixes.
|
||||
- `Security` to invite users to upgrade in case of vulnerabilities.
|
||||
|
||||
### How can I minimize the effort required?
|
||||
Always have an `"Unreleased"` section at the top for keeping track of any
|
||||
changes.
|
||||
|
||||
This serves two purposes:
|
||||
|
||||
- People can see what changes they might expect in upcoming releases
|
||||
- At release time, you just have to change `"Unreleased"` to the version number
|
||||
and add a new `"Unreleased"` header at the top.
|
||||
|
||||
### What makes unicorns cry?
|
||||
Alright…let’s get into it.
|
||||
|
||||
- **Dumping a diff of commit logs.** Just don’t do that, you’re helping nobody.
|
||||
- **Not emphasizing deprecations.** When people upgrade from one version to
|
||||
another, it should be painfully clear when something will break.
|
||||
- **Dates in region-specific formats.** In the U.S., people put the month first
|
||||
("06-02-2012" for June 2nd, 2012, which makes *no* sense), while many people
|
||||
in the rest of the world write a robotic-looking "2 June 2012", yet pronounce
|
||||
it differently. "2012-06-02" works logically from largest to smallest, doesn't
|
||||
overlap in ambiguous ways with other date formats, and is an
|
||||
[ISO standard](http://www.iso.org/iso/home/standards/iso8601.htm). Thus, it
|
||||
is the recommended date format for change logs.
|
||||
|
||||
There’s more. Help me collect those unicorn tears by
|
||||
[opening an issue][issues]
|
||||
or a pull request.
|
||||
|
||||
### Is there a standard change log format?
|
||||
Sadly, no. Calm down. I know you're furiously rushing to find that link
|
||||
to the GNU change log style guide, or the two-paragraph GNU NEWS file
|
||||
"guideline". The GNU style guide is a nice start but it is sadly naive.
|
||||
There's nothing wrong with being naive but when people need
|
||||
guidance it's rarely very helpful. Especially when there are many
|
||||
situations and edge cases to deal with.
|
||||
|
||||
This project [contains what I hope will become a better CHANGELOG file convention][CHANGELOG].
|
||||
I don't think the status quo is good enough, and I think that as a community we
|
||||
can come up with better conventions if we try to extract good practices from
|
||||
real software projects. Please take a look around and remember that
|
||||
[discussions and suggestions for improvements are welcome][issues]!
|
||||
|
||||
### What should the change log file be named?
|
||||
Well, if you can’t tell from the example above, `CHANGELOG.md` is the
|
||||
best convention so far.
|
||||
|
||||
Some projects also use `HISTORY.txt`, `HISTORY.md`, `History.md`, `NEWS.txt`,
|
||||
`NEWS.md`, `News.txt`, `RELEASES.txt`, `RELEASE.md`, `releases.md`, etc.
|
||||
|
||||
It’s a mess. All these names only makes it harder for people to find it.
|
||||
|
||||
### Why can’t people just use a `git log` diff?
|
||||
Because log diffs are full of noise — by nature. They could not make a suitable
|
||||
change log even in a hypothetical project run by perfect humans who never make
|
||||
typos, never forget to commit new files, never miss any part of a refactoring.
|
||||
The purpose of a commit is to document one atomic step in the process by which
|
||||
the code evolves from one state to another. The purpose of a change log is to
|
||||
document the noteworthy differences between these states.
|
||||
|
||||
As is the difference between good comments and the code itself,
|
||||
so is the difference between a change log and the commit log:
|
||||
one describes the *why*, the other the how.
|
||||
|
||||
### Can change logs be automatically parsed?
|
||||
It’s difficult, because people follow wildly different formats and file names.
|
||||
|
||||
[Vandamme][vandamme] is a Ruby gem
|
||||
created by the [Gemnasium][gemnasium] team and which parses
|
||||
many (but not all) open source project change logs.
|
||||
|
||||
### Why do you alternate between spelling it "CHANGELOG" and "change log"?
|
||||
"CHANGELOG" is the name of the file itself. It's a bit shouty but it's a
|
||||
historical convention followed by many open source projects. Other
|
||||
examples of similar files include [`README`][README], [`LICENSE`][LICENSE],
|
||||
and [`CONTRIBUTING`][CONTRIBUTING].
|
||||
|
||||
The uppercase naming (which in old operating systems made these files stick
|
||||
to the top) is used to draw attention to them. Since they're important
|
||||
metadata about the project, they could be useful to anyone intending to use
|
||||
or contribute to it, much like [open source project badges][shields].
|
||||
|
||||
When I refer to a "change log", I'm talking about the function of this
|
||||
file: to log changes.
|
||||
|
||||
### What about yanked releases?
|
||||
Yanked releases are versions that had to be pulled because of a serious
|
||||
bug or security issue. Often these versions don't even appear in change
|
||||
logs. They should. This is how you should display them:
|
||||
|
||||
`## 0.0.5 - 2014-12-13 [YANKED]`
|
||||
|
||||
The `[YANKED]` tag is loud for a reason. It's important for people to
|
||||
notice it. Since it's surrounded by brackets it's also easier to parse
|
||||
programmatically.
|
||||
|
||||
### Should you ever rewrite a change log?
|
||||
Sure. There are always good reasons to improve a change log. I regularly open
|
||||
pull requests to add missing releases to open source projects with unmaintained
|
||||
change logs.
|
||||
|
||||
It's also possible you may discover that you forgot to address a breaking change
|
||||
in the notes for a version. It's obviously important for you to update your
|
||||
change log in this case.
|
||||
|
||||
### How can I contribute?
|
||||
This document is not the **truth**; it’s my carefully considered
|
||||
opinion, along with information and examples I gathered.
|
||||
Although I provide an actual [CHANGELOG][] on [the GitHub repo][gh],
|
||||
I have purposefully not created a proper *release* or clear list of rules
|
||||
to follow (as [SemVer.org][semver] does, for instance).
|
||||
|
||||
This is because I want our community to reach a consensus. I believe the
|
||||
discussion is as important as the end result.
|
||||
|
||||
So please [**pitch in**][gh].
|
||||
|
||||
[CHANGELOG]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md
|
||||
[CONTRIBUTING]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CONTRIBUTING.md
|
||||
[LICENSE]: https://github.com/olivierlacan/keep-a-changelog/blob/master/LICENSE
|
||||
[README]: https://github.com/olivierlacan/keep-a-changelog/blob/master/README.md
|
||||
[gemnasium]: https://gemnasium.com/
|
||||
[gh]: https://github.com/olivierlacan/keep-a-changelog
|
||||
[issues]: https://github.com/olivierlacan/keep-a-changelog/issues
|
||||
[semver]: http://semver.org/
|
||||
[shields]: http://shields.io/
|
||||
[thechangelog]: http://5by5.tv/changelog/127
|
||||
[vandamme]: https://github.com/tech-angels/vandamme/
|
||||
@ -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,14 +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 'italiano [it-IT]', '/it-IT/', {rel: "alternate", lang: "it-IT", hreflang: "it-IT"}
|
||||
%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
|
||||
|
||||
@ -49,10 +44,9 @@
|
||||
%p.about
|
||||
#{link_to "Typed", "https://github.com/olivierlacan/keep-a-changelog/"}
|
||||
with trepidation by
|
||||
#{link_to "Olivier Lacan", "http://olivierlacan.com/"} from
|
||||
#{link_to "Code School", "https://www.codeschool.com/"}.
|
||||
#{link_to "Olivier Lacan", "http://olivierlacan.com/"}.
|
||||
|
||||
- unless gauges_id.blank?
|
||||
- unless config.gauges_id.blank?
|
||||
:javascript
|
||||
var _gauges = _gauges || [];
|
||||
(function() {
|
||||
@ -60,7 +54,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);
|
||||
@ -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*?
|
||||
@ -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
|
||||
### Для чего нужен лог изменений?
|
||||
187
source/sv/0.3.0/index.html.haml
Normal file
187
source/sv/0.3.0/index.html.haml
Normal 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/
|
||||
178
source/tr-TR/0.3.0/index.html.haml
Normal file
178
source/tr-TR/0.3.0/index.html.haml
Normal file
@ -0,0 +1,178 @@
|
||||
---
|
||||
description: Değişiklik kaydı tutun
|
||||
title: Değişiklik kaydı tutun
|
||||
language: tr-TR
|
||||
version: 0.3.0
|
||||
---
|
||||
|
||||
:markdown
|
||||
# CHANGELOG dosyası kullanın
|
||||
|
||||
## Arkadaşlarınızın git kayıtlarını CHANGELOG dosyalarına boşaltmasını engelleyin™
|
||||
|
||||
### Nedir bu değişiklik kayıtları?
|
||||
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")
|
||||
|
||||
: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.
|
||||
|
||||
### Neden umrumda olsun ki?
|
||||
Çünkü yazılım paketleri insanlar içindir. Eğer umrunuzda değilse neden açık kaynağa
|
||||
katkıda bulunuyorsunuz ki? Mutlaka sevimli beyninizin bir yerlerinde bunu önemseyen
|
||||
bir çekirdek (a-ha!) vardır.
|
||||
|
||||
[Adam Stacoviak ve Jerod Santo ile Changelog Podcast'inde][thechangelog](uyuyor,
|
||||
değil mi?) neden geliştiricilerin ve katılımcıların umrunda olması gerektiğini ve
|
||||
bu projenin arkasındaki motivasyonu konuştuk. Eğer vaktiniz varsa (1:06) iyi bir
|
||||
söyleşi oldu.
|
||||
|
||||
### Bir değişiklik kaydını iyi yapan nedir?
|
||||
Bunu sorduğunuza sevindim.
|
||||
|
||||
İyi bir değişiklik kaydı şu prensiplere bağlıdır:
|
||||
|
||||
- İnsanlar için yapılmıştır, makineler için değil, yani okunurluğu kritik.
|
||||
- Kolayca bölümler arası bağlantı kurulabilmeli (bu yüzden yalın metin yerine markdown).
|
||||
- Her sürüm için bir alt bölüm.
|
||||
- Dağıtımları tersine tarih sırası ile listeleyin (en yeni en üstte).
|
||||
- Tüm tarihleri `YYYY-AA-GG` biçiminde yazın. (Örneğin `2 Haziran 2012` için `2012-06-02`.) Uluslararasıdır, [anlamlıdır](http://xkcd.com/1179/), ve lisan bağımsızdır.
|
||||
- [Anlamsal sürümlemeyi][semver] destekleyip desteklemediğini özellikle belirtin.
|
||||
- Her sürümde olması gerekenler:
|
||||
- Üstteki biçimde dağıtım tarihi.
|
||||
- Projeye etkileri bakımından değişiklikleri gruplayın, şöyle ki:
|
||||
- `Eklendi`: yeni özellikler için.
|
||||
- `Değişti`: var olan beceriler değiştiyse.
|
||||
- `Rafa kalktı`: gelecekte yok olacak var olan beceriler.
|
||||
- `Kaldırıldı`: bu sürümde kaldırılan, daha önce rafa kaldırılmış olan beceriler.
|
||||
- `Düzeltildi`: ayıklanmış hatalar için.
|
||||
- `Güvenlik`: açıkları kapatabilmeleri için kullanıcıları bilgilendirin.
|
||||
|
||||
### Gerekli çabayı nasıl en aza indirebilirim?
|
||||
Her zaman en üstte değişiklikleri takip ettiğiniz bir `"Yayımlanmadı"` bölümü olsun.
|
||||
|
||||
Bu, iki amaca hizmet eder:
|
||||
|
||||
- İnsanlar gelecek sürümlerde karşılarına ne gibi değişiklikler çıkacağını görebilirler
|
||||
- Dağıtım zamanı geldiğinde `"Yayımlanmadı"` başlığını sürüm numarası ile değişitip
|
||||
tepeye yeni bir `"Yayımlanmadı"` bölümü eklemeniz yeterli.
|
||||
|
||||
### Tek boynuzlu atları ağlatan ne?
|
||||
Peki… Gelelim sadede.
|
||||
|
||||
- **Commit kayıtlarının farkını yüklemek.** Sakın bunu yapmayın, kimseye yardım etmiyorsunuz.
|
||||
- **Rafa kalkanları ön plana çıkarmamak.** Kullanıcılar bir sürümden diğerine
|
||||
yükseltme yaptıklarında neyin bozulabileceği apaçık ortada olmalı.
|
||||
- **Bölgesel biçimlenmiş tarihler.** ABD'de insanlar ay bilgisini önce kullanıyor
|
||||
("06-02-2012" demek 2 Haziran 2012 demek yani, ki tamamen *saçma*), diğer taraftan
|
||||
dünyanın bir çok bölgesinde "2 Haziran 2012" gibi robotik bir yapı kullanıp farklı
|
||||
şekilde dile getiriyor. "2012-06-02" hem mantıksal olarak en büyüğünden en küçüğüne çalışıyor,
|
||||
hem de diğer tarih biçimleriyle çakışmıyor. Aynı zamanda [ISO standardında](http://www.iso.org/iso/home/standards/iso8601.htm).
|
||||
Bu yüzden değişiklik kayıtları için önerilen tarih biçimidir.
|
||||
|
||||
Dahası da var. Bu tek boynuzlu at gözyaşlarını toplamak için
|
||||
[bir başlık açın][issues]
|
||||
ya da bir çekme isteği (pull request) gönderin.
|
||||
|
||||
### Standart bir değişiklik kaydı biçimi var mı?
|
||||
Ne yazık ki hayır. Sakin olun. Biliyorum, şu an alelacele GNU değişiklik kaydı
|
||||
stil rehberi için bağlantı arıyorsunuz, ya da iki paragraflık GNU NEWS dosyasına
|
||||
bakınıyorsunuz. GNU stil rehberi iyi bir başlangıç fakat üzücü derece naif.
|
||||
Naif olmakta yanlış bir şey yok, fakat insanlar rehberlik aradığında nadiren
|
||||
yardımcı oluyorlar. Özellikle ortada uğraşılacak bir çok durum ve uç örnekler
|
||||
mevcutken.
|
||||
|
||||
Bu proje [umuyorum ki daha iyi CHANGELOG dosyaları için bir altyapı oluşturacak][CHANGELOG].
|
||||
Mevcut durumun çok iyi olduğunu düşünmüyorum, ve topluluk olarak, gerçek yazılım
|
||||
projelerinden iyi pratikleri toplayarak bundan daha iyisini yapabiliriz. Lütfen
|
||||
etrafa bir göz gezdirin ve unutmayın [gelişme yolunda tartışmalara ve önerilere her zaman açığız][issues]!
|
||||
|
||||
### Değişiklik kayıtlarının dosya ismi ne olmalı?
|
||||
Eh, üstteki örnekten çıkartamadıysanız eğer, `CHANGELOG.md` şu ana kadarki
|
||||
en iyi çözüm.
|
||||
|
||||
Bazı projeler `HISTORY.txt`, `HISTORY.md`, `History.md`, `NEWS.txt`, `NEWS.md`,
|
||||
`News.txt`, `RELEASES.txt`, `RELEASE.md`, `releases.md` vb de kullanıyor.
|
||||
|
||||
Tam bir karmaşa. Tüm bu isimler insanların bu dosyayı bulmasını zorlaştırıyor.
|
||||
|
||||
### Neden `git log` farkları kullanılmasın?
|
||||
Çünkü kayıt farkları bir sürü gürültü içerir - doğal olarak. Mükemmel insanlar
|
||||
tarafından yürütülen, hiç yazım hatasının yapılmadığı, dosyaların gönderilmesinin
|
||||
hiç unutulmadığı, refaktör yapılmasının atlanmadığı varsayımsal bir projede bile
|
||||
uygun bir değişiklik kaydı oluşmayacaktır. Dosyaları repoya göndermenin amacı
|
||||
atomik seviyede kodun bir durumdan diğerine geçişinin sağlanmasıdır. Değişiklik
|
||||
kayıtları ise bu durumlar arasında, önem arz eden değişiklikleri belgelemeyi
|
||||
amaçlıyor.
|
||||
|
||||
İyi yorumlar ve kodun kendisi arasındaki fark,
|
||||
aynı şekilde değişiklik kayıtları ve commit kayıtları arasındaki gibidir:
|
||||
biri *neden* olduğunu, diğeri nasıl olduğunu açıklar.
|
||||
|
||||
### Değişiklik kayıtları otomatik olarak toplanabilir mi?
|
||||
Zor, çünkü insanlar bir çok farklı biçim ve dosya isimleri kullanıyorlar.
|
||||
|
||||
[Vandamme][vandamme], [Gemnasium][gemnasium] ekibi tarafından oluşturulmuş
|
||||
bir Ruby Gem'idir ve bir çok (hepsini değil) açık kaynaklı projenin değişiklik
|
||||
kayıtlarını ayrıştırabiliyor.
|
||||
|
||||
### Neden arada bir "CHANGELOG" ve arada bir "değişiklik kaydı" yazıyorsun?
|
||||
"CHANGELOG" dosyanın ismi. Biraz fazla şaşalı ama bir çok açık kaynak kodlu
|
||||
proje tarafından uygulanan tarihi bir gelenek. Benzer dosyalar da var;
|
||||
[`README`][README], [`LICENSE`][LICENSE], ve [`CONTRIBUTING`][CONTRIBUTING].
|
||||
|
||||
Büyük harfle isimlendirme (eski işletim sistemlerinde dosyaların tepede
|
||||
gözükmelerini sağlardı) dikkat çekmek için. Proje hakkında önemli meta verileri
|
||||
içerdikleri için, kullanmak ya da katkıda bulunmak isteyen herkesin işine
|
||||
yarar, tıpkı [açık kaynaklı proje rozeleri][shields] gibi.
|
||||
|
||||
"Değişiklik kaydı"ndan bahsettiğim zamanlar bu dosyanın işlevinden bahsediyorum:
|
||||
Değişiklikleri kaydetmek.
|
||||
|
||||
### Peki ya Geri çekilen dağıtımlar?
|
||||
Geri çekilen dağıtımlar, önemli hatalar ya da güvenlik sebepleri nedeniyle
|
||||
yayından geri çekilen sürümlerdir. Genelde bu sürümler değişiklik kayıtlarında
|
||||
görüntülenmezler. Görünmeliler. Tam da şu şekilde görünmeliler:
|
||||
|
||||
`## 0.0.5 - 2014-12-13 [GERİ ÇEKİLDİ]`
|
||||
|
||||
`[GERİ ÇEKİLDİ]` etiketi belirli bir sebepten büyük harf. İnsanların bunu fark
|
||||
etmeleri çok önemli. Ayrıca köşeli parantezler ile çevrelenmiş olması
|
||||
programatik olarak da ayrıştırılabilmeine olanak sağlıyor.
|
||||
|
||||
### Değişiklik kayıtlarınızı tekrar yazmalı mısınız?
|
||||
Tabii ki. Her zaman değişiklik kayıtlarını geliştirmek için iyi sebepler vardır.
|
||||
Düzenli olarak açık kaynaklı projelerde bakım yapılmayan değişiklik kayıtları
|
||||
için çekme istekleri yapıyorum.
|
||||
|
||||
Ayrıca bir sürümdeki notların arasında önemli bir değişiklikten bahsetmeyi
|
||||
unutmuş olduğunuzu fark edebilirsiniz. Değişiklik kayıtlarınızı bu bilgi ışığında
|
||||
güncellemeniz gerektiği gün gibi ortada.
|
||||
|
||||
### Nasıl katkıda bulunabilirim?
|
||||
Bu belge **doğrunun kendisi** değil; benim hesaplı görüşlerimdir. Beraberinde
|
||||
toparlamış olduğum bilgiler ve örnekler bulunur.
|
||||
[GitHub repo][gh]sunda güncel bir [CHANGELOG][] sağlıyor olsam da, özellikle
|
||||
bir *sürüm* ya da ([SemVer.org][semver] benzeri) takip edilecek kurallar
|
||||
oluşturmadım.
|
||||
|
||||
Bunu istememin sebebi topluluğun ortak bir paydada buluşmasını istememdir.
|
||||
İnanıyorum ki tartışmanın kendisi de sonucu kadar önemli.
|
||||
|
||||
Yani lütfen, [**siz de katılın**][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/
|
||||
@ -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
|
||||
### 为何要提供更新日志？
|
||||
@ -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
|
||||
### 為何要提供更新日誌？
|
||||
Loading…
x
Reference in New Issue
Block a user