update contribution howto
This commit is contained in:
Chris Eppstein
parent
67da3ee809
commit
fab2436c1e
@ -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
|
||||
branch to hold the changes while they are pending merge and also to track iterations to
|
||||
the original submission. To create a topic branch:
|
||||
If you are submitting features that have more than one changeset, please create a
|
||||
topic branch to hold the changes while they are pending merge and also to track
|
||||
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
|
||||
in the commit messages -- so no need to write a whole lot in the 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].
|
||||
changes and send a pull request. Make sure to choose the same upstream branch that
|
||||
you developed against (probably stable or master). Most of the description of your
|
||||
changes should be in the commit messages -- so no need to write a whole lot in the
|
||||
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,
|
||||
@ -156,4 +270,5 @@ 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
|
||||
[documentation]: http://github.com/chriseppstein/compass/blob/stable/doc-src/README.markdown
|
||||
[bundler]: http://gembundler.com/
|
||||
Loading…
Reference in New Issue
Block a user