Update documentation and tests

CHANGELOG.md

@@ -1,31 +1,50 @@
-=== HEAD
+# Changes to normalize.css
 
-* Address inconsistent styling of b and strong.
+### HEAD
-* Correct `hr` overflow in IE 8/9/10/11 and Edge 12.
+
-* Ensure `mark` long-hand background declaration usage.
+* Add the correct font weight for `b` and `strong` in Chrome, Edge, and Safari.
-* Remove color inheritance from form controls.
+* Correct inconsistent `overflow` for `hr` in Edge and IE.
-* Address inconsistent styling of abbr[title].
+* Correct inconsistent `box-sizing` for `hr` in Firefox.
-* Correct inheritance and scaling of font-size for preformatted text.
+* Correct inconsistent `text-decoration` and `border-bottom` for `abbr[title]`
-* Replace focus style removed in the border reset in Firefox 4+.
+  in Chrome, Edge, Firefox IE, Opera, and Safari.
+* Correct inheritance and scaling of `font-size` for preformatted text.
+* Correct `legend` text wrapping not present in Edge and IE.
+* Remove unnecessary normalization of `line-height` for `input`.
+* Remove unnecessary normalization of `color` for form controls.
+* Remove unnecessary `box-sizing` for `input[type="search"]` in Chrome, Edge,
+  Firefox, IE, and Safari.
 * Remove opinionated table resets.
+* Remove opinionated `pre` overflow.
+* Remove selector weight from some input selectors.
+* Update normalization of `border-style` for `img`.
+* Update normalization of `color` inheritance for `legend`.
+* Update normalization of `background-color` for `mark`.
+* Update normalization of `outline` for `:-moz-focusring` removed by a previous
+  normalization in Firefox.
+* Update opinionated style of `outline-width` for `a:active` and `a:hover`.
+* Update comments to identify opinionated styles.
+* Update comments to specify browser/versions affected by all changes.
+* Update comments to use one voice.
 
-=== 3.0.3 (March 30, 2015)
+---
+
+### 3.0.3 (March 30, 2015)
 
 * Remove unnecessary vendor prefixes.
 * Add `main` property.
 
-=== 3.0.2 (October 4, 2014)
+### 3.0.2 (October 4, 2014)
 
 * Only alter `background-color` of links in IE 10.
 * Add `menu` element to HTML5 display definitions.
 
-=== 3.0.1 (March 27, 2014)
+### 3.0.1 (March 27, 2014)
 
 * Add package.json for npm support.
 
-=== 3.0.0 (January 28, 2014)
+### 3.0.0 (January 28, 2014)
 
-=== 3.0.0-rc.1 (January 26, 2014)
+### 3.0.0-rc.1 (January 26, 2014)
 
 * Explicit tests for each normalization.
 * Fix i18n for `q` element.
@@ -41,21 +60,23 @@
 * Set correct display for `progress` in IE 8/9.
 * Fix `font` and `color` inheritance for forms.
 
-=== 2.1.3 (August 26, 2013)
+---
+
+### 2.1.3 (August 26, 2013)
 
 * Fix component.json.
 * Remove the gray background color from active links in IE 10.
 
-=== 2.1.2 (May 11, 2013)
+### 2.1.2 (May 11, 2013)
 
 * Revert root `color` and `background` normalizations.
 
-=== 2.1.1 (April 8, 2013)
+### 2.1.1 (April 8, 2013)
 
 * Normalize root `color` and `background` to counter the effects of system
   color schemes.
 
-=== 2.1.0 (January 21, 2013)
+### 2.1.0 (January 21, 2013)
 
 * Normalize `text-transform` for `button` and `select`.
 * Normalize `h1` margin when within HTML5 sectioning elements.
@@ -64,11 +85,11 @@
 * Add `main` element to HTML5 display definitions.
 * Fix cursor style for disabled button `input`.
 
-=== 2.0.1 (August 20, 2012)
+### 2.0.1 (August 20, 2012)
 
 * Remove stray IE 6/7 `inline-block` hack from HTML5 display settings.
 
-=== 2.0.0 (August 19, 2012)
+### 2.0.0 (August 19, 2012)
 
 * Remove legacy browser form normalizations.
 * Remove all list normalizations.
@@ -77,19 +98,21 @@
 * Form elements automatically inherit `font-family` from ancestor.
 * Drop support for IE 6/7, Firefox < 4, and Safari < 5.
 
-=== 1.0.1 (August 19, 2012)
+---
+
+### 1.0.1 (August 19, 2012)
 
 * Adjust `small` font size normalization.
 
-=== 1.0.0 (August 14, 2012)
+### 1.0.0 (August 14, 2012)
 
 (Only the notable changes since public release)
 
 * Add MIT License.
