Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 112 lines (76 sloc) 3.607 kB
f802918 @croaky README improvments, added MIT-LICENSE
croaky authored
1 Appraisal
2 =========
dd23fe0 @jferris Documentation
jferris authored
3
4 Find out what your Ruby gems are worth.
5
f802918 @croaky README improvments, added MIT-LICENSE
croaky authored
6 Synopsis
7 --------
dd23fe0 @jferris Documentation
jferris authored
8
9 Appraisal integrates with bundler and rake to test your library against
10 different versions of dependencies in repeatable scenarios called "appraisals."
11 Appraisal is designed to make is easy to check for regressions in your library
12 without interfering with day-to-day development using bundler.
13
f802918 @croaky README improvments, added MIT-LICENSE
croaky authored
14 Installation
15 ------------
dd23fe0 @jferris Documentation
jferris authored
16
e223b37 @croaky use Gemfile format in README instructions
croaky authored
17 In your Gemfile:
18
19 gem "appraisal"
dd23fe0 @jferris Documentation
jferris authored
20
f802918 @croaky README improvments, added MIT-LICENSE
croaky authored
21 Setup
22 -----
dd23fe0 @jferris Documentation
jferris authored
23
24 Setting up appraisal requires an Appraisals file (similar to a Gemfile) in your
1cc4c5b Indicate that the Appraisals file must be named "Appraisals" (case se…
Kate Gengler authored
25 project root, named "Appraisals" (note the case), and some slight changes to your project's Rakefile.
dd23fe0 @jferris Documentation
jferris authored
26
27 An Appraisals file consists of several appraisal definitions. An appraisal
28 definition is simply a list of gem dependencies. For example, to test with a
29 few versions of Rails:
30
f802918 @croaky README improvments, added MIT-LICENSE
croaky authored
31 appraise "rails2" do
32 gem "rails", "2.3.9"
33 end
dd23fe0 @jferris Documentation
jferris authored
34
f802918 @croaky README improvments, added MIT-LICENSE
croaky authored
35 appraise "rails3" do
36 gem "rails", "3.0.0"
37 end
dd23fe0 @jferris Documentation
jferris authored
38
39 The dependencies in your Appraisals file are combined with dependencies in your
40 Gemfile, so you don't need to repeat anything that's the same for each
41 appraisal. If something is specified in both the Gemfile and an appraisal, the
42 version from the appraisal takes precedence.
43
44 Once you have an Appraisals file set up, just require appraisal in your Rakefile:
45
f802918 @croaky README improvments, added MIT-LICENSE
croaky authored
46 require 'appraisal'
dd23fe0 @jferris Documentation
jferris authored
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
f802918 @croaky README improvments, added MIT-LICENSE
croaky authored
51 require 'rubygems'
52 require 'bundler/setup'
dd23fe0 @jferris Documentation
jferris authored
53
f802918 @croaky README improvments, added MIT-LICENSE
croaky authored
54 Usage
55 -----
dd23fe0 @jferris Documentation
jferris authored
56
57 Once you've configured the appraisals you want to use, you need to install the
58 dependencies for each appraisal:
59
f802918 @croaky README improvments, added MIT-LICENSE
croaky authored
60 rake appraisal:install
dd23fe0 @jferris Documentation
jferris authored
61
62 This will resolve, install, and lock the dependencies for that appraisal using
63 bundler. Once you have your dependencies setup, you can run any rake task in a
64 single appraisal:
65
f802918 @croaky README improvments, added MIT-LICENSE
croaky authored
66 rake appraisal:rails2 test
dd23fe0 @jferris Documentation
jferris authored
67
68 This will run your "test" rake task using the dependencies configured for Rails
69 2. You can also run each appraisal in turn:
70
f802918 @croaky README improvments, added MIT-LICENSE
croaky authored
71 rake appraisal test
dd23fe0 @jferris Documentation
jferris authored
72
73 If you want to use only the dependencies from your Gemfile, just run "rake
74 test" as normal. This allows you to keep running with the latest versions of
75 your dependencies in quick test runs, but keep running the tests in older
76 versions to check for regressions.
77
f802918 @croaky README improvments, added MIT-LICENSE
croaky authored
78 Under the hood
79 --------------
dd23fe0 @jferris Documentation
jferris authored
80
81 Running "rake appraisal:install" generates a Gemfile for each appraisal by
82 combining your root Gemfile with the specific requirements for each appraisal.
83 These are stored in the "gemfiles" directory, and should be added to version
84 control to ensure that the same versions are always used. When running rake
85 tasks for an appraisal, the rake task is run with the appropriate Gemfile for
86 that appraisal, ensuring the correct dependencies are used.
87
508f760 @jferris Added a note to the README about version control
jferris authored
88 Version Control
89 --------------
90
91 When using Appraisal, we recommend that you check your Gemfile.lock into
92 version control, as well as the gemfiles directory generated by Appraisal. This
93 will ensure that your tests are always green when you check out a fresh copy.
94 It also allows you to create reproducible regression tests for version-specific
95 bugs.
96
f802918 @croaky README improvments, added MIT-LICENSE
croaky authored
97 Credits
98 -------
dd23fe0 @jferris Documentation
jferris authored
99
f802918 @croaky README improvments, added MIT-LICENSE
croaky authored
100 ![thoughtbot](http://thoughtbot.com/images/tm/logo.png)
dd23fe0 @jferris Documentation
jferris authored
101
8b11ec8 @gabebw Even more appraisal, not diesel
gabebw authored
102 Appraisal is maintained and funded by [thoughtbot, inc](http://thoughtbot.com/community)
f802918 @croaky README improvments, added MIT-LICENSE
croaky authored
103
8b11ec8 @gabebw Even more appraisal, not diesel
gabebw authored
104 Thank you to all [the contributors](https://github.com/thoughtbot/appraisal/contributors)!
f802918 @croaky README improvments, added MIT-LICENSE
croaky authored
105
106 The names and logos for thoughtbot are trademarks of thoughtbot, inc.
107
108 License
109 -------
110
5325392 @croaky appraisal, not diesel
croaky authored
111 Appraisal is Copyright © 2011 Joe Ferris and thoughtbot. It is free software, and may be redistributed under the terms specified in the MIT-LICENSE file.
Something went wrong with that request. Please try again.