Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Documentation

  • Loading branch information...
commit dd23fe031c60b255a01a0d36ba924231f268e0dc 1 parent dcd72fe
Joe Ferris authored November 11, 2010
97  README.textile
Source Rendered
... ...
@@ -0,0 +1,97 @@
  1
+h1. Appraisal
  2
+
  3
+Find out what your Ruby gems are worth.
  4
+
  5
+h2. Synopsis
  6
+
  7
+Appraisal integrates with bundler and rake to test your library against
  8
+different versions of dependencies in repeatable scenarios called "appraisals."
  9
+Appraisal is designed to make is easy to check for regressions in your library
  10
+without interfering with day-to-day development using bundler.
  11
+
  12
+h2. Installation
  13
+
  14
+<pre>
  15
+gem install appraisal
  16
+</pre>
  17
+
  18
+h2. Setup
  19
+
  20
+Setting up appraisal requires an Appraisals file (similar to a Gemfile) in your
  21
+project root, and some slight changes to your project's Rakefile.
  22
+
  23
+An Appraisals file consists of several appraisal definitions. An appraisal
  24
+definition is simply a list of gem dependencies. For example, to test with a
  25
+few versions of Rails:
  26
+
  27
+<pre>
  28
+appraise "rails2" do
  29
+  gem "rails", "2.3.9"
  30
+end
  31
+
  32
+appraise "rails3" do
  33
+  gem "rails", "3.0.0"
  34
+end
  35
+</pre>
  36
+
  37
+The dependencies in your Appraisals file are combined with dependencies in your
  38
+Gemfile, so you don't need to repeat anything that's the same for each
  39
+appraisal. If something is specified in both the Gemfile and an appraisal, the
  40
+version from the appraisal takes precedence.
  41
+
  42
+Once you have an Appraisals file set up, just require appraisal in your Rakefile:
  43
+
  44
+<pre>
  45
+require 'appraisal'
  46
+</pre>
  47
+
  48
+It's also recommended that you setup bundler at the very top of your Rakefile,
  49
+so that you don't need to constantly run bundle exec:
  50
+
  51
+<pre>
  52
+require 'rubygems'
  53
+require 'bundler/setup'
  54
+</pre>
  55
+
  56
+h2. Usage
  57
+
  58
+Once you've configured the appraisals you want to use, you need to install the
  59
+dependencies for each appraisal:
  60
+
  61
+<pre>
  62
+rake appraisal:install
  63
+</pre>
  64
+
  65
+This will resolve, install, and lock the dependencies for that appraisal using
  66
+bundler. Once you have your dependencies setup, you can run any rake task in a
  67
+single appraisal:
  68
+
  69
+<pre>
  70
+rake appraisal:rails2 test
  71
+</pre>
  72
+
  73
+This will run your "test" rake task using the dependencies configured for Rails
  74
+2. You can also run each appraisal in turn:
  75
+
  76
+<pre>
  77
+rake appraisal test
  78
+</pre>
  79
+
  80
+If you want to use only the dependencies from your Gemfile, just run "rake
  81
+test" as normal. This allows you to keep running with the latest versions of
  82
+your dependencies in quick test runs, but keep running the tests in older
  83
+versions to check for regressions.
  84
+
  85
+h2. Under the hood
  86
+
  87
+Running "rake appraisal:install" generates a Gemfile for each appraisal by
  88
+combining your root Gemfile with the specific requirements for each appraisal.
  89
+These are stored in the "gemfiles" directory, and should be added to version
  90
+control to ensure that the same versions are always used. When running rake
  91
+tasks for an appraisal, the rake task is run with the appropriate Gemfile for
  92
+that appraisal, ensuring the correct dependencies are used.
  93
+
  94
+h2. Author
  95
+
  96
+Copyright 2010 Joe Ferris
  97
+
4  appraisal.gemspec
... ...
@@ -1,8 +1,8 @@
1 1
 Gem::Specification.new do |s|
2 2
     s.name        = %q{appraisal}
3 3
     s.version     = '0.1'
4  
-    s.summary     = %q{Find out how much your Ruby gems are worth}
5  
-    s.description = %q{appraisal integrates with bundler and rake to test your library against different versions of dependencies in repeatable scenarios called "appraisals."}
  4
+    s.summary     = %q{Find out what your Ruby gems are worth}
  5
+    s.description = %q{Appraisal integrates with bundler and rake to test your library against different versions of dependencies in repeatable scenarios called "appraisals."}
6 6
 
7 7
     s.files        = Dir['[A-Z]*', 'lib/**/*.rb', 'features/**/*']
8 8
     s.require_path = 'lib'

0 notes on commit dd23fe0

Please sign in to comment.
Something went wrong with that request. Please try again.