Permalink
Browse files

Documentation

  • Loading branch information...
1 parent dcd72fe commit dd23fe031c60b255a01a0d36ba924231f268e0dc @jferris jferris committed Nov 11, 2010
Showing with 99 additions and 2 deletions.
  1. +97 −0 README.textile
  2. +2 −2 appraisal.gemspec
View
@@ -0,0 +1,97 @@
+h1. Appraisal
+
+Find out what your Ruby gems are worth.
+
+h2. Synopsis
+
+Appraisal integrates with bundler and rake to test your library against
+different versions of dependencies in repeatable scenarios called "appraisals."
+Appraisal is designed to make is easy to check for regressions in your library
+without interfering with day-to-day development using bundler.
+
+h2. Installation
+
+<pre>
+gem install appraisal
+</pre>
+
+h2. Setup
+
+Setting up appraisal requires an Appraisals file (similar to a Gemfile) in your
+project root, and some slight changes to your project's Rakefile.
+
+An Appraisals file consists of several appraisal definitions. An appraisal
+definition is simply a list of gem dependencies. For example, to test with a
+few versions of Rails:
+
+<pre>
+appraise "rails2" do
+ gem "rails", "2.3.9"
+end
+
+appraise "rails3" do
+ gem "rails", "3.0.0"
+end
+</pre>
+
+The dependencies in your Appraisals file are combined with dependencies in your
+Gemfile, so you don't need to repeat anything that's the same for each
+appraisal. If something is specified in both the Gemfile and an appraisal, the
+version from the appraisal takes precedence.
+
+Once you have an Appraisals file set up, just require appraisal in your Rakefile:
+
+<pre>
+require 'appraisal'
+</pre>
+
+It's also recommended that you setup bundler at the very top of your Rakefile,
+so that you don't need to constantly run bundle exec:
+
+<pre>
+require 'rubygems'
+require 'bundler/setup'
+</pre>
+
+h2. Usage
+
+Once you've configured the appraisals you want to use, you need to install the
+dependencies for each appraisal:
+
+<pre>
+rake appraisal:install
+</pre>
+
+This will resolve, install, and lock the dependencies for that appraisal using
+bundler. Once you have your dependencies setup, you can run any rake task in a
+single appraisal:
+
+<pre>
+rake appraisal:rails2 test
+</pre>
+
+This will run your "test" rake task using the dependencies configured for Rails
+2. You can also run each appraisal in turn:
+
+<pre>
+rake appraisal test
+</pre>
+
+If you want to use only the dependencies from your Gemfile, just run "rake
+test" as normal. This allows you to keep running with the latest versions of
+your dependencies in quick test runs, but keep running the tests in older
+versions to check for regressions.
+
+h2. Under the hood
+
+Running "rake appraisal:install" generates a Gemfile for each appraisal by
+combining your root Gemfile with the specific requirements for each appraisal.
+These are stored in the "gemfiles" directory, and should be added to version
+control to ensure that the same versions are always used. When running rake
+tasks for an appraisal, the rake task is run with the appropriate Gemfile for
+that appraisal, ensuring the correct dependencies are used.
+
+h2. Author
+
+Copyright 2010 Joe Ferris
+
View
@@ -1,8 +1,8 @@
Gem::Specification.new do |s|
s.name = %q{appraisal}
s.version = '0.1'
- s.summary = %q{Find out how much your Ruby gems are worth}
- s.description = %q{appraisal integrates with bundler and rake to test your library against different versions of dependencies in repeatable scenarios called "appraisals."}
+ s.summary = %q{Find out what your Ruby gems are worth}
+ s.description = %q{Appraisal integrates with bundler and rake to test your library against different versions of dependencies in repeatable scenarios called "appraisals."}
s.files = Dir['[A-Z]*', 'lib/**/*.rb', 'features/**/*']
s.require_path = 'lib'

0 comments on commit dd23fe0

Please sign in to comment.