Update readme

- Updates the tagline. - Updates the description and purpose of Bourbon. - Wraps lines at 80 characters. - Updates browser support. - Adds table of contents.
vittaljk · Nov 2, 2016 · 29d9ed4 · 29d9ed4
1 parent da3be35
commit 29d9ed4
Show file tree

Hide file tree

Showing 5 changed files with 117 additions and 51 deletions.
diff --git a/README.md b/README.md
@@ -1,44 +1,64 @@
-[![Bourbon](http://images.thoughtbot.com/bourbon/bourbon-logo.svg)](http://bourbon.io)
+[<img src="https://images.thoughtbot.com/bourbon/bourbon-logo.svg" width="200" alt="Bourbon logo">][Bourbon]
 
-[![GitHub release](https://img.shields.io/github/release/thoughtbot/bourbon.svg)](https://github.com/thoughtbot/bourbon/releases)
-[![CircleCI branch](https://img.shields.io/circleci/project/thoughtbot/bourbon/master.svg)](https://circleci.com/gh/thoughtbot/bourbon/tree/master)
+## A Lightweight Sass Tool Set
 
-## A simple and lightweight mixin library for Sass.
+[Bourbon] is a library of [Sass] mixins and functions that are designed to make
+you a more efficient style sheet author.
 
-Bourbon is a library of pure Sass mixins that are designed to be simple and easy to use. No configuration required. The mixins aim to be as vanilla as possible, meaning they should be as close to the original CSS syntax as possible.
+It is…
 
-The mixins contain vendor specific prefixes for all CSS3 properties for support amongst modern browsers. The prefixes also ensure graceful degradation for older browsers that support only CSS3 prefixed properties. Bourbon uses SCSS syntax.
+- Dependency-free: Bourbon is pure Sass.
+- Human-readable: We aim for clarity over brevity.
+- Lightweight: Zero output post-install and has no visual opinion.
 
-- **[Documentation](http://bourbon.io/docs)**
-- **[Changelog](https://github.com/thoughtbot/bourbon/releases)**
-- **[Issues & Bugs](https://github.com/thoughtbot/bourbon/issues)**
+The current version is **4.2.7**. The `master` branch on GitHub is version
+5.0.0-beta.6.
 
-Follow the [@bourbonsass](https://twitter.com/bourbonsass) Twitter account
-for updates.
+  [Bourbon]: http://bourbon.io
+  [Sass]: http://sass-lang.com
+
+### Helpful Links
+
+- [Documentation](http://bourbon.io/docs/latest/)
+- [Change log](CHANGELOG.md)
+- [Twitter](https://twitter.com/bourbonsass)
+
+## Table of Contents
+
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Command Line Interface](#command-line-interface)
+- [Browser Support](#browser-support)
+- [The Bourbon Family](#the-bourbon-family)
+- [Contributing](#contributing)
+- [License](#license)
+- [About](#about)
 
 ## Requirements
 
-- [Sass](https://github.com/sass/sass) 3.4+ or [LibSass](https://github.com/sass/libsass) 3.3+
+- [Sass] 3.4+ or [LibSass] 3.3+
 
-## Installation
+  [Sass]: https://github.com/sass/sass
+  [LibSass]: https://github.com/sass/libsass
 
-For command line help, visit our wiki page on Bourbon’s [command line interface](https://github.com/thoughtbot/bourbon/wiki/Command-Line-Interface).
+## Installation
 
-1. Install the Bourbon gem using the [RubyGems](https://rubygems.org) package manager:
+1. Install the Bourbon gem using the [RubyGems] package manager:
 
   ```bash
   gem install bourbon
   ```
 
-  Alternatively, you can install Bourbon with [Bower](http://bower.io).
+  Alternatively, you can install Bourbon with [Bower].
 
 1. Install the Bourbon library into the current directory:
 
   ```bash
   bourbon install
   ```
 
-  **Pro Tip:** You can target installation into a specific directory using the `path` flag:
+  **Pro Tip:** You can target installation into a specific directory using the
+  `path` flag:
 
   ```bash
   bourbon install --path my/custom/path/
@@ -50,9 +70,14 @@ For command line help, visit our wiki page on Bourbon’s [command line interfac
   @import "bourbon/bourbon";
   ```
 
-  It’s not recommended to add or modify the Bourbon files so that you can update them easily.
+  It’s not recommended that you modify Bourbon’s files directly as it will make
+  updating to future versions difficult, by overwriting your custom changes or
+  causing merge conflicts.
 
-## Installation for Ruby on Rails 4.2+
+  [RubyGems]: https://rubygems.org
+  [Bower]: http://bower.io
+
+### Installation for Ruby on Rails 4.2+
 
 1. Add Bourbon to your Gemfile:
 
@@ -72,66 +97,104 @@ For command line help, visit our wiki page on Bourbon’s [command line interfac
   mv app/assets/stylesheets/application.css app/assets/stylesheets/application.scss
   ```
 
-1. Delete _all_ Sprockets directives in `application.scss` (`require`, `require_tree` and `require_self`) and use Sass’s native `@import` instead ([why?](http://pivotallabs.com/structure-your-sass-files-with-import)).
+1. Delete _all_ Sprockets directives in `application.scss` (`require`,
+   `require_tree` and `require_self`) and use Sass’s native `@import` instead
+   ([why?][sass-import]).
 
-1. Import Bourbon at the beginning of `application.scss`. All additional stylesheets should be imported below Bourbon:
+1. Import Bourbon at the beginning of `application.scss`. Any project styles
+   that utilize Bourbon’s features must be imported after Bourbon.
 
   ```scss
   @import "bourbon";
   @import "home";
   @import "users";
   ```
 
-  [Help! I’m getting an undefined mixin error.](https://github.com/thoughtbot/bourbon/wiki/Rails-Help-%5C-Undefined-mixin)
+  [sass-import]: http://pivotallabs.com/structure-your-sass-files-with-import
 
-## Installing with npm and using a Node-based asset pipeline
+### Installing with npm and using a Node-based asset pipeline
 
 1. Add Bourbon as a dependency:
 
   ```bash
   npm install --save bourbon
   ```
 
-1. If you’re using [Eyeglass](http://eyeglass.rocks), skip to Step 3. Otherwise, you’ll need to add Bourbon to your node-sass `includePaths` option. `require("bourbon").includePaths` is an array of directories that you should pass to node-sass. How you do this depends on how node-sass is integrated into your project.
+1. If you’re using [eyeglass], skip to Step 3. Otherwise,
+you’ll need to add Bourbon to your node-sass `includePaths` option.
+`require("bourbon").includePaths` is an array of directories that you should
+pass to node-sass. How you do this depends on how node-sass is integrated into
+your project.
 
 1. Import Bourbon into your Sass files:
 
   ```scss
   @import "bourbon";
   ```
 
-## Installing older versions of Bourbon
+  [eyeglass]: http://eyeglass.rocks
+
+### Installing older versions of Bourbon
 
 1. Uninstall any Bourbon gem versions you already have:
 
   ```bash
   gem uninstall bourbon
   ```
 
-1. Reinstall the Bourbon gem, using the `-v` flag to specify the version you need:
+1. Reinstall the Bourbon gem, using the `-v` flag to specify the version
+   you need:
 
   ```bash
   gem install bourbon -v 3.2.4
   ```
 
-1. Follow the [instructions above](#installation) to install Bourbon into your project.
+1. Follow the [instructions above](#installation) to install Bourbon into
+   your project.
+
+## Command Line Interface
+
+```bash
+bourbon [options]
+```
+
+### Options
+
+| Option            | Description               |
+| :---------------- | :------------------------ |
+| `-h`, `--help`    | Show help                 |
+| `-v`, `--version` | Show the version number   |
+| `--path`          | Specify a custom path     |
+| `--force`         | Force install (overwrite) |
+
+### Commands
+
+| Command           | Description                                           |
+| :---------------- | :---------------------------------------------------- |
+| `bourbon install` | Install Bourbon into the current directory            |
+| `bourbon update`  | Overwrite and update Bourbon in the current directory |
+| `bourbon help`    | Show help                                             |
+
+## Browser Support
 
-## Browser support
+Bourbon supports Internet Explorer 11+ and the latest versions of Chrome,
+Firefox, Safari, and Edge.
 
-- Chrome 26+
-- Firefox 29+
-- Internet Explorer 9+
-- Opera 15+
-- Safari 6.1+
+## The Bourbon Family
 
-## The Bourbon family
+Bourbon is part of a larger, modular family of Sass utilities:
 
-- [Bourbon](https://github.com/thoughtbot/bourbon): A simple and lightweight mixin library for Sass
-- [Neat](https://github.com/thoughtbot/neat): A lightweight semantic grid framework for Sass and Bourbon
-- [Bitters](https://github.com/thoughtbot/bitters): Scaffold styles, variables and structure for Bourbon projects
-- [Refills](https://github.com/thoughtbot/refills): Prepackaged patterns and components built with Bourbon, Neat and Bitters
+- [Bourbon](https://github.com/thoughtbot/bourbon): A lightweight Sass tool set
+- [Neat](https://github.com/thoughtbot/neat): A lightweight semantic grid
+  framework for Sass and Bourbon
+- [Bitters](https://github.com/thoughtbot/bitters): Scaffold styles, variables
+  and structure for Bourbon projects
+- [Refills](https://github.com/thoughtbot/refills): Prepackaged patterns and
+  components built with Bourbon, Neat and Bitters
 
-Also check out [Proteus](https://github.com/thoughtbot/proteus), a collection of useful starter kits to help you prototype faster. Each kit comes with Bourbon, Neat and Bitters out-of-the-box.
+Be sure to also check out [Proteus](https://github.com/thoughtbot/proteus), a
+collection of useful starter kits to help you prototype faster. Each kit comes
+with Bourbon, Neat and Bitters out-of-the-box.
 
 ## Contributing
 
@@ -142,17 +205,21 @@ See the [contributing] document. Thank you, [contributors]!
 
 ## License
 
-Bourbon is copyright © 2011 [thoughtbot, inc.][thoughtbot] It is free software, and may be redistributed under the terms specified in the [license].
+Bourbon is copyright © 2011 [thoughtbot, inc.][thoughtbot] It is free software,
+and may be redistributed under the terms specified in the [license].
 
   [license]: LICENSE.md
 
 ## About
 
-Bourbon is maintained by Tyson Gach and the thoughtbot design team. It is funded by [thoughtbot, inc.][thoughtbot] and the names and logos for thoughtbot are trademarks of thoughtbot, inc.
+Bourbon is maintained by Tyson Gach and the thoughtbot design team. It is funded
+by [thoughtbot, inc.][thoughtbot] and the names and logos for thoughtbot are
+trademarks of thoughtbot, inc.
 
 [<img src="http://presskit.thoughtbot.com/images/signature.svg" width="250" alt="thoughtbot logo">][thoughtbot]
 
-We love open-source software! See [our other projects][community] or [hire us][hire] to design, develop, and grow your product.
+We love open-source software! See [our other projects][community] or
+[hire us][hire] to design, develop, and grow your product.
 
   [thoughtbot]: https://thoughtbot.com?utm_source=github
   [community]: https://thoughtbot.com/community?utm_source=github

diff --git a/RELEASING.md b/RELEASING.md
@@ -5,14 +5,15 @@
   - `core/_bourbon.scss`
   - `package.json`
   - `bower.json`
+  - `README.md`
 
 1. Update `CHANGELOG.md`. We follow the guidelines from [Keep a CHANGELOG].
 
 1. Commit changes. Use the convention “Bourbon vX.X.X” in your commit message.
    There shouldn’t be code changes, and thus CI doesn’t need to run.
 
-1. Run `bundle exec rake release`, which tags the release, pushes the tag to GitHub, and
-   pushes the gem to RubyGems.org.
+1. Run `bundle exec rake release`, which tags the release, pushes the tag to
+   GitHub, and pushes the gem to RubyGems.org.
 
 1. Run `npm publish`, which pushes the new version to npm’s registry (if
    releasing a pre-release, run `npm publish --tag beta`).

diff --git a/bourbon.gemspec b/bourbon.gemspec
@@ -22,10 +22,8 @@ Gem::Specification.new do |s|
     "Will McMahan"
   ]
   s.description = <<-DESC
-    Bourbon is a library of pure Sass mixins that are designed to be simple
-    and easy to use. No configuration required. The mixins aim to be as
-    vanilla as possible, meaning they should be as close to the original
-    CSS syntax as possible.
+    Bourbon is a library of pure Sass mixins and functions that are designed to
+    make you a more efficient developer.
   DESC
   s.email = "[email protected]"
   s.executables = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
@@ -35,7 +33,7 @@ Gem::Specification.new do |s|
   s.name = "bourbon"
   s.platform = Gem::Platform::RUBY
   s.require_paths = ["lib"]
-  s.summary = "A simple and lightweight mixin library for Sass"
+  s.summary = "A lightweight Sass tool set."
   s.test_files = `git ls-files -- {test,spec,features}/*`.split("\n")
   s.version = Bourbon::VERSION
 end
diff --git a/bower.json b/bower.json
@@ -2,7 +2,7 @@
   "authors": [
     "thoughtbot (http://thoughtbot.com)"
   ],
-  "description": "A simple and lightweight mixin library for Sass.",
+  "description": "A lightweight Sass tool set.",
   "homepage": "http://bourbon.io",
   "ignore": [
     "**/.*",

diff --git a/package.json b/package.json
@@ -6,7 +6,7 @@
   "bugs": {
     "url": "https://github.com/thoughtbot/bourbon/issues"
   },
-  "description": "A simple and lightweight mixin library for Sass.",
+  "description": "A lightweight Sass tool set.",
   "eyeglass": {
     "needs": "*",
     "exports": "eyeglass-exports.js"