From 7f2eaef38d5a55c9a1707ae0f6fd1f050cf8fdcf Mon Sep 17 00:00:00 2001 From: Jonathan Neal Date: Sat, 19 Mar 2016 17:11:59 -0400 Subject: [PATCH] Update documentation and tests --- CHANGELOG.md | 75 +++++++++++++++++++++------------ CONTRIBUTING.md | 46 ++++++++++++++++++--- LICENSE.md | 4 +- README.md | 107 ++++++++++++++++++++++++++++++++---------------- test.html | 57 +++----------------------- 5 files changed, 170 insertions(+), 119 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ea49be8..ac6a5c9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,31 +1,50 @@ -=== HEAD +# Changes to normalize.css -* 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+. +### 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. +* 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). -* 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 index 30fa608..434ca45 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -21,7 +21,6 @@ requests](#pull-requests), but please respect the following restrictions: respect the opinions of others. - ## Bug reports A bug is a _demonstrable problem_ that is caused by the code in the repository. @@ -64,7 +63,6 @@ Example: > merits). - ## 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. - ## 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. + - ## 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 index c6bcc9b..43b5ddc 100644 --- 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 diff --git a/README.md b/README.md index 1b4dc3c..34842ec 100644 --- a/README.md +++ b/README.md @@ -1,26 +1,36 @@ -# normalize.css v3 +# normalize.css -Normalize.css is a customisable CSS file that makes browsers render all -elements more consistently and in line with modern standards. +Normalize Logo -The project relies on researching the differences between default browser -styles in order to precisely target only the styles that need or benefit from -normalizing. +> A modern alternative to CSS resets -[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` -* [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). +**NPM** -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) -* Edge (latest) -* Firefox (latest) +* Chrome (last two) +* Edge (last two) +* Firefox (last two) * Firefox ESR * Internet Explorer 8+ -* Opera (latest) +* Opera (last two) * Safari 6+ -[Normalize.css v1 provides legacy browser -support](https://github.com/necolas/normalize.css/tree/v1) (IE 6+, Safari 4+), -but is no longer actively developed. +*[Normalize.css v1 provides legacy browser support] +(https://github.com/necolas/normalize.css/tree/v1) (IE 6+, Safari 4+), +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 -Mailing List discussion](http://lists.w3.org/Archives/Public/public-svg-wg/2008JulSep/0339.html) +modern browsers use in the default UA stylesheets to apply this style. [Source] +(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 diff --git a/test.html b/test.html index f8ea790..a9d5524 100644 --- a/test.html +++ b/test.html @@ -1,9 +1,9 @@ - + Normalize CSS: UI tests - +