mirror of
https://github.com/olivierlacan/keep-a-changelog.git
synced 2025-07-29 16:54:12 +02:00
Merge remote-tracking branch 'olivierlacan/master'
This commit is contained in:
Emre Erkan
commit
a42dc89796
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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/
|
||||
|
||||
25
config.rb
25
config.rb
@ -3,12 +3,33 @@
|
||||
# --------------------------------------
|
||||
|
||||
# ----- Site ----- #
|
||||
$last_version = "0.3.0"
|
||||
$languages = {
|
||||
de: "Deutsch",
|
||||
en: "English",
|
||||
"es-ES" => "Español",
|
||||
"pt-BR" => "Brazilian Portugese",
|
||||
ru: "Pyccкий",
|
||||
"zh-CN" => "简体中文",
|
||||
"zh-TW" => " 繁體中文",
|
||||
"sv" => "Svenska"
|
||||
}
|
||||
|
||||
activate :i18n,
|
||||
lang_map: $languages,
|
||||
mount_at_root: :en
|
||||
|
||||
activate :i18n, langs: [:en, 'es-ES', 'pt-BR', :ru, 'zh-CN', 'zh-TW'], :mount_at_root => :en
|
||||
set :gauges_id, ''
|
||||
set :publisher_url, 'https://www.facebook.com/olivier.lacan.5'
|
||||
set :site_url, 'http://keepachangelog.com'
|
||||
|
||||
redirect "index.html", to: "en/#{$last_version}/index.html"
|
||||
|
||||
$languages.each do |language|
|
||||
language_param = language.last.parameterize
|
||||
redirect "#{language.first}/index.html", to: "#{language.first}/#{$last_version}/index.html"
|
||||
end
|
||||
|
||||
# ----- Assets ----- #
|
||||
|
||||
set :css_dir, 'assets/stylesheets'
|
||||
@ -37,7 +58,7 @@ set :markdown, {
|
||||
|
||||
helpers do
|
||||
def path_to_url(path)
|
||||
Addressable::URI.join(site_url, path).normalize.to_s
|
||||
Addressable::URI.join(config.site_url, path).normalize.to_s
|
||||
end
|
||||
end
|
||||
|
||||
|
||||
@ -2,6 +2,7 @@
|
||||
description: Keep a Changelog
|
||||
title: Keep a Changelog
|
||||
language: de
|
||||
version: 0.3.0
|
||||
---
|
||||
|
||||
:markdown
|
||||
@ -9,15 +10,17 @@ 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?
|
||||
Es für Benutzer und Entwickler einfacher zu machen, die relevanten Änderungen, welche
|
||||
Es für Benutzer und Entwickler einfacher zu machen, die relevanten Änderungen, welche
|
||||
zwischen Releases (oder Versionen) des Projekts gemacht wurden, zu sehen.
|
||||
|
||||
### Warum sollte ich mich darum kümmern?
|
||||
@ -84,7 +87,7 @@ language: de
|
||||
Es ist sicher nichts falsch daran, naiv zu zu sein, aber beim Verfassen eines Leitfadens
|
||||
ist es nicht wirklich hilfreich. Vor allem nicht, wenn es viele Spezialfälle zu beachten gibt.
|
||||
|
||||
Dieses Projekt [enthält das, wovon ich hoffe, dass es zu einer besseren CHANGELOG-Datei-Konvention][CHANGELOG]
|
||||
Dieses Projekt [enthält das, wovon ich hoffe, dass es zu einer besseren CHANGELOG-Datei-Konvention][CHANGELOG]
|
||||
wird. Ich glaube nicht, dass der status quo gut genug ist, und ich denke, dass wir als Community
|
||||
eine bessere Konvention entwickeln können, wenn wir Bewährtes aus echten
|
||||
Software-Projekten entnehmen. Schau dich um und denk daran, dass
|
||||
@ -101,8 +104,8 @@ language: de
|
||||
|
||||
### Wieso sollte man nicht einfach ein `git log` Diff verwenden?
|
||||
Weil log Diffs voller unnötiger Information sind - von Natur aus. Sie wären nicht
|
||||
einmal ein geeignetes Changelog in einem hypothetischen Projekt, welches von perfekten
|
||||
Menschen geführt wird, welche sich niemals vertippen, niemals vergessen, neue Dateien
|
||||
einmal ein geeignetes Changelog in einem hypothetischen Projekt, welches von perfekten
|
||||
Menschen geführt wird, welche sich niemals vertippen, niemals vergessen, neue Dateien
|
||||
zu comitten und nie einen Teil eines Refactorings übersehen.
|
||||
Der Zweck eines Commits ist es, einen atomaren Schritt eines Prozesses zu dokumentieren,
|
||||
welcher den Code von einem Zustand in den nächsten bringt. Der Zweck eines Changelogs
|
||||
@ -127,7 +130,7 @@ language: de
|
||||
|
||||
Die Grossschreibung (welche in alten Betriebssystemen dafür gesorgt hat,
|
||||
dass die Dateien zuerst aufgelistet wurden) wird verwendet, um die Aufmerksamkeit
|
||||
auf diese Dateien zu lenken. Da sie wichtige Metadaten über das Projekt enthalten,
|
||||
auf diese Dateien zu lenken. Da sie wichtige Metadaten über das Projekt enthalten,
|
||||
können sie wichtig für jeden sein, der das Projekt gerne benutzen oder mitentwickeln
|
||||
möchte, ähnlich wie [Open-Source-Projekt-Badges][shields].
|
||||
|
||||
@ -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?
|
||||
@ -69,12 +72,12 @@ language: es-ES
|
||||
Pero espera! hay más ayúdame a coleccionar esas lágrimas de unicornio [abriendo una incidencia][issues] o haciendo un pull request.
|
||||
|
||||
### Hay algún formato estándar de formato para los change log?
|
||||
|
||||
|
||||
Tristemente, no. Pero calma. Sé que estás corriendo furiosamente intentando encontrar ese link al libro de estilo de registro de cambios de GNU, or the two-paragraph GNU NEWS file
|
||||
"guideline". La guía de estilo GNU es un buen comienzo, pero es tristemente cándida. No hay nada malo en ser cándida, pero cuando la gente necesita orientación es rara la vez, que resulta ser muy útil. Sobre todo, cuando hay muchas situaciones y casos muy específicos.
|
||||
|
||||
Este proyecto [contiene lo que espero se convierta en un mejor patrón de CHANGELOGs][CHANGELOG].
|
||||
|
||||
|
||||
No creo que la situación actual sea lo suficientemente buena, i creo que como comunidad que somos podemos llegar a mejores convenciones si tratamos de extraer buenas prácticas de proyectos de software reales. Por favor echa un pequeño vistazo y recuerda que las [sugerencias y discusiones para mejorar son bienvenidas][issues]!
|
||||
|
||||
### Cómo se debería llamar el change log?
|
||||
@ -89,7 +92,7 @@ language: es-ES
|
||||
### Por qué la gente no usa simplemente un `git log`?
|
||||
|
||||
Debido a que están llenos de ruido - por naturaleza. No se podría hacer un change log adecuado ni siquiera en un proyecto hipotético dirigido por seres humanos perfectos que nunca se equivocan y que nunca se olvidan meter ningún archivo en un commit... etc. El propósito de un commit es el de documentar un cambio atómico en el cual el software evoluciona desde un estado hacia otro. El propósito del change log es el de documentar las diferencias notables entre estos estados.
|
||||
|
||||
|
||||
### Se pueden parsear automáticamente los change logs?
|
||||
|
||||
Es difícil, ya que la gente sigue formatos y nombres de archivo muy distintos.
|
||||
@ -108,7 +111,7 @@ language: es-ES
|
||||
### Qué son las yanked releases?
|
||||
|
||||
Las yanked releases son versiones que tuvieron que ser retiradas a causa de un grave error o problema de seguridad. A menudo, estas versiones ni siquiera aparecen en los change logs, y tendrían que aparecer. Así es como se muestran:
|
||||
|
||||
|
||||
`## 0.0.5 - 2014-12-13 [YANKED]`
|
||||
|
||||
La sección `[YANKED]` va entre corchetes por una razón, es importante que destaque, y el echo de estar rodeado por corchetes lo hace más fácil de localizar programáticamente.
|
||||
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,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);
|
||||
@ -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
|
||||
### Для чего нужен лог изменений?
|
||||
@ -92,7 +95,7 @@ language: ru
|
||||
[стандартом ISO](http://www.iso.org/iso/home/standards/iso8601.htm). Таким
|
||||
образом, этот формат является рекомендуемым для логов изменений.
|
||||
|
||||
Существуют и другие. Помогите мне собрать слёзы единорогов,
|
||||
Существуют и другие. Помогите мне собрать слёзы единорогов,
|
||||
[открыв тикет][issues] или пулл-реквест.
|
||||
|
||||
### Существует стандарт формата лога изменений?
|
||||
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/
|
||||
@ -2,6 +2,7 @@
|
||||
description: 如何维护更新日志
|
||||
title: 如何维护更新日志
|
||||
language: zh-CN
|
||||
version: 0.3.0
|
||||
---
|
||||
|
||||
:markdown
|
||||
@ -9,21 +10,23 @@ 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
|
||||
### 为何要提供更新日志？
|
||||
为了让用户和开发人员更好知道每一个版本有哪些区别。
|
||||
|
||||
|
||||
### 为何我要在乎呢？
|
||||
因为归根结底软件是为人提供的。既然你不关心人，哪么为何写软件呢？
|
||||
多少你还是要关心你的受众。
|
||||
|
||||
|
||||
本文档原作者和另外两个人的一个[播客][thechangelog]向大家介绍了，
|
||||
为何代码的管理者和开发者应该在乎更新日志。如果你有一小时时间和很好的英文听力本领，
|
||||
不放听听。
|
||||
@ -32,7 +35,7 @@ language: zh-CN
|
||||
好问题！
|
||||
|
||||
一个好的更新日志，一定满足：
|
||||
|
||||
|
||||
- 给人而不是机器写的。记住，要说人话。
|
||||
- 快速跳转到任意段。所以采用markdown格式
|
||||
- 一个版本对应一个章节。
|
||||
@ -49,88 +52,88 @@ language: zh-CN
|
||||
- 'Removed' 之前不建议使用的功能，这次真的删掉了
|
||||
- 'Fixed' 改的bug
|
||||
- 'Security' 改的有关安全相关bug
|
||||
|
||||
|
||||
|
||||
|
||||
### 怎么尽可能减少耗费的精力？
|
||||
永远在文档最上方提供一个'Unreleased' 未发布区域，来记录当前的变化。
|
||||
这佯作有两大意义。
|
||||
|
||||
|
||||
- 大家可以看到接下来会有什么变化
|
||||
- 在发布时，只要把'Unreleased'改为当前版本号，然后再添加一个新的'Unreleased'就行了
|
||||
|
||||
|
||||
|
||||
### 吐槽环节到了
|
||||
请你一定要注意：
|
||||
|
||||
|
||||
- **把git日志扔到更新日志里。**看似有用，然并卵。
|
||||
- **不写'deprecations'就删功能。**不带这样坑队友的。
|
||||
- **采用各种不靠谱日期格式** 2012年12月12日，也就中国人能看懂了。
|
||||
|
||||
|
||||
如果你还有要吐槽的，欢迎留[issue][issues]或者直接PR
|
||||
|
||||
|
||||
|
||||
### 世界上不是有标准的更新日志格式吗？
|
||||
貌似GNU或者GNU NEWS还是提过些规范的，事实是它们太过简陋了。
|
||||
开发有那么多中情况，采用那样的规范，确实是不太合适的。
|
||||
|
||||
|
||||
这个项目提供的[规范][CHANGELOG]是作者本人希望能够成为世界规范的。
|
||||
作者不认为当前的标准足够好，而且作为一个社区，我们是有能力提供更棒的规范。
|
||||
如果你对这个规范有不满的地方，不要忘记还可以[吐槽][issues]呢。
|
||||
|
||||
|
||||
### 更新日志文件名应该叫什么？
|
||||
|
||||
我们的案例中给的名字就是最好的规范：`CHANGELOG.md`，注意大小写。
|
||||
|
||||
|
||||
像`HISTORY.txt`, `HISTORY.md`, `History.md`, `NEWS.txt`,
|
||||
`NEWS.md`, `News.txt`, `RELEASES.txt`, `RELEASE.md`, `releases.md`这么
|
||||
多文件名就太不统一了。
|
||||
|
||||
|
||||
只会让大家更难找到。
|
||||
|
||||
|
||||
### 为何不直接记录`git log`?
|
||||
|
||||
因为git日志一定是乱糟糟的。哪怕一个最理想的由完美的程序员开发的提交的，哪怕一个
|
||||
从不忘记每次提交全部文件，不写错别字，不忘记重构每一个部分——也无法保证git日志完美无瑕。
|
||||
况且git日志的核心在于记录代码的演化，而更新日志则是记录最重要的变更。
|
||||
|
||||
|
||||
就像注释之于代码，更新日志之于git日志。前者解释*为什么*，而后者说明*发生了什么*。
|
||||
|
||||
|
||||
### 更新日志能机器识别吗？
|
||||
非常困难，因为有各种不同的文件格式和其他规范。
|
||||
|
||||
|
||||
[Vandamme][vandamme]是一个Ruby程序（由[Gemnasium][gemnasium]团队制作），可以解析
|
||||
好多种（但绝对不是全部）开源库的更新日志。
|
||||
|
||||
|
||||
### 到底是CHANGELOG还是更新日志
|
||||
|
||||
|
||||
CHANGELOG是文件名，更新日志是常用说法。CHANGELOG采用大写是有历史根源的。就像很多类似的文件
|
||||
[`README`][README]， [`LICENSE`][LICENSE]，还有[`CONTRIBUTING`][CONTRIBUTING]。
|
||||
|
||||
|
||||
采用大写可以更加显著，毕竟这是项目很重要的元信息。就像[开源徽章][shields]。
|
||||
|
||||
|
||||
### 那些后来撤下的版本怎么办？
|
||||
因为各种安全/重大bug原因被撤下的版本被标记'YANKED'。这些版本一般不出现在更新日志里，但作者建议他们出现。
|
||||
显示方式应该是：
|
||||
|
||||
|
||||
`## 0.0.5 - 2014-12-13 [YANKED]`
|
||||
|
||||
|
||||
`[YANKED]`采用大写更加显著，因为这个信息很重要。而采用方括号则容易被程序解析。
|
||||
|
||||
|
||||
### 是否可以重写更新日志
|
||||
当然。哪怕已经上线了，也可以重新更新更新日志。有许多开源项目更新日志不够新，所以作者就会帮忙更新。
|
||||
|
||||
|
||||
另外，很有可能你忘记记录一个重大功能更新。所以这时候应该去重写更新日志。
|
||||
|
||||
|
||||
### 如何贡献？
|
||||
本文档并不是**真理**。这只是原作者的个人建议，并且包括许多收集的例子。
|
||||
哪怕[本开源库][gh]提供一个[更新日志案例][CHANGELOG]，我刻意没有提供一个
|
||||
过于苛刻的规则列表（不像[语义化版本格式][semver]）。
|
||||
|
||||
|
||||
这是因为我希望通过社区达到统一观点，我认为中间讨论的过程与结果一样重要。
|
||||
|
||||
|
||||
所以[欢迎贡献][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
|
||||
@ -2,6 +2,7 @@
|
||||
description: 如何維護更新日誌
|
||||
title: 如何維護更新日誌
|
||||
language: zh-TW
|
||||
version: 0.3.0
|
||||
---
|
||||
|
||||
:markdown
|
||||
@ -9,21 +10,23 @@ 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
|
||||
### 為何要提供更新日誌？
|
||||
為了讓用戶和開發人員更好知道每壹個版本有哪些區別。
|
||||
|
||||
|
||||
### 為何我要在乎呢？
|
||||
因為歸根結底軟件是為人提供的。既然妳不關心人，哪麽為何寫軟件呢？
|
||||
多少妳還是要關心妳的受眾。
|
||||
|
||||
|
||||
本文檔原作者和另外兩個人的壹個[播客][thechangelog]向大家介紹了，
|
||||
為何代碼的管理者和開發者應該在乎更新日誌。如果妳有壹小時時間和很好的英文聽力本領，
|
||||
不放聽聽。
|
||||
@ -32,7 +35,7 @@ language: zh-TW
|
||||
好問題！
|
||||
|
||||
壹個好的更新日誌，壹定滿足：
|
||||
|
||||
|
||||
- 給人而不是機器寫的。記住，要說人話。
|
||||
- 快速跳轉到任意段。所以采用markdown格式
|
||||
- 壹個版本對應壹個章節。
|
||||
@ -49,88 +52,88 @@ language: zh-TW
|
||||
- 'Removed' 之前不建議使用的功能，這次真的刪掉了
|
||||
- 'Fixed' 改的bug
|
||||
- 'Security' 改的有關安全相關bug
|
||||
|
||||
|
||||
|
||||
|
||||
### 怎麽盡可能減少耗費的精力？
|
||||
永遠在文檔最上方提供壹個'Unreleased' 未發布區域，來記錄當前的變化。
|
||||
這佯作有兩大意義。
|
||||
|
||||
|
||||
- 大家可以看到接下來會有什麽變化
|
||||
- 在發布時，只要把'Unreleased'改為當前版本號，然後再添加壹個新的'Unreleased'就行了
|
||||
|
||||
|
||||
|
||||
### 吐槽環節到了
|
||||
請妳壹定要註意：
|
||||
|
||||
|
||||
- **把git日誌扔到更新日誌裏。**看似有用，然並卵。
|
||||
- **不寫'deprecations'就刪功能。**不帶這樣坑隊友的。
|
||||
- **采用各種不靠譜日期格式** 2012年12月12日，也就中國人能看懂了。
|
||||
|
||||
|
||||
如果妳還有要吐槽的，歡迎留[issue][issues]或者直接PR
|
||||
|
||||
|
||||
|
||||
### 世界上不是有標準的更新日誌格式嗎？
|
||||
貌似GNU或者GNU NEWS還是提過些規範的，事實是它們太過簡陋了。
|
||||
開發有那麽多中情況，采用那樣的規範，確實是不太合適的。
|
||||
|
||||
|
||||
這個項目提供的[規範][CHANGELOG]是作者本人希望能夠成為世界規範的。
|
||||
作者不認為當前的標準足夠好，而且作為壹個社區，我們是有能力提供更棒的規範。
|
||||
如果妳對這個規範有不滿的地方，不要忘記還可以[吐槽][issues]呢。
|
||||
|
||||
|
||||
### 更新日誌文件名應該叫什麽？
|
||||
|
||||
我們的案例中給的名字就是最好的規範：`CHANGELOG.md`，註意大小寫。
|
||||
|
||||
|
||||
像`HISTORY.txt`, `HISTORY.md`, `History.md`, `NEWS.txt`,
|
||||
`NEWS.md`, `News.txt`, `RELEASES.txt`, `RELEASE.md`, `releases.md`這麽
|
||||
多文件名就太不統壹了。
|
||||
|
||||
|
||||
只會讓大家更難找到。
|
||||
|
||||
|
||||
### 為何不直接記錄`git log`?
|
||||
|
||||
因為git日誌壹定是亂糟糟的。哪怕壹個最理想的由完美的程序員開發的提交的，哪怕壹個
|
||||
從不忘記每次提交全部文件，不寫錯別字，不忘記重構每壹個部分——也無法保證git日誌完美無瑕。
|
||||
況且git日誌的核心在於記錄代碼的演化，而更新日誌則是記錄最重要的變更。
|
||||
|
||||
|
||||
就像註釋之於代碼，更新日誌之於git日誌。前者解釋*為什麽*，而後者說明*發生了什麽*。
|
||||
|
||||
|
||||
### 更新日誌能機器識別嗎？
|
||||
非常困難，因為有各種不同的文件格式和其他規範。
|
||||
|
||||
|
||||
[Vandamme][vandamme]是壹個Ruby程序（由[Gemnasium][gemnasium]團隊制作），可以解析
|
||||
好多種（但絕對不是全部）開源庫的更新日誌。
|
||||
|
||||
|
||||
### 到底是CHANGELOG還是更新日誌
|
||||
|
||||
|
||||
CHANGELOG是文件名，更新日誌是常用說法。CHANGELOG采用大寫是有歷史根源的。就像很多類似的文件
|
||||
[`README`][README]， [`LICENSE`][LICENSE]，還有[`CONTRIBUTING`][CONTRIBUTING]。
|
||||
|
||||
|
||||
采用大寫可以更加顯著，畢竟這是項目很重要的元信息。就像[開源徽章][shields]。
|
||||
|
||||
|
||||
### 那些後來撤下的版本怎麽辦？
|
||||
因為各種安全/重大bug原因被撤下的版本被標記'YANKED'。這些版本壹般不出現在更新日誌裏，但作者建議他們出現。
|
||||
顯示方式應該是：
|
||||
|
||||
|
||||
`## 0.0.5 - 2014-12-13 [YANKED]`
|
||||
|
||||
|
||||
`[YANKED]`采用大寫更加顯著，因為這個信息很重要。而采用方括號則容易被程序解析。
|
||||
|
||||
|
||||
### 是否可以重寫更新日誌
|
||||
當然。哪怕已經上線了，也可以重新更新更新日誌。有許多開源項目更新日誌不夠新，所以作者就會幫忙更新。
|
||||
|
||||
|
||||
另外，很有可能妳忘記記錄壹個重大功能更新。所以這時候應該去重寫更新日誌。
|
||||
|
||||
|
||||
### 如何貢獻？
|
||||
本文檔並不是**真理**。這只是原作者的個人建議，並且包括許多收集的例子。
|
||||
哪怕[本開源庫][gh]提供壹個[更新日誌案例][CHANGELOG]，我刻意沒有提供壹個
|
||||
過於苛刻的規則列表（不像[語義化版本格式][semver]）。
|
||||
|
||||
|
||||
這是因為我希望通過社區達到統壹觀點，我認為中間討論的過程與結果壹樣重要。
|
||||
|
||||
|
||||
所以[歡迎貢獻][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
|
||||
Loading…
x
Reference in New Issue
Block a user