commit 8692eade4dd8a6e5ac3bf00910b89cad7ddb4c5c Author: Nathaniel Bibler Date: Sun Oct 18 16:35:49 2015 -0400 Convert static files to a Middleman app. diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..97eec54 --- /dev/null +++ b/.editorconfig @@ -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 diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..6cb2241 --- /dev/null +++ b/.gitignore @@ -0,0 +1,5 @@ +.DS_Store +/.bundle +/.cache +/.sass-cache +/build diff --git a/.ruby-version b/.ruby-version new file mode 100644 index 0000000..5859406 --- /dev/null +++ b/.ruby-version @@ -0,0 +1 @@ +2.2.3 diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..6fb9e10 --- /dev/null +++ b/CHANGELOG.md @@ -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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..d2a68f3 --- /dev/null +++ b/CONTRIBUTING.md @@ -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. diff --git a/Gemfile b/Gemfile new file mode 100644 index 0000000..13d35fd --- /dev/null +++ b/Gemfile @@ -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" diff --git a/Gemfile.lock b/Gemfile.lock new file mode 100644 index 0000000..8492c6f --- /dev/null +++ b/Gemfile.lock @@ -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 diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..b3dc2a3 --- /dev/null +++ b/LICENSE @@ -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. diff --git a/README.md b/README.md new file mode 100644 index 0000000..3f2631b --- /dev/null +++ b/README.md @@ -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. + + + +### 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/ diff --git a/Rakefile b/Rakefile new file mode 100644 index 0000000..74d7d27 --- /dev/null +++ b/Rakefile @@ -0,0 +1,4 @@ +require "middleman-gh-pages" + +desc "Build and publish to GitHub Pages" +task :deploy => :publish diff --git a/config.rb b/config.rb new file mode 100644 index 0000000..7a396cf --- /dev/null +++ b/config.rb @@ -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 diff --git a/source/assets/javascripts/all.js b/source/assets/javascripts/all.js new file mode 100644 index 0000000..2c03f2d --- /dev/null +++ b/source/assets/javascripts/all.js @@ -0,0 +1 @@ +//= require_tree . diff --git a/source/assets/stylesheets/application.sass b/source/assets/stylesheets/application.sass new file mode 100644 index 0000000..a9e59e1 --- /dev/null +++ b/source/assets/stylesheets/application.sass @@ -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 diff --git a/source/assets/stylesheets/normalize.css b/source/assets/stylesheets/normalize.css new file mode 100644 index 0000000..08f8950 --- /dev/null +++ b/source/assets/stylesheets/normalize.css @@ -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; +} diff --git a/source/fr/index.haml b/source/fr/index.haml new file mode 100644 index 0000000..c7d5afe --- /dev/null +++ b/source/fr/index.haml @@ -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. diff --git a/source/index.haml b/source/index.haml new file mode 100644 index 0000000..9c228f9 --- /dev/null +++ b/source/index.haml @@ -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/ diff --git a/source/layouts/layout.haml b/source/layouts/layout.haml new file mode 100644 index 0000000..b8cfe94 --- /dev/null +++ b/source/layouts/layout.haml @@ -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); + })();