Convert static files to a Middleman app.
This commit is contained in:
Nathaniel Bibler
commit
8692eade4d
|
|
@ -0,0 +1,16 @@
|
|||
# EditorConfig is awesome: http://EditorConfig.org
|
||||
#
|
||||
# All EditorConfig properties:
|
||||
# https://github.com/editorconfig/editorconfig/wiki/EditorConfig-Properties
|
||||
|
||||
|
||||
# Top-most EditorConfig file
|
||||
root = true
|
||||
|
||||
# This is a small project; currently, we
|
||||
# use the same settings everywhere
|
||||
[*]
|
||||
end_of_line = lf
|
||||
insert_final_newline = true
|
||||
indent_style = space
|
||||
indent_size = 2
|
||||
|
|
@ -0,0 +1,5 @@
|
|||
.DS_Store
|
||||
/.bundle
|
||||
/.cache
|
||||
/.sass-cache
|
||||
/build
|
||||
|
|
@ -0,0 +1 @@
|
|||
2.2.3
|
||||
|
|
@ -0,0 +1,91 @@
|
|||
# Change Log
|
||||
All notable changes to this project will be documented in this file.
|
||||
This project adheres to [Semantic Versioning](http://semver.org/).
|
||||
|
||||
## [Unreleased]
|
||||
|
||||
## [0.2.0] - 2015-10-06
|
||||
### Changed
|
||||
- Remove exclusionary mentions of "open source" since this project can benefit
|
||||
both "open" and "closed" source projects equally.
|
||||
|
||||
## [0.1.0] - 2015-10-06
|
||||
### Added
|
||||
- Answer "Should you ever rewrite a change log?".
|
||||
|
||||
### Changed
|
||||
- Improve argument against commit logs.
|
||||
- Start following [SemVer](http://semver.org) properly.
|
||||
|
||||
## [0.0.8] - 2015-02-17
|
||||
### Changed
|
||||
- Update year to match in every README example.
|
||||
- Reluctantly stop making fun of Brits only, since most of the world
|
||||
writes dates in a strange way.
|
||||
|
||||
### Fixed
|
||||
- Fix typos in recent README changes.
|
||||
- Update outdated unreleased diff link.
|
||||
|
||||
## [0.0.7] - 2015-02-16
|
||||
### Added
|
||||
- Link, and make it obvious that date format is ISO 8601.
|
||||
|
||||
### Changed
|
||||
- Clarified the section on "Is there a standard change log format?".
|
||||
|
||||
### Fixed
|
||||
- Fix Markdown links to tag comparison URL with footnote-style links.
|
||||
|
||||
## [0.0.6] - 2014-12-12
|
||||
### Added
|
||||
- README section on "yanked" releases.
|
||||
|
||||
## [0.0.5] - 2014-08-09
|
||||
### Added
|
||||
- Markdown links to version tags on release headings.
|
||||
- Unreleased section to gather unreleased changes and encourage note
|
||||
keeping prior to releases.
|
||||
|
||||
## [0.0.4] - 2014-08-09
|
||||
### Added
|
||||
- Better explanation of the difference between the file ("CHANGELOG")
|
||||
and its function "the change log".
|
||||
|
||||
### Changed
|
||||
- Refer to a "change log" instead of a "CHANGELOG" throughout the site
|
||||
to differentiate between the file and the purpose of the file — the
|
||||
logging of changes.
|
||||
|
||||
### Removed
|
||||
- Remove empty sections from CHANGELOG, they occupy too much space and
|
||||
create too much noise in the file. People will have to assume that the
|
||||
missing sections were intentionally left out because they contained no
|
||||
notable changes.
|
||||
|
||||
## [0.0.3] - 2014-08-09
|
||||
### Added
|
||||
- "Why should I care?" section mentioning The Changelog podcast.
|
||||
|
||||
## [0.0.2] - 2014-07-10
|
||||
### Added
|
||||
- Explanation of the recommended reverse chronological release ordering.
|
||||
|
||||
## 0.0.1 - 2014-05-31
|
||||
### Added
|
||||
- This CHANGELOG file to hopefully serve as an evolving example of a standardized open source project CHANGELOG.
|
||||
- CNAME file to enable GitHub Pages custom domain
|
||||
- README now contains answers to common questions about CHANGELOGs
|
||||
- Good examples and basic guidelines, including proper date formatting.
|
||||
- Counter-examples: "What makes unicorns cry?"
|
||||
|
||||
[Unreleased]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.2.0...HEAD
|
||||
[0.2.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.1.0...v0.2.0
|
||||
[0.1.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.8...v0.1.0
|
||||
[0.0.8]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.7...v0.0.8
|
||||
[0.0.7]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.6...v0.0.7
|
||||
[0.0.6]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.5...v0.0.6
|
||||
[0.0.5]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.4...v0.0.5
|
||||
[0.0.4]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.3...v0.0.4
|
||||
[0.0.3]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.2...v0.0.3
|
||||
[0.0.2]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.1...v0.0.2
|
||||
|
|
@ -0,0 +1,14 @@
|
|||
Hi there,
|
||||
|
||||
Please open a pull request with any suggestions you have regarding the
|
||||
example [CHANGELOG](CHANGELOG.md) or the [README](README.md).
|
||||
|
||||
|
||||
Don't edit the [`index.html`](index.html) manually. Instead:
|
||||
|
||||
1. make changes to [README](README.md) if necessary
|
||||
2. run [`generate.thor`](generate.thor) with `thor generate index`.
|
||||
3. add the `README.md` and `index.html` changes to a Pull Request.
|
||||
|
||||
Tweaks, fixes and improvements to any of the [assets](assets/) are also
|
||||
quite welcome.
|
||||
|
|
@ -0,0 +1,13 @@
|
|||
source "https://rubygems.org"
|
||||
|
||||
gem "addressable"
|
||||
gem "middleman", "~>3.4.0"
|
||||
gem "middleman-autoprefixer"
|
||||
gem "middleman-blog"
|
||||
gem "middleman-livereload"
|
||||
gem "middleman-minify-html"
|
||||
gem "middleman-syntax"
|
||||
gem 'middleman-gh-pages'
|
||||
gem 'middleman-imageoptim'
|
||||
|
||||
gem "redcarpet"
|
||||
|
|
@ -0,0 +1,184 @@
|
|||
GEM
|
||||
remote: https://rubygems.org/
|
||||
specs:
|
||||
activesupport (4.2.4)
|
||||
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)
|
||||
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)
|
||||
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)
|
||||
compass-import-once (1.0.5)
|
||||
sass (>= 3.2, < 3.5)
|
||||
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)
|
||||
exifr (1.2.3.1)
|
||||
ffi (1.9.10)
|
||||
fspath (2.1.1)
|
||||
haml (4.0.7)
|
||||
tilt
|
||||
hike (1.2.3)
|
||||
hooks (0.4.1)
|
||||
uber (~> 0.0.14)
|
||||
htmlcompressor (0.2.0)
|
||||
http_parser.rb (0.6.0)
|
||||
i18n (0.7.0)
|
||||
image_optim (0.20.2)
|
||||
exifr (~> 1.1, >= 1.1.3)
|
||||
fspath (~> 2.1)
|
||||
image_size (~> 1.3)
|
||||
in_threads (~> 1.3)
|
||||
progress (~> 3.0, >= 3.0.1)
|
||||
image_optim_pack (0.2.1.20151002)
|
||||
fspath (~> 2.1)
|
||||
image_optim (~> 0.19)
|
||||
image_size (1.4.1)
|
||||
in_threads (1.3.1)
|
||||
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)
|
||||
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)
|
||||
sass (>= 3.4.0, < 4.0)
|
||||
uglifier (~> 2.5)
|
||||
middleman-autoprefixer (2.6.1)
|
||||
autoprefixer-rails (~> 6.0.1)
|
||||
middleman-core (>= 3.3.3)
|
||||
middleman-blog (3.5.3)
|
||||
addressable (~> 2.3.5)
|
||||
middleman-core (~> 3.2)
|
||||
tzinfo (>= 0.3.0)
|
||||
middleman-core (3.4.0)
|
||||
activesupport (~> 4.1)
|
||||
bundler (~> 1.1)
|
||||
capybara (~> 2.4.4)
|
||||
erubis
|
||||
hooks (~> 0.3)
|
||||
i18n (~> 0.7.0)
|
||||
listen (~> 3.0.3)
|
||||
padrino-helpers (~> 0.12.3)
|
||||
rack (>= 1.4.5, < 2.0)
|
||||
thor (>= 0.15.2, < 2.0)
|
||||
tilt (~> 1.4.1, < 2.0)
|
||||
middleman-gh-pages (0.0.3)
|
||||
rake (> 0.9.3)
|
||||
middleman-imageoptim (0.2.1)
|
||||
image_optim (~> 0.20.2)
|
||||
image_optim_pack (~> 0.2.1)
|
||||
middleman-core (>= 3.1)
|
||||
middleman-livereload (3.4.3)
|
||||
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)
|
||||
i18n (~> 0.6, >= 0.6.7)
|
||||
padrino-support (= 0.12.5)
|
||||
tilt (~> 1.4.1)
|
||||
padrino-support (0.12.5)
|
||||
activesupport (>= 3.1)
|
||||
progress (3.1.0)
|
||||
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)
|
||||
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)
|
||||
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)
|
||||
|
||||
PLATFORMS
|
||||
ruby
|
||||
|
||||
DEPENDENCIES
|
||||
addressable
|
||||
middleman (~> 3.4.0)
|
||||
middleman-autoprefixer
|
||||
middleman-blog
|
||||
middleman-gh-pages
|
||||
middleman-imageoptim
|
||||
middleman-livereload
|
||||
middleman-minify-html
|
||||
middleman-syntax
|
||||
redcarpet
|
||||
|
||||
BUNDLED WITH
|
||||
1.10.6
|
||||
|
|
@ -0,0 +1,21 @@
|
|||
The MIT License (MIT)
|
||||
|
||||
Copyright (c) 2014 Olivier Lacan
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
|
|
@ -0,0 +1,169 @@
|
|||
# Keep a CHANGELOG
|
||||
|
||||
## 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.
|
||||
|
||||
<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>
|
||||
|
||||
### 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.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].
|
||||
|
||||
[CHANGELOG]: ./CHANGELOG.md
|
||||
[gemnasium]: http://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/
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
require "middleman-gh-pages"
|
||||
|
||||
desc "Build and publish to GitHub Pages"
|
||||
task :deploy => :publish
|
||||
|
|
@ -0,0 +1,88 @@
|
|||
# --------------------------------------
|
||||
# Config
|
||||
# --------------------------------------
|
||||
|
||||
# ----- Site ----- #
|
||||
|
||||
activate :i18n, langs: [:en, :fr], :mount_at_root => :en
|
||||
set :gauges_id, ''
|
||||
set :publisher_url, 'https://www.facebook.com/olivier.lacan.5'
|
||||
set :site_url, 'http://keepachangelog.com'
|
||||
|
||||
# ----- Assets ----- #
|
||||
|
||||
set :css_dir, 'assets/stylesheets'
|
||||
set :js_dir, 'assets/javascripts'
|
||||
set :images_dir, 'assets/images'
|
||||
set :fonts_dir, 'assets/fonts'
|
||||
|
||||
# ----- Images ----- #
|
||||
|
||||
activate :automatic_image_sizes
|
||||
|
||||
# ----- Markdown ----- #
|
||||
|
||||
activate :syntax
|
||||
set :markdown_engine, :redcarpet
|
||||
set :markdown, {
|
||||
fenced_code_blocks: true,
|
||||
footnotes: true,
|
||||
smartypants: true,
|
||||
tables: true
|
||||
}
|
||||
|
||||
# --------------------------------------
|
||||
# Helpers
|
||||
# --------------------------------------
|
||||
|
||||
helpers do
|
||||
def path_to_url(path)
|
||||
Addressable::URI.join(site_url, path).normalize.to_s
|
||||
end
|
||||
end
|
||||
|
||||
# --------------------------------------
|
||||
# Content
|
||||
# --------------------------------------
|
||||
|
||||
# ----- Directories ----- #
|
||||
|
||||
activate :directory_indexes
|
||||
page "/404.html", directory_index: false
|
||||
|
||||
# --------------------------------------
|
||||
# Production
|
||||
# --------------------------------------
|
||||
|
||||
# ----- Optimization ----- #
|
||||
|
||||
configure :build do
|
||||
set :gauges_id, "5389808eeddd5b055a00440d"
|
||||
activate :gzip, {exts: %w[
|
||||
.css
|
||||
.eot
|
||||
.htm
|
||||
.html
|
||||
.ico
|
||||
.js
|
||||
.json
|
||||
.svg
|
||||
.ttf
|
||||
.txt
|
||||
.woff
|
||||
]}
|
||||
set :haml, {ugly: true, attr_wrapper: '"'}
|
||||
activate :imageoptim
|
||||
activate :minify_css
|
||||
activate :minify_html do |html|
|
||||
html.remove_quotes = false
|
||||
end
|
||||
activate :minify_javascript
|
||||
end
|
||||
|
||||
# ----- Prefixing ----- #
|
||||
|
||||
activate :autoprefixer do |config|
|
||||
config.browsers = ['last 2 versions', 'Explorer >= 10']
|
||||
config.cascade = false
|
||||
end
|
||||
|
|
@ -0,0 +1 @@
|
|||
//= require_tree .
|
||||
|
|
@ -0,0 +1,109 @@
|
|||
html
|
||||
font: 14px/1.4 "jaf-bernino-sans", "Helvetica Neue", Helvetica, Arial, sans-serif
|
||||
color: #333
|
||||
|
||||
a
|
||||
color: #E10FCE
|
||||
font-weight: bold
|
||||
text-decoration: none
|
||||
|
||||
a:hover
|
||||
text-decoration: underline
|
||||
|
||||
h1
|
||||
color: #C647BF
|
||||
font-size: 3.8em
|
||||
font-weight: bold
|
||||
font-family: "source-code-pro", monospace
|
||||
margin-bottom: 0
|
||||
line-height: 1
|
||||
|
||||
h2
|
||||
margin-top: 0
|
||||
margin-bottom: 2em
|
||||
|
||||
h1, h2
|
||||
text-align: center
|
||||
|
||||
h3
|
||||
font-size: 1.3em
|
||||
font-family: "source-code-pro", monospace
|
||||
margin-bottom: 0
|
||||
position: relative
|
||||
padding-left: .1em
|
||||
|
||||
h3:hover .anchor, h3:focus .anchor
|
||||
display: block
|
||||
|
||||
.anchor
|
||||
display: none
|
||||
font-style: normal
|
||||
font-weight: normal
|
||||
position: absolute
|
||||
right: 100%
|
||||
top: 0
|
||||
|
||||
.anchor::before
|
||||
content: '¶'
|
||||
|
||||
.anchor:hover
|
||||
text-decoration: none
|
||||
|
||||
h3 ~ p
|
||||
margin-top: 0
|
||||
|
||||
article
|
||||
margin: 0 auto
|
||||
width: 640px
|
||||
|
||||
article p
|
||||
font-size: 1.3em
|
||||
|
||||
article code
|
||||
border-radius: 0.315em
|
||||
border: 1px solid #ccc
|
||||
padding: 0 0.3em 0.040em
|
||||
font-size: 0.9em
|
||||
|
||||
article img
|
||||
margin: 0 auto
|
||||
max-width: 100%
|
||||
text-align: center
|
||||
display: block
|
||||
box-shadow: rgba(0, 0, 0, 0.37) 0px 0px 6px
|
||||
border-radius: 7px
|
||||
padding: 0.4em 0.9em
|
||||
|
||||
article > ul
|
||||
font-size: 1.2em
|
||||
padding-left: 0
|
||||
|
||||
article > ul ul
|
||||
padding-left: 1em
|
||||
|
||||
article ul
|
||||
line-height: 1.5
|
||||
list-style-position: inside
|
||||
list-style-type: square
|
||||
|
||||
footer
|
||||
font-size: .7em
|
||||
border-top: 1px solid #e9e6e1
|
||||
margin-top: 1em
|
||||
margin-bottom: 2em
|
||||
padding-top: 1em
|
||||
|
||||
.license
|
||||
float: left
|
||||
|
||||
.about
|
||||
float: right
|
||||
|
||||
.about, .license
|
||||
margin-top: 0
|
||||
|
||||
.changelog
|
||||
border: 1px solid #aaa
|
||||
margin: 0 0.5em
|
||||
padding: 1em
|
||||
overflow-x: auto
|
||||
|
|
@ -0,0 +1,425 @@
|
|||
/*! normalize.css v3.0.1 | MIT License | git.io/normalize */
|
||||
|
||||
/**
|
||||
* 1. Set default font family to sans-serif.
|
||||
* 2. Prevent iOS text size adjust after orientation change, without disabling
|
||||
* user zoom.
|
||||
*/
|
||||
|
||||
html {
|
||||
font-family: sans-serif; /* 1 */
|
||||
-ms-text-size-adjust: 100%; /* 2 */
|
||||
-webkit-text-size-adjust: 100%; /* 2 */
|
||||
}
|
||||
|
||||
/**
|
||||
* Remove default margin.
|
||||
*/
|
||||
|
||||
body {
|
||||
margin: 0;
|
||||
}
|
||||
|
||||
/* HTML5 display definitions
|
||||
========================================================================== */
|
||||
|
||||
/**
|
||||
* Correct `block` display not defined for any HTML5 element in IE 8/9.
|
||||
* Correct `block` display not defined for `details` or `summary` in IE 10/11 and Firefox.
|
||||
* Correct `block` display not defined for `main` in IE 11.
|
||||
*/
|
||||
|
||||
article,
|
||||
aside,
|
||||
details,
|
||||
figcaption,
|
||||
figure,
|
||||
footer,
|
||||
header,
|
||||
hgroup,
|
||||
main,
|
||||
nav,
|
||||
section,
|
||||
summary {
|
||||
display: block;
|
||||
}
|
||||
|
||||
/**
|
||||
* 1. Correct `inline-block` display not defined in IE 8/9.
|
||||
* 2. Normalize vertical alignment of `progress` in Chrome, Firefox, and Opera.
|
||||
*/
|
||||
|
||||
audio,
|
||||
canvas,
|
||||
progress,
|
||||
video {
|
||||
display: inline-block; /* 1 */
|
||||
vertical-align: baseline; /* 2 */
|
||||
}
|
||||
|
||||
/**
|
||||
* Prevent modern browsers from displaying `audio` without controls.
|
||||
* Remove excess height in iOS 5 devices.
|
||||
*/
|
||||
|
||||
audio:not([controls]) {
|
||||
display: none;
|
||||
height: 0;
|
||||
}
|
||||
|
||||
/**
|
||||
* Address `[hidden]` styling not present in IE 8/9/10.
|
||||
* Hide the `template` element in IE 8/9/11, Safari, and Firefox < 22.
|
||||
*/
|
||||
|
||||
[hidden],
|
||||
template {
|
||||
display: none;
|
||||
}
|
||||
|
||||
/* Links
|
||||
========================================================================== */
|
||||
|
||||
/**
|
||||
* Remove the gray background color from active links in IE 10.
|
||||
*/
|
||||
|
||||
a {
|
||||
background: transparent;
|
||||
}
|
||||
|
||||
/**
|
||||
* Improve readability when focused and also mouse hovered in all browsers.
|
||||
*/
|
||||
|
||||
a:active,
|
||||
a:hover {
|
||||
outline: 0;
|
||||
}
|
||||
|
||||
/* Text-level semantics
|
||||
========================================================================== */
|
||||
|
||||
/**
|
||||
* Address styling not present in IE 8/9/10/11, Safari, and Chrome.
|
||||
*/
|
||||
|
||||
abbr[title] {
|
||||
border-bottom: 1px dotted;
|
||||
}
|
||||
|
||||
/**
|
||||
* Address style set to `bolder` in Firefox 4+, Safari, and Chrome.
|
||||
*/
|
||||
|
||||
b,
|
||||
strong {
|
||||
font-weight: bold;
|
||||
}
|
||||
|
||||
/**
|
||||
* Address styling not present in Safari and Chrome.
|
||||
*/
|
||||
|
||||
dfn {
|
||||
font-style: italic;
|
||||
}
|
||||
|
||||
/**
|
||||
* Address variable `h1` font-size and margin within `section` and `article`
|
||||
* contexts in Firefox 4+, Safari, and Chrome.
|
||||
*/
|
||||
|
||||
h1 {
|
||||
font-size: 2em;
|
||||
margin: 0.67em 0;
|
||||
}
|
||||
|
||||
/**
|
||||
* Address styling not present in IE 8/9.
|
||||
*/
|
||||
|
||||
mark {
|
||||
background: #ff0;
|
||||
color: #000;
|
||||
}
|
||||
|
||||
/**
|
||||
* Address inconsistent and variable font size in all browsers.
|
||||
*/
|
||||
|
||||
small {
|
||||
font-size: 80%;
|
||||
}
|
||||
|
||||
/**
|
||||
* Prevent `sub` and `sup` affecting `line-height` in all browsers.
|
||||
*/
|
||||
|
||||
sub,
|
||||
sup {
|
||||
font-size: 75%;
|
||||
line-height: 0;
|
||||
position: relative;
|
||||
vertical-align: baseline;
|
||||
}
|
||||
|
||||
sup {
|
||||
top: -0.5em;
|
||||
}
|
||||
|
||||
sub {
|
||||
bottom: -0.25em;
|
||||
}
|
||||
|
||||
/* Embedded content
|
||||
========================================================================== */
|
||||
|
||||
/**
|
||||
* Remove border when inside `a` element in IE 8/9/10.
|
||||
*/
|
||||
|
||||
img {
|
||||
border: 0;
|
||||
}
|
||||
|
||||
/**
|
||||
* Correct overflow not hidden in IE 9/10/11.
|
||||
*/
|
||||
|
||||
svg:not(:root) {
|
||||
overflow: hidden;
|
||||
}
|
||||
|
||||
/* Grouping content
|
||||
========================================================================== */
|
||||
|
||||
/**
|
||||
* Address margin not present in IE 8/9 and Safari.
|
||||
*/
|
||||
|
||||
figure {
|
||||
margin: 1em 40px;
|
||||
}
|
||||
|
||||
/**
|
||||
* Address differences between Firefox and other browsers.
|
||||
*/
|
||||
|
||||
hr {
|
||||
-moz-box-sizing: content-box;
|
||||
box-sizing: content-box;
|
||||
height: 0;
|
||||
}
|
||||
|
||||
/**
|
||||
* Contain overflow in all browsers.
|
||||
*/
|
||||
|
||||
pre {
|
||||
overflow: auto;
|
||||
}
|
||||
|
||||
/**
|
||||
* Address odd `em`-unit font size rendering in all browsers.
|
||||
*/
|
||||
|
||||
code,
|
||||
kbd,
|
||||
pre,
|
||||
samp {
|
||||
font-family: monospace, monospace;
|
||||
font-size: 1em;
|
||||
}
|
||||
|
||||
/* Forms
|
||||
========================================================================== */
|
||||
|
||||
/**
|
||||
* Known limitation: by default, Chrome and Safari on OS X allow very limited
|
||||
* styling of `select`, unless a `border` property is set.
|
||||
*/
|
||||
|
||||
/**
|
||||
* 1. Correct color not being inherited.
|
||||
* Known issue: affects color of disabled elements.
|
||||
* 2. Correct font properties not being inherited.
|
||||
* 3. Address margins set differently in Firefox 4+, Safari, and Chrome.
|
||||
*/
|
||||
|
||||
button,
|
||||
input,
|
||||
optgroup,
|
||||
select,
|
||||
textarea {
|
||||
color: inherit; /* 1 */
|
||||
font: inherit; /* 2 */
|
||||
margin: 0; /* 3 */
|
||||
}
|
||||
|
||||
/**
|
||||
* Address `overflow` set to `hidden` in IE 8/9/10/11.
|
||||
*/
|
||||
|
||||
button {
|
||||
overflow: visible;
|
||||
}
|
||||
|
||||
/**
|
||||
* Address inconsistent `text-transform` inheritance for `button` and `select`.
|
||||
* All other form control elements do not inherit `text-transform` values.
|
||||
* Correct `button` style inheritance in Firefox, IE 8/9/10/11, and Opera.
|
||||
* Correct `select` style inheritance in Firefox.
|
||||
*/
|
||||
|
||||
button,
|
||||
select {
|
||||
text-transform: none;
|
||||
}
|
||||
|
||||
/**
|
||||
* 1. Avoid the WebKit bug in Android 4.0.* where (2) destroys native `audio`
|
||||
* and `video` controls.
|
||||
* 2. Correct inability to style clickable `input` types in iOS.
|
||||
* 3. Improve usability and consistency of cursor style between image-type
|
||||
* `input` and others.
|
||||
*/
|
||||
|
||||
button,
|
||||
html input[type="button"], /* 1 */
|
||||
input[type="reset"],
|
||||
input[type="submit"] {
|
||||
-webkit-appearance: button; /* 2 */
|
||||
cursor: pointer; /* 3 */
|
||||
}
|
||||
|
||||
/**
|
||||
* Re-set default cursor for disabled elements.
|
||||
*/
|
||||
|
||||
button[disabled],
|
||||
html input[disabled] {
|
||||
cursor: default;
|
||||
}
|
||||
|
||||
/**
|
||||
* Remove inner padding and border in Firefox 4+.
|
||||
*/
|
||||
|
||||
button::-moz-focus-inner,
|
||||
input::-moz-focus-inner {
|
||||
border: 0;
|
||||
padding: 0;
|
||||
}
|
||||
|
||||
/**
|
||||
* Address Firefox 4+ setting `line-height` on `input` using `!important` in
|
||||
* the UA stylesheet.
|
||||
*/
|
||||
|
||||
input {
|
||||
line-height: normal;
|
||||
}
|
||||
|
||||
/**
|
||||
* It's recommended that you don't attempt to style these elements.
|
||||
* Firefox's implementation doesn't respect box-sizing, padding, or width.
|
||||
*
|
||||
* 1. Address box sizing set to `content-box` in IE 8/9/10.
|
||||
* 2. Remove excess padding in IE 8/9/10.
|
||||
*/
|
||||
|
||||
input[type="checkbox"],
|
||||
input[type="radio"] {
|
||||
box-sizing: border-box; /* 1 */
|
||||
padding: 0; /* 2 */
|
||||
}
|
||||
|
||||
/**
|
||||
* Fix the cursor style for Chrome's increment/decrement buttons. For certain
|
||||
* `font-size` values of the `input`, it causes the cursor style of the
|
||||
* decrement button to change from `default` to `text`.
|
||||
*/
|
||||
|
||||
input[type="number"]::-webkit-inner-spin-button,
|
||||
input[type="number"]::-webkit-outer-spin-button {
|
||||
height: auto;
|
||||
}
|
||||
|
||||
/**
|
||||
* 1. Address `appearance` set to `searchfield` in Safari and Chrome.
|
||||
* 2. Address `box-sizing` set to `border-box` in Safari and Chrome
|
||||
* (include `-moz` to future-proof).
|
||||
*/
|
||||
|
||||
input[type="search"] {
|
||||
-webkit-appearance: textfield; /* 1 */
|
||||
-moz-box-sizing: content-box;
|
||||
-webkit-box-sizing: content-box; /* 2 */
|
||||
box-sizing: content-box;
|
||||
}
|
||||
|
||||
/**
|
||||
* Remove inner padding and search cancel button in Safari and Chrome on OS X.
|
||||
* Safari (but not Chrome) clips the cancel button when the search input has
|
||||
* padding (and `textfield` appearance).
|
||||
*/
|
||||
|
||||
input[type="search"]::-webkit-search-cancel-button,
|
||||
input[type="search"]::-webkit-search-decoration {
|
||||
-webkit-appearance: none;
|
||||
}
|
||||
|
||||
/**
|
||||
* Define consistent border, margin, and padding.
|
||||
*/
|
||||
|
||||
fieldset {
|
||||
border: 1px solid #c0c0c0;
|
||||
margin: 0 2px;
|
||||
padding: 0.35em 0.625em 0.75em;
|
||||
}
|
||||
|
||||
/**
|
||||
* 1. Correct `color` not being inherited in IE 8/9/10/11.
|
||||
* 2. Remove padding so people aren't caught out if they zero out fieldsets.
|
||||
*/
|
||||
|
||||
legend {
|
||||
border: 0; /* 1 */
|
||||
padding: 0; /* 2 */
|
||||
}
|
||||
|
||||
/**
|
||||
* Remove default vertical scrollbar in IE 8/9/10/11.
|
||||
*/
|
||||
|
||||
textarea {
|
||||
overflow: auto;
|
||||
}
|
||||
|
||||
/**
|
||||
* Don't inherit the `font-weight` (applied by a rule above).
|
||||
* NOTE: the default cannot safely be changed in Chrome and Safari on OS X.
|
||||
*/
|
||||
|
||||
optgroup {
|
||||
font-weight: bold;
|
||||
}
|
||||
|
||||
/* Tables
|
||||
========================================================================== */
|
||||
|
||||
/**
|
||||
* Remove most spacing between table cells.
|
||||
*/
|
||||
|
||||
table {
|
||||
border-collapse: collapse;
|
||||
border-spacing: 0;
|
||||
}
|
||||
|
||||
td,
|
||||
th {
|
||||
padding: 0;
|
||||
}
|
||||
|
|
@ -0,0 +1,63 @@
|
|||
---
|
||||
description: Keep a Changelog
|
||||
title: Keep a Changelog
|
||||
language: fr
|
||||
---
|
||||
|
||||
:markdown
|
||||
# Gardez un CHANGELOG
|
||||
|
||||
## Ne laissez pas vos amis déversent journaux git dans ChangeLogs™
|
||||
|
||||
### Qu'est-ce qu'un journal de change log?
|
||||
Un journal des modifications est un fichier qui contient un commissaire de
|
||||
l'exposition, la liste par ordre chronologique des changements notables pour
|
||||
chaque version d'un projet.
|
||||
|
||||
%pre.changelog= File.read(File.expand_path("../../../CHANGELOG.md", __FILE__))
|
||||
|
||||
:markdown
|
||||
### Quel est le point d'un journal des modifications?
|
||||
Pour rendre plus facile pour les utilisateurs et contributeurs pour voir
|
||||
précisément ce que des changements notables ont été réalisés entre chaque
|
||||
version (ou une version) du projet.
|
||||
|
||||
### Pourquoi devrais-je m'en soucier?
|
||||
Parce que les outils logiciels sont pour les gens. Si vous ne vous souciez
|
||||
pas, pourquoi êtes-vous contribuerez à l'Open Source? Sûrement, il doit y
|
||||
avoir un noyau (ha!) Des soins, quelque part dans ce beau petit cerveau de la
|
||||
vôtre.
|
||||
|
||||
Je [parlais avec Adam Stacoviak et Jerod Santo sur le
|
||||
changelog][thechangelog] (montage, non?) Podcast sur la raison
|
||||
pour laquelle la maintenance et les contributeurs doivent prendre soin, et
|
||||
les motivations derrière ce projet. Si vous pouvez épargner le temps (01:06),
|
||||
il est une bonne écoute.
|
||||
|
||||
### Ce qui fait un bon changement log?
|
||||
Je suis content que vous posiez.
|
||||
|
||||
Un bon journal des modifications colle à ces principes:
|
||||
|
||||
- Il est fait pour les êtres humains, pas des machines, de sorte que la
|
||||
lisibilité est crucial.
|
||||
- Facile à créer un lien vers une section (d'où Markdown plus de texte brut).
|
||||
- Une sous-section par version.
|
||||
- Liste presse dans l'ordre chronologique inverse (les plus récents en haut).
|
||||
- Écrivez toutes les dates dans `AAAA-MM-JJ` le format. (Exemple:
|
||||
`2012-06-02` pour `2ème Juin, 2012`.) Il est international,
|
||||
[sensée](http://xkcd.com/1179/), et indépendant de la langue.
|
||||
- Mentionner explicitement si le projet suit [Versioning sémantique][semver].
|
||||
- Chaque version devrait:
|
||||
- Inscrivez sa date de sortie dans le format ci-dessus.
|
||||
- Groupe change de décrire leur impact sur le projet, comme suit:
|
||||
- `Ajouté` de nouvelles fonctionnalités.
|
||||
- `Changé` pour des changements dans les fonctionnalités existantes.
|
||||
- `Déconseillé` pour les fonctions autrefois stables supprimé dans les
|
||||
prochaines versions.
|
||||
- `Suppression` des fonctions obsolètes supprimés dans cette version.
|
||||
- `Fixe` pour toutes les corrections de bugs.
|
||||
- `Sécurité` d'inviter les utilisateurs à passer en cas de vulnérabilités.
|
||||
|
||||
### Comment puis-je réduire les efforts nécessaires?
|
||||
Toujours avoir un `"Unreleased"` section au sommet pour garder la trace de tous les changements.
|
||||
|
|
@ -0,0 +1,177 @@
|
|||
---
|
||||
description: Keep a Changelog
|
||||
title: Keep a Changelog
|
||||
language: en
|
||||
---
|
||||
|
||||
:markdown
|
||||
# Keep a CHANGELOG
|
||||
|
||||
## 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.
|
||||
|
||||
%pre.changelog= File.read(File.expand_path("../../CHANGELOG.md", __FILE__))
|
||||
|
||||
: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.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].
|
||||
|
||||
[CHANGELOG]: ./CHANGELOG.md
|
||||
[gemnasium]: http://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/
|
||||
|
|
@ -0,0 +1,58 @@
|
|||
!!! 5
|
||||
%html
|
||||
%head{lang: current_page.data.language}
|
||||
%meta{charset: 'utf-8'}
|
||||
%meta{content: 'IE=edge', 'http-equiv' => 'X-UA-Compatible'}
|
||||
%meta{name: 'viewport', content: 'width=device-width, initial-scale=1.0'}
|
||||
%meta{name: 'description', content: current_page.data.description}
|
||||
|
||||
-# Open Graph
|
||||
|
||||
%meta{property: 'og:article:publisher', content: 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)}
|
||||
%meta{property: 'og:description', content: current_page.data.description}
|
||||
= yield_content :og
|
||||
|
||||
-# Icons
|
||||
|
||||
%link{rel: 'shortcut icon', type: 'image/x-icon', href: '/favicon.ico'}
|
||||
%link{rel: 'apple-touch-icon', href: '/apple-touch-icon.png'}
|
||||
|
||||
%link{rel: 'canonical', href: path_to_url(current_page.url)}
|
||||
|
||||
%title= current_page.data.title
|
||||
= stylesheet_link_tag 'application'
|
||||
|
||||
= javascript_include_tag "//use.typekit.net/tng8liq.js"
|
||||
|
||||
:javascript
|
||||
try{Typekit.load();}catch(e){}
|
||||
|
||||
%body
|
||||
%article
|
||||
= yield
|
||||
%footer.clearfix
|
||||
%p.license
|
||||
This project is
|
||||
#{link_to "MIT Licensed", "http://choosealicense.com/licenses/mit/"}.
|
||||
%p.about
|
||||
#{link_to "Typed", "https://github.com/olivierlacan/keep-a-changelog/"}
|
||||
with trepidation by
|
||||
#{link_to "Olivier Lacan", "http://olivierlacan.com"} from
|
||||
#{link_to "Code School", "http://codeschool.com"}.
|
||||
|
||||
- unless gauges_id.blank?
|
||||
:javascript
|
||||
var _gauges = _gauges || [];
|
||||
(function() {
|
||||
var t = document.createElement('script');
|
||||
t.type = 'text/javascript';
|
||||
t.async = true;
|
||||
t.id = 'gauges-tracker';
|
||||
t.setAttribute('data-site-id', '#{gauges_id}');
|
||||
t.src = '//secure.gaug.es/track.js';
|
||||
var s = document.getElementsByTagName('script')[0];
|
||||
s.parentNode.insertBefore(t, s);
|
||||
})();
|
||||
Loading…
Reference in New Issue