update contribution howto

doc-src/content/CONTRIBUTING.markdown

@@ -6,13 +6,16 @@ as we can for you to contribute changes to compass -- So if there's something he
 seems harder than it aught to be, please let us know.
 
 Step 1: If you do not have a github account, create one.
-Step 2: Fork Compass to your account.
+
+Step 2: Fork Compass to your account. Go to the [main repo](http://github.com/chriseppstein/compass)
+and click the fork button.
 
 Now we're at a decision point. What kind of change do you intend to make?
 
 * [Fix a typo (or some other trivial change)](#trivial-changes)
 * [Documentation Changes](#documentation-changes)
-* [Stylesheet Changes](#stylesheet-changes)
+* [Fixing Stylesheet Bugs](#stylesheet-bugs)
+* [New Stylesheet Features](#stylesheet-changes)
 * [Ruby Changes](#ruby-changes)
 
 Here's some general information about the project you might find useful along the way:
@@ -25,7 +28,11 @@ Here's some general information about the project you might find useful along th
   * [Configuration](#configuration-architecture)
 * [General Philosophy](#project-philosophy)
 * [Stylesheet Conventions](#api-conventions)
-* [In Case of Emergency](#faq)
+* [Miscellaneous Stuff](#faq)
+  * [Setting up Git](#setting-up-git)
+  * [Using Compass while Under Development](#running-local-code)
+  * [Running Tests](#running-tests)
+  * [Recovering from a cherry-pick or a rebase](#recovering-from-rebased-or-cherry-picked-changesets)
 
 <h2 id="trivial-changes">Making Trivial Changes</h2>
 
@@ -35,15 +42,43 @@ message, and click the `Commit` button. Now you need to get your change [accepte
 
 <h2 id="documentation-changes">Making Documentation Changes</h2>
 
-The compass documentation is stored in two places. First, the doc-src directory is
+The compass documentation is stored in two places. First, the `doc-src` directory is
 where the documentation lives -- however much of the documentation is generated
 from comments in the Sass files themselves. More information on [changing
-documentation][documentation]. Once your changes are pushed, you can
+documentation][documentation]. Once your changes are pushed, please
 [submit them](#patches).
 
+<h2 id="stylesheet-bugs">Fixing Stylesheet Bugs</h2>
+
+Step 3: If this is a bug you discovered. Please [report it][issues] before working on a fix.
+This helps us better understand the patch.
+
+Step 4: Get [the code](#setting-up-git) if you haven't yet done so.
+
+Step 5: Fix the bug.
+
+Step 6: Verify the fix in as many browsers as you can as well as against your own
+project. How to [use compass while changing it](#running-local-code).
+
+Step 7: Make sure the tests pass. More info on [running tests](#running-tests)
+If the tests fail, fix the tests or the stylesheets accordingly. If the tests, don't
+fail, that means this aspect was not well enough tested. Please [add or augment
+a test](#writing-tests).
+
+You're done. Please [submit your changes](#patches)
+
 <h2 id="stylesheet-changes">Making Stylesheet Changes</h2>
 
-TODO
+Step 3: Get [the code](#setting-up-git) if you haven't yet done so.
+
+Step 4: Add the feature -- contact the mailing list if you have any questions.
+
+Step 5: Add a test case. More info on [writing tests for compass](#writing-tests).
+
+Step 6: Documentation - Add or update the reference documentation. Add
+an example of using the feature. See the [doc readme for details][documentation].
+
+You're done. Please [submit your changes](#patches)
 
 <h2 id="ruby-changes">Making Ruby Changes</h2>
 
@@ -55,9 +90,9 @@ It is a good idea to discuss new features ideas with the compass users and devel
 before building something. Please don't by shy; send an email to the [compass mailing
 list](http://groups.google.com/group/compass-users).
 
-If you are submitting features that have more than one changeset, please create a topic
+If you are submitting features that have more than one changeset, please create a
-branch to hold the changes while they are pending merge and also to track iterations to
+topic branch to hold the changes while they are pending merge and also to track
-the original submission. To create a topic branch:
+iterations to the original submission. To create a topic branch:
 
     $ git checkout -b new_branch_name
     ... make more commits if needed ...
@@ -72,10 +107,12 @@ mind that these changesets might be
 [cherry-picked](#recovering-from-rebased-or-cherry-picked-changesets).
 
 Once your changeset(s) are on github, select the appropriate branch containing your
-changes and send a pull request. Most of the description of your changes should be
+changes and send a pull request. Make sure to choose the same upstream branch that
-in the commit messages -- so no need to write a whole lot in the pull request message.
+you developed against (probably stable or master). Most of the description of your
-However, the pull request message is a good place to provide a rationale or use case
+changes should be in the commit messages -- so no need to write a whole lot in the
-for the change if you think one is needed. More info on [pull requests][pulls].
+pull request message. However, the pull request message is a good place to provide a
+rationale or use case for the change if you think one is needed. More info on [pull
+requests][pulls].
 
 Pull requests are then managed like an issue from the [compass issues page][issues].
 A code review will be performed by a compass core team member, and one of three outcomes
@@ -92,7 +129,33 @@ will result:
 
 <h2 id="project-structure">Project Structure</h2>
 
-TODO
+    compass/
+      bin/
+        compass             - CLI executable
+      devbin/               - development scripts after installing the bundle
+      doc-src/              - source for documentation
+      docs/                 - generated documentation
+      examples/             - fully working compass projects that you can explore
+      features/             - tests for compass
+      frameworks/           - All frameworks in this directory are loaded automatically
+        compass/            - The compass framework
+          stylesheets/      - The compass libraries
+          templates/        - The compass project templates and patterns
+        blueprint/
+          stylesheets/      - The blueprint libraries
+          templates/        - The blueprint project templates and patterns
+      lib/
+        compass.rb          - The main compass ruby library
+        compass/
+          app_integration/  - integration with app frameworks
+          commands/         - UI agnostic support for the CLI
+          configuration/    - support for project configuration
+          exec/             - UI code for the CLI
+          installers/       - support for installing templates
+          sass_extensions/  - enhancements to Sass
+            functions/      - Sass functions exposed by compass
+            monkey_patches/ - Changes to sass itself
+      test/                 - unit tests
 
 <h2 id="project-architecture">Project Architecture</h2>
 
@@ -112,7 +175,14 @@ TODO
 
 <h2 id="project-philosophy">General Philosophy</h2>
 
-TODO
+1. Users specify their own selectors. Compass never forces a user
+   to use a presentational class name.
+2. Compass frameworks are not special. If compass can do it, so should an extension
+   be able.
+3. Sass is awesome -- Compass should make sass more accessible and
+   demonstrate how to use Sass to it's fullest potential.
+4. Developing across browsers is hard and will always be hard. It takes
+   a community to get it right.
 
 <h2 id="api-conventions">Stylesheet Conventions</h2>
 
@@ -138,6 +208,50 @@ Getting recent changes from the main repo:
 
     git fetch chriseppstein
 
+<h3 id="running-local-code">Using Compass while Under Development</h3>
+
+1. Use the bin script. `$PROJECT_ROOT/bin/compass` is a version of the compass
+   command line that uses the local changes you have made. You can add `$PROJECT_ROOT/bin`
+   to your `$PATH`, or refer to it directly.
+2. Build and install a gem:
+   1. Edit VERSION.yml and add a build indicator like so (**Do not commit this change**):
+      
+          --- 
+          :major: 0
+          :minor: 10
+          :patch: 6
+          :build: something-uniq-to-me.1
+      
+     
+   2. `gem build compass.gemspec`
+   3. `gem install compass-0.10.6.something-uniq-to-me.1.gem` -- If installing to your
+      system gems, you'll probably need to add `sudo` to the front. If you don't know
+      what that means, you probably need to add `sudo` to the front.
+3. In a [bundled][bundler] environment, you can configure your gem to use compass
+   while you work on it like so:
+   
+       gem 'compass', :path => "/Users/myusername/some/path/to/compass"
+   
+   Bundler will perform some sort of charm on ruby to make it work.
+4. Configuring ruby directly. If you're a ruby pro, you probably don't need to be
+   told that you can set compass on the load path like so:
+   
+       export RUBYLIB=/Users/myusername/some/path/to/compass/lib
+
+<h3 id="running-tests">Running Tests</h3>
+
+1. Install development dependencies:
+   
+       bundle install --binstubs devbin
+   
+2. Running core library and stylesheet tests:
+   
+       rake run_tests
+
+3. Running behavior tests
+   
+       ./devbin/cucumber
+
 <h3 id="recovering-from-rebased-or-cherry-picked-changesets">You cherry-picked/rebased
 my changes. What should I do?</h3>
 Depending on any number of reasons, including but not limited to the alignment of the stars,
@@ -157,3 +271,4 @@ a couple of ways you can react:
 [pulls]: http://help.github.com/pull-requests/
 [issues]: http://github.com/chriseppstein/compass/issues
 [documentation]: http://github.com/chriseppstein/compass/blob/stable/doc-src/README.markdown
+[bundler]: http://gembundler.com/