From 8692eade4dd8a6e5ac3bf00910b89cad7ddb4c5c Mon Sep 17 00:00:00 2001 From: Nathaniel Bibler Date: Sun, 18 Oct 2015 16:35:49 -0400 Subject: [PATCH] Convert static files to a Middleman app. --- .editorconfig | 16 + .gitignore | 5 + .ruby-version | 1 + CHANGELOG.md | 91 +++++ CONTRIBUTING.md | 14 + Gemfile | 13 + Gemfile.lock | 184 +++++++++ LICENSE | 21 + README.md | 169 ++++++++ Rakefile | 4 + config.rb | 88 +++++ source/assets/javascripts/all.js | 1 + source/assets/stylesheets/application.sass | 109 ++++++ source/assets/stylesheets/normalize.css | 425 +++++++++++++++++++++ source/fr/index.haml | 63 +++ source/index.haml | 177 +++++++++ source/layouts/layout.haml | 58 +++ 17 files changed, 1439 insertions(+) create mode 100644 .editorconfig create mode 100644 .gitignore create mode 100644 .ruby-version create mode 100644 CHANGELOG.md create mode 100644 CONTRIBUTING.md create mode 100644 Gemfile create mode 100644 Gemfile.lock create mode 100644 LICENSE create mode 100644 README.md create mode 100644 Rakefile create mode 100644 config.rb create mode 100644 source/assets/javascripts/all.js create mode 100644 source/assets/stylesheets/application.sass create mode 100644 source/assets/stylesheets/normalize.css create mode 100644 source/fr/index.haml create mode 100644 source/index.haml create mode 100644 source/layouts/layout.haml 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); + })();