Update documentation and tests

necolas · Mar 19, 2016 · 7f2eaef38d5a55c9a1707ae0f6fd1f050cf8fdcf · 7f2eaef
1 parent 0c90242
commit 7f2eaef38d5a55c9a1707ae0f6fd1f050cf8fdcf
Show file tree

Hide file tree

Showing 5 changed files with 172 additions and 121 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,31 +1,50 @@
-=== HEAD
-
-* Address inconsistent styling of b and strong.
-* Correct `hr` overflow in IE 8/9/10/11 and Edge 12.
-* Ensure `mark` long-hand background declaration usage.
-* Remove color inheritance from form controls.
-* Address inconsistent styling of abbr[title].
-* Correct inheritance and scaling of font-size for preformatted text.
-* Replace focus style removed in the border reset in Firefox 4+.
+# Changes to normalize.css
+
+### HEAD
+
+* Add the correct font weight for `b` and `strong` in Chrome, Edge, and Safari.
+* Correct inconsistent `overflow` for `hr` in Edge and IE.
+* Correct inconsistent `box-sizing` for `hr` in Firefox.
+* Correct inconsistent `text-decoration` and `border-bottom` for `abbr[title]`
+  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.
-
-=== 3.0.3 (March 30, 2015)
+* 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)
 
 * 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).
-* Remove scrollbar normalization (#64 #65).
-* Remove excess padding from checkbox and radio inputs in IE 7 (#42).
-* Add IE9 correction for SVG overflow (#16).
+* Move font-family normalization from `body` to `html`.
+* Remove scrollbar normalization.
+* Remove excess padding from checkbox and radio inputs in IE 7.
+* Add IE9 correction for SVG overflow.
 * Add fix for legend not inheriting color in IE 6/7/8/9.
diff --git a/CONTRIBUTING.md b/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.
diff --git a/LICENSE.md b/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