update contribution howto

This commit is contained in:
Chris Eppstein 2010-10-13 23:15:16 -07:00
parent 67da3ee809
commit fab2436c1e

View File

@ -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. seems harder than it aught to be, please let us know.
Step 1: If you do not have a github account, create one. 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? 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) * [Fix a typo (or some other trivial change)](#trivial-changes)
* [Documentation Changes](#documentation-changes) * [Documentation Changes](#documentation-changes)
* [Stylesheet Changes](#stylesheet-changes) * [Fixing Stylesheet Bugs](#stylesheet-bugs)
* [New Stylesheet Features](#stylesheet-changes)
* [Ruby Changes](#ruby-changes) * [Ruby Changes](#ruby-changes)
Here's some general information about the project you might find useful along the way: 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) * [Configuration](#configuration-architecture)
* [General Philosophy](#project-philosophy) * [General Philosophy](#project-philosophy)
* [Stylesheet Conventions](#api-conventions) * [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> <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> <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 where the documentation lives -- however much of the documentation is generated
from comments in the Sass files themselves. More information on [changing 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). [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> <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> <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 before building something. Please don't by shy; send an email to the [compass mailing
list](http://groups.google.com/group/compass-users). 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 $ git checkout -b new_branch_name
... make more commits if needed ... ... make more commits if needed ...
@ -72,10 +107,12 @@ mind that these changesets might be
[cherry-picked](#recovering-from-rebased-or-cherry-picked-changesets). [cherry-picked](#recovering-from-rebased-or-cherry-picked-changesets).
Once your changeset(s) are on github, select the appropriate branch containing your 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]. 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 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> <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> <h2 id="project-architecture">Project Architecture</h2>
@ -112,7 +175,14 @@ TODO
<h2 id="project-philosophy">General Philosophy</h2> <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> <h2 id="api-conventions">Stylesheet Conventions</h2>
@ -138,6 +208,50 @@ Getting recent changes from the main repo:
git fetch chriseppstein 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 <h3 id="recovering-from-rebased-or-cherry-picked-changesets">You cherry-picked/rebased
my changes. What should I do?</h3> my changes. What should I do?</h3>
Depending on any number of reasons, including but not limited to the alignment of the stars, Depending on any number of reasons, including but not limited to the alignment of the stars,
@ -156,4 +270,5 @@ a couple of ways you can react:
[pulls]: http://help.github.com/pull-requests/ [pulls]: http://help.github.com/pull-requests/
[issues]: http://github.com/chriseppstein/compass/issues [issues]: http://github.com/chriseppstein/compass/issues
[documentation]: http://github.com/chriseppstein/compass/blob/stable/doc-src/README.markdown [documentation]: http://github.com/chriseppstein/compass/blob/stable/doc-src/README.markdown
[bundler]: http://gembundler.com/