-* Hide `audio` elements without controls in iOS 5 (#69).
+* Hide `audio` elements without controls in iOS 5.
 * Normalize heading margins and font size.
-* Move font-family normalization from `body` to `html` (#62).
+* Move font-family normalization from `body` to `html`.
-* Remove scrollbar normalization (#64 #65).
+* Remove scrollbar normalization.
-* Remove excess padding from checkbox and radio inputs in IE 7 (#42).
+* Remove excess padding from checkbox and radio inputs in IE 7.
-* Add IE9 correction for SVG overflow (#16).
+* Add IE9 correction for SVG overflow.
 * Add fix for legend not inheriting color in IE 6/7/8/9.

CONTRIBUTING.md

@@ -21,7 +21,6 @@ requests](#pull-requests), but please respect the following restrictions:
   respect the opinions of others.
 
 
-<a name="bugs"></a>
 ## Bug reports
 
 A bug is a _demonstrable problem_ that is caused by the code in the repository.
@@ -64,7 +63,6 @@ Example:
 > merits).
 
 
-<a name="features"></a>
 ## Feature requests
 
 Feature requests are welcome. But take a moment to find out whether your idea
@@ -73,7 +71,6 @@ case to convince the project's developers of the merits of this feature. Please
 provide as much detail and context as possible.
 
 
-<a name="pull-requests"></a>
 ## Pull requests
 
 Good pull requests - patches, improvements, new features - are a fantastic
@@ -90,7 +87,7 @@ accurate comments, etc.) and any other requirements (such as test coverage).
 Follow this process if you'd like your work considered for inclusion in the
 project:
 
-1. [Fork](http://help.github.com/fork-a-repo/) the project, clone your fork,
+1. [Fork](https://help.github.com/articles/fork-a-repo/) the project, clone your fork,
    and configure the remotes:
 
    ```bash
@@ -122,9 +119,19 @@ project:
    [interactive rebase](https://help.github.com/articles/interactive-rebase)
    feature to tidy up your commits before making them public.
 
-   Make sure to add a test to the `test.html` file if appropriate, and test
+   Be sure to test the `normalize.css` file for style conformance.
+
+   ```bash
+   npm test
+   ```
+
+   Be sure to add a test to the `test.html` file if appropriate, and test
    your change in all supported browsers.
 
+   ```bash
+   git pull --rebase upstream master
+   ```
+
 5. Locally rebase the upstream development branch into your topic branch:
 
    ```bash
@@ -146,8 +153,24 @@ project:
 **IMPORTANT**: By submitting a patch, you agree to allow the project owner to
 license your work under the same license as that used by the project.
 
+### CSS Conventions
+
+Keep the CSS file as readable as possible by following these guidelines:
+
+- Comments are short and to the point.
+- Comments without a number reference the entire rule.
+- Comments describe the selector when the selector does not make the
+  normalization obvious.
+- Comments begin with “Correct the...” when they deal with less obvious side
+  effects.
+- Rules are sorted by cascade, specificity, and then alphabetic order.
+- Selectors are sorted by specificity and then alphabetic order.
+- `in browser` applies to all versions.
+- `in browser v-` applies to all versions up to and including the version.
+- `in browser v+` applies to all versions after and including the version.
+- `in browser v-v` applies to all versions including and between the versions.
+
 
-<a name="maintainers"></a>
 ## Maintainers
 
 If you have commit access, please follow this process for merging patches and
@@ -175,3 +198,14 @@ cutting new releases.
 4. Create an annotated tag for the version: `git tag -m "v0.0.0" 0.0.0`.
 5. Push the changes and tags to GitHub: `git push --tags origin master`
 6. Checkout the `gh-pages` branch and follow the instructions in the README.
+
+### Semver strategy
+
+[Semver](http://semver.org/) is a widely accepted method for deciding how
+version numbers are incremented in a project. Versions are written as
+MAJOR.MINOR.PATCH.
+
+Changes limited to fallback declarations for browsers which do not support
+newer features produce a PATCH release.
+
+Changes limited to normalizations for older browsers produce a MINOR release.

LICENSE.md

@@ -1,4 +1,6 @@
-Copyright (c) Nicolas Gallagher and Jonathan Neal
+# The MIT License (MIT)
+
+Copyright © Nicolas Gallagher and Jonathan Neal
 
 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

README.md

@@ -1,26 +1,36 @@
-# normalize.css v3
+# normalize.css
 
-Normalize.css is a customisable CSS file that makes browsers render all
+<a href="https://github.com/necolas/normalize.css"><img
-elements more consistently and in line with modern standards.
+  src="https://necolas.github.io/normalize.css/logo.svg" alt="Normalize Logo"
+  width="80" height="80" align="right"></a>
 
-The project relies on researching the differences between default browser
+> A modern alternative to CSS resets
-styles in order to precisely target only the styles that need or benefit from
-normalizing.
 
-[View the test file](http://necolas.github.io/normalize.css/latest/test.html)
+[![npm][npm-image]][npm-url] [![license][license-image]][license-url]
+[![changelog][changelog-image]][changelog-url]
+[![gitter][gitter-image]][gitter-url]
 
-## Install
 
-* [npm](http://npmjs.org/): `npm install --save normalize.css`
+**NPM**
-* [Bower](http://bower.io/): `bower install --save
-  https://github.com/necolas/normalize.css.git`
-* [cdnjs](https://cdnjs.com/libraries/normalize)
-* [Download](http://necolas.github.io/normalize.css/latest/normalize.css).
 
-No other styles should come before Normalize.css.
+```sh
+npm install --save normalize.css
+```
+
+**Bower**
+
+```sh
+bower install --save normalize-css
+```
+
+**CDN**
+
+See https://cdnjs.com/libraries/normalize
+
+**Download**
+
+See https://necolas.github.io/normalize.css/latest/normalize.css
 
-It is recommended that you include the `normalize.css` file as untouched
-library code.
 
 ## What does it do?
 
@@ -30,21 +40,23 @@ library code.
 * Improves usability with subtle improvements.
 * Explains what code does using detailed comments.
 
+
 ## Browser support
 
-* Chrome (latest)
+* Chrome (last two)
-* Edge (latest)
+* Edge (last two)
-* Firefox (latest)
+* Firefox (last two)
 * Firefox ESR
 * Internet Explorer 8+
-* Opera (latest)
+* Opera (last two)
 * Safari 6+
 
-[Normalize.css v1 provides legacy browser
+*[Normalize.css v1 provides legacy browser support]
-support](https://github.com/necolas/normalize.css/tree/v1) (IE 6+, Safari 4+),
+(https://github.com/necolas/normalize.css/tree/v1) (IE 6+, Safari 4+),
-but is no longer actively developed.
+but is no longer actively developed.*
 
-## Extended details
+
+## Extended details and known issues
 
 Additional detail and explanation of the esoteric parts of normalize.css.
 
@@ -52,21 +64,37 @@ Additional detail and explanation of the esoteric parts of normalize.css.
 
 The `font-family: monospace, monospace` hack fixes the inheritance and scaling
 of font-size for preformatted text. The duplication of `monospace` is
-intentional. [Source](http://en.wikipedia.org/wiki/User:Davidgothberg/Test59).
+intentional. [Source](https://en.wikipedia.org/wiki/User:Davidgothberg/Test59).
 
 #### `sub, sup`
 
 Normally, using `sub` or `sup` affects the line-box height of text in all
-browsers. [Source](http://gist.github.com/413930).
+browsers. [Source](https://gist.github.com/413930).
 
 #### `svg:not(:root)`
 
 Adding `overflow: hidden` fixes IE9's SVG rendering. Earlier versions of IE
 don't support SVG, so we can safely use the `:not()` and `:root` selectors that
-modern browsers use in the default UA stylesheets to apply this style. [SVG
+modern browsers use in the default UA stylesheets to apply this style. [Source]
-Mailing List discussion](http://lists.w3.org/Archives/Public/public-svg-wg/2008JulSep/0339.html)
+(https://lists.w3.org/Archives/Public/public-svg-wg/2008JulSep/0339.html).
 
-#### `input[type="search"]`
+#### `select`
+
+By default, Chrome on OS X and Safari on OS X allow very limited styling of
+`select`, unless a border property is set. The default font weight on `optgroup`
+elements cannot safely be changed in Chrome on OSX and Safari on OS X.
+
+#### `[type="checkbox"]`
+
+It is recommended that you do not style checkbox and radio inputs as Firefox's
+implementation does not respect box-sizing, padding, or width.
+
+#### `[type="number"]`
+
+Certain font size values applied to number inputs cause the cursor style of the
+decrement button to change from `default` to `text`.
+
+#### `[type="search"]`
 
 The search input is not fully stylable by default. In Chrome and Safari on
 OSX/iOS you can't control `font`, `padding`, `border`, or `background`. In
@@ -74,18 +102,27 @@ Chrome and Safari on Windows you can't control `border` properly. It will apply
 `border-width` but will only show a border color (which cannot be controlled)
 for the outer 1px of that border. Applying `-webkit-appearance: textfield`
 addresses these issues without removing the benefits of search inputs (e.g.
-showing past searches).
+showing past searches). Safari (but not Chrome) will clip the cancel button on
+when it has padding (and `textfield` appearance).
 
-#### `legend`
-
-Adding `border: 0` corrects an IE 8–11 bug where `color` (yes, `color`) is not
-inherited by `legend`.
 
 ## Contributing
 
-Please read the [contribution guidelines](CONTRIBUTING.md).
+Please read the [contribution guidelines](CONTRIBUTING.md) in order to make the
+contribution process easy and effective for everyone involved.
+
 
 ## Acknowledgements
 
 Normalize.css is a project by [Nicolas Gallagher](https://github.com/necolas),
 co-created with [Jonathan Neal](https://github.com/jonathantneal).
+
+
+[changelog-image]: https://img.shields.io/badge/changelog-md-blue.svg?style=flat-square
+[changelog-url]: CHANGELOG.md
+[license-image]: https://img.shields.io/npm/l/normalize.css.svg?style=flat-square
+[license-url]: LICENSE.md
+[npm-image]: https://img.shields.io/npm/v/normalize.css.svg?style=flat-square
+[npm-url]: https://www.npmjs.com/package/normalize.css
+[gitter-image]: https://img.shields.io/badge/chat-gitter-blue.svg?style=flat-square
+[gitter-url]: https://gitter.im/necolas/normalize.css

test.html

@@ -3,7 +3,7 @@
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width,initial-scale=1">
 <title>Normalize CSS: UI tests</title>
-<script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
+<script src="https://html5shim.googlecode.com/svn/trunk/html5.js"></script>
 <link rel="stylesheet" href="normalize.css">
 <style>
   /*! suit-test v0.1.0 | MIT License | github.com/suitcss */
@@ -100,7 +100,7 @@
   <h2 class="Test-describe">
     <code>article</code>, <code>aside</code>, <code>details</code>,
     <code>figure</code>, <code>figcaption</code>, <code>footer</code>,
-    <code>header</code>, <code>hgroup</code>, <code>main</code>,
+    <code>header</code>, <code>main</code>,
     <code>menu</code>, <code>nav</code>, <code>section</code>,
     <code>summary</code>
   </h2>
@@ -118,7 +118,6 @@
     </figure>
     <footer>footer</footer>
     <header>header</header>
-    <hgroup>hgroup</hgroup>
     <main>main</main>
     <menu><li>menu</li></menu>
     <nav>nav</nav>
@@ -156,13 +155,13 @@
   </div>
 
   <h2 class="Test-describe"><code>abbr[title]</code></h2>
-  <h3 class="Test-it">should have a dotted bottom border</h3>
+  <h3 class="Test-it">should have a dotted underline with a solid underline as a fallback</h3>
   <div class="Test-run">
     <abbr title="abbreviation">abbr</abbr>
   </div>
 
   <h2 class="Test-describe"><code>b</code>, <code>strong</code></h2>
-  <h3 class="Test-it">should have bold font-weight</h3>
+  <h3 class="Test-it">should have bolder font-weight</h3>
   <div class="Test-run">
     <b>b</b>
     <strong>strong</strong>
@@ -242,7 +241,7 @@
   </div>
 
   <h2 class="Test-describe"><code>code</code>, <code>kbd</code>, <code>pre</code>, <code>samp</code></h2>
-  <h3 class="Test-it">should render <code>em</code>-unit preformatted text at the same absolute size as normal text</h3>
+  <h3 class="Test-it">should render text at the same absolute size as normal text</h3>
   <div class="Test-run">
     <span>span: abcdefghijklmnopqrstuvwxyz.</span><br>
     <code>code: abcdefghijklmnopqrstuvwxyz.</code><br>
@@ -444,48 +443,4 @@
     <textarea>textarea</textarea>
   </div>
 
-  <h2 class="Test-describe"><code>table</code></h2>
-  <h3 class="Test-it">should not have spaces between cells</h3>
-  <div class="Test-run">
-    <table>
-      <caption>Jimi Hendrix - albums</caption>
-      <thead>
-        <tr>
-          <th>Album</th>
-          <th>Year</th>
-          <th>Price</th>
-        </tr>
-      </thead>
-      <tfoot>
-        <tr>
-          <th>Album</th>
-          <th>Year</th>
-          <th>Price</th>
-        </tr>
-      </tfoot>
-      <tbody>
-        <tr>
-          <td>Are You Experienced</td>
-          <td>1967</td>
-          <td>$10.00</td>
-        </tr>
-        <tr>
-          <td>Axis: Bold as Love</td>
-          <td>1967</td>
-          <td>$12.00</td>
-        </tr>
-        <tr>
-          <td>Electric Ladyland</td>
-          <td>1968</td>
-          <td>$10.00</td>
-        </tr>
-        <tr>
-          <td>Band of Gypsys</td>
-          <td>1970</td>
-          <td>$12.00</td>
-        </tr>
-      </tbody>
-    </table>
-  </div>
-
 </div>