ContributingPatches

rspec | rspec-rails | rspec-tmbundle | rspec-dev | contributing patches | rspec website | rspec at rubyforge

IMPORTANT: Instead of making a github pull request, please file a ticket at http://rspec.lighthouseapp.com.

Interested in contributing a patch to rspec, rspec-rails or the rspec-tmbundle? Here’s what you need to know.

Getting started – cloning the repositories

git-clone git://github.com/dchelimsky/rspec-dev.git
cd rspec-dev
rake git:update

This will pull down the rspec-dev repo and the others as submodules.

Once you’ve cloned the repos, you need to install some dependencies and configure a thing or two:

cd rspec-dev
rake install_dependencies
cd example_rails_app
rake rspec:generate_sqlite3_config
# or, if you prefer
rake rspec:generate_mysql_config
# or, if you prefer
rake rspec:generate_pgsql_config
# the last two require you setting up rspec_dev and rspec_test databases

Running the examples for everything in one shot

cd rspec-dev
rake pre_commit

Running the examples for individual submodules

The rspec and rspec-rails repositories live in example_rails_app/vendor/plugins. To run the examples for rspec (core), do the following (from rspec-dev):

cd example_rails_app/vendor/plugins/rspec
rake

To run the examples for rspec-rails, also from rspec-dev:

cd example_rails_app
rake rspec:pre_commit

This runs all the examples in the example_rails_app and in the plugin’s spec directory against 4 versions of rails (edge, 2.1.0, 2.0.2, and 1.2.6). To run against only one version, do this:

RSPEC_RAILS_VERSION=2.1.0 rake rspec:pre_commit

If you want to get more granular and run individual examples or spec files, you have to run rspec-rails’ bootstrap script first:

script/generate rspec

The reason this is necessary is that running rspec:pre_commit generates this in order to ensure that the generator works correctly. Once you do this, you can run the example_rails_app specs like so:

rake spec

You can run the specs in vendor/plugins/rspec-rails/spec like so:

rake spec:plugins:rspec_on_rails

(NOTE – this will soon change to rspec_rails and will be noted as such on this page).

To run individual examples or files and access all of the spec commands optional goodies, you can do this (for example):

script/spec vendor/plugins/rspec-rails/spec/rails/mocks/mock_model_spec.rb -cfs -e 'should say it is_a? if it is'

Autospec (RSpec’s autotest wrapper)

You can use autospec with the rspec suite like this:

cd example_rails_app/vendor/plugins/rspec
autospec

Autospec is not yet supported for running the example_rails_app or rspec-rails examples.

Clean histories when sharing changes

Also see Topic Branches

Please keep commit histories as clean as possible. This makes it easier for us to merge your changes into the official RSpec repo. If your commit histories contain junk, we’ll politely ask you to give us a cleaner history.

The easiest way to create a clean history is to make a new branch that tracks RSpec’s master branch, and then cherry-pick your own commits to it. For example, say you had a commit whose sha is abc123 that you’d like to contribute to RSpec. However you made a previous commit to your repo that would be irrelevant, but that would get pulled in when we pull from your repo.

Here’s how you would do it. This assumes that you have a remote reference named ‘rspec’, and a publically-available repository named ‘origin

git checkout -b myfix rspec/master
git cherry-pick abc123
git push origin myfix

This creates a branch named ‘myfix’ on your public repo. Now you can tell us to pull from that branch of your repository. Then once we’ve incorporated the change you’re free to delete the branch.

You don’t need to create a different branch for each fix. This would only apply if you’ve got commits in your repo that would be irrelevant for the fix you want to share.

More steps coming soon …

Lastly, either enter a ticket or modify and existing ticket at http://rspec.lighthouseapp.com with one of two things:

• A link to the relevant commit(s) in your own fork of any of the rspec repositories. These can be at github or any other public-facing git host.
• A git-formatted patch (created using git-format-patch). This can be uploaded as an attachment, or just pasted into the ticket.