Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 167 lines (115 sloc) 5.493 kb
5545140 Prem Sichanugrist Update README
sikachu authored
1 Appraisal
2 =========
3
4 [![Build Status][Build Status Image]][Build Status]
dd23fe0 Joe Ferris Documentation
jferris authored
5
6 Find out what your Ruby gems are worth.
7
5545140 Prem Sichanugrist Update README
sikachu authored
8 [Build Status Image]: https://secure.travis-ci.org/thoughtbot/appraisal.png?branch=master
9 [Build Status]: http://travis-ci.org/thoughtbot/appraisal
10
f802918 Dan Croak README improvments, added MIT-LICENSE
croaky authored
11 Synopsis
12 --------
dd23fe0 Joe Ferris Documentation
jferris authored
13
14 Appraisal integrates with bundler and rake to test your library against
15 different versions of dependencies in repeatable scenarios called "appraisals."
1883b80 Brian Cardarella Grammar correction
bcardarella authored
16 Appraisal is designed to make it easy to check for regressions in your library
5545140 Prem Sichanugrist Update README
sikachu authored
17 without interfering with day-to-day development using Bundler.
dd23fe0 Joe Ferris Documentation
jferris authored
18
f802918 Dan Croak README improvments, added MIT-LICENSE
croaky authored
19 Installation
20 ------------
dd23fe0 Joe Ferris Documentation
jferris authored
21
e223b37 Dan Croak use Gemfile format in README instructions
croaky authored
22 In your Gemfile:
23
24 gem "appraisal"
dd23fe0 Joe Ferris Documentation
jferris authored
25
c03c964 Prem Sichanugrist Remove trailing space from README.md
sikachu authored
26 Note that gems must be bundled in the global namespace. Bundling gems to a local
f6f9a8c Phill Baker Add description of known Bundle installation limitation.
phillbaker authored
27 location or vendoring plugins is not supported. If you do not want to pollute the
28 global namespace, one alternative is [RVM's Gemsets](http://rvm.io/gemsets).
29
f802918 Dan Croak README improvments, added MIT-LICENSE
croaky authored
30 Setup
31 -----
dd23fe0 Joe Ferris Documentation
jferris authored
32
33 Setting up appraisal requires an Appraisals file (similar to a Gemfile) in your
5545140 Prem Sichanugrist Update README
sikachu authored
34 project root, named "Appraisals" (note the case), and some slight changes to
35 your project's Rakefile.
dd23fe0 Joe Ferris Documentation
jferris authored
36
37 An Appraisals file consists of several appraisal definitions. An appraisal
38 definition is simply a list of gem dependencies. For example, to test with a
39 few versions of Rails:
40
5545140 Prem Sichanugrist Update README
sikachu authored
41 appraise "rails-3" do
42 gem "rails", "3.2.14"
f802918 Dan Croak README improvments, added MIT-LICENSE
croaky authored
43 end
dd23fe0 Joe Ferris Documentation
jferris authored
44
5545140 Prem Sichanugrist Update README
sikachu authored
45 appraise "rails-4" do
46 gem "rails", "4.0.0"
f802918 Dan Croak README improvments, added MIT-LICENSE
croaky authored
47 end
dd23fe0 Joe Ferris Documentation
jferris authored
48
49 The dependencies in your Appraisals file are combined with dependencies in your
50 Gemfile, so you don't need to repeat anything that's the same for each
51 appraisal. If something is specified in both the Gemfile and an appraisal, the
52 version from the appraisal takes precedence.
53
54 It's also recommended that you setup bundler at the very top of your Rakefile,
55 so that you don't need to constantly run bundle exec:
56
5545140 Prem Sichanugrist Update README
sikachu authored
57 require "rubygems"
58 require "bundler/setup"
dd23fe0 Joe Ferris Documentation
jferris authored
59
f802918 Dan Croak README improvments, added MIT-LICENSE
croaky authored
60 Usage
61 -----
dd23fe0 Joe Ferris Documentation
jferris authored
62
63 Once you've configured the appraisals you want to use, you need to install the
64 dependencies for each appraisal:
65
5545140 Prem Sichanugrist Update README
sikachu authored
66 appraisal install
dd23fe0 Joe Ferris Documentation
jferris authored
67
68 This will resolve, install, and lock the dependencies for that appraisal using
5545140 Prem Sichanugrist Update README
sikachu authored
69 bundler. Once you have your dependencies set up, you can run any command in a
dd23fe0 Joe Ferris Documentation
jferris authored
70 single appraisal:
71
5545140 Prem Sichanugrist Update README
sikachu authored
72 appraisal rails-3 rake test
dd23fe0 Joe Ferris Documentation
jferris authored
73
5545140 Prem Sichanugrist Update README
sikachu authored
74 This will run `rake test` using the dependencies configured for Rails 3. You can
75 also run each appraisal in turn:
dd23fe0 Joe Ferris Documentation
jferris authored
76
5545140 Prem Sichanugrist Update README
sikachu authored
77 appraisal rake test
dd23fe0 Joe Ferris Documentation
jferris authored
78
5545140 Prem Sichanugrist Update README
sikachu authored
79 If you want to use only the dependencies from your Gemfile, just run `rake
80 test` as normal. This allows you to keep running with the latest versions of
dd23fe0 Joe Ferris Documentation
jferris authored
81 your dependencies in quick test runs, but keep running the tests in older
82 versions to check for regressions.
83
5545140 Prem Sichanugrist Update README
sikachu authored
84 In the case that you want to run all the appraisals by default when you run
85 `rake`, you can override your default Rake task by put this into your Rakefile:
86
87 if !ENV["APPRAISAL_INITIALIZED"] && !ENV["TRAVIS"]
88 task :default => :appraisal
89 end
90
91 (Appraisal sets `APPRAISAL_INITIALIZED` environment variable when it runs your
92 process. We put a check here to ensure that `appraisal rake` command should run
93 your real default task, which usually is your `test` task.)
94
95 Note that this may conflict with your CI setup if you decide to split the test
96 into multiple processes by Appraisal and you are using `rake` to run tests by
97 default. Please see **Travis CI Integration** for more detail.
98
f802918 Dan Croak README improvments, added MIT-LICENSE
croaky authored
99 Under the hood
100 --------------
dd23fe0 Joe Ferris Documentation
jferris authored
101
5545140 Prem Sichanugrist Update README
sikachu authored
102 Running `appraisal install` generates a Gemfile for each appraisal by combining
103 your root Gemfile with the specific requirements for each appraisal. These are
104 stored in the `gemfiles` directory, and should be added to version control to
105 ensure that the same versions are always used.
106
107 When you prefix a command with `appraisal`, the command is run with the
108 appropriate Gemfile for that appraisal, ensuring the correct dependencies
109 are used.
dd23fe0 Joe Ferris Documentation
jferris authored
110
508f760 Joe Ferris Added a note to the README about version control
jferris authored
111 Version Control
80ab4e0 Prem Sichanugrist Add example on how to config Travis CI
sikachu authored
112 ---------------
508f760 Joe Ferris Added a note to the README about version control
jferris authored
113
5545140 Prem Sichanugrist Update README
sikachu authored
114 When using Appraisal, we recommend you check in the Gemfiles that Appraisal
115 generates within the gemfiles directory, but exclude the lockfiles there
116 (`*.gemfile.lock`.) The Gemfiles are useful when running your tests against a
117 continuous integration server such as [Travis CI][Travis CI].
118
119 [Travis CI]: https://travis-ci.org
508f760 Joe Ferris Added a note to the README about version control
jferris authored
120
80ab4e0 Prem Sichanugrist Add example on how to config Travis CI
sikachu authored
121 Travis CI integration
122 ---------------------
123
124 If you're using Appraisal and using Travis CI, we're recommending you to setup
125 Travis to run the test against multiple generated Gemfiles. This can be done
126 by using `gemfile` setting:
127
128 # In .travis.yml
129 gemfile:
130 - gemfiles/3.0.gemfile
131 - gemfiles/3.1.gemfile
132 - gemfiles/3.2.gemfile
133
134 Please note that if you've set your default rake task to run the test against
135 all versions of its dependency, you might have to set a `script` setting:
136
5545140 Prem Sichanugrist Update README
sikachu authored
137 script: "bundle exec rake test"
138
80ab4e0 Prem Sichanugrist Add example on how to config Travis CI
sikachu authored
139 That will make sure that each of the test sub-job are not getting run more than
140 one time.
141
ae3875f Prem Sichanugrist Reword suggestion about WWTD
sikachu authored
142 You can also running your test against multiple versions of Ruby locally, just
143 like running on Travis CI, by using [WWTD].
144
145 [WWTD]: https://github.com/grosser/wwtd
f5d799d Michael Grosser Mention `wwtd` for testing against multiple Rubies
grosser authored
146
f802918 Dan Croak README improvments, added MIT-LICENSE
croaky authored
147 Credits
148 -------
dd23fe0 Joe Ferris Documentation
jferris authored
149
f802918 Dan Croak README improvments, added MIT-LICENSE
croaky authored
150 ![thoughtbot](http://thoughtbot.com/images/tm/logo.png)
dd23fe0 Joe Ferris Documentation
jferris authored
151
5545140 Prem Sichanugrist Update README
sikachu authored
152 Appraisal is maintained and funded by [thoughtbot, inc][thoughtbot]
f802918 Dan Croak README improvments, added MIT-LICENSE
croaky authored
153
5545140 Prem Sichanugrist Update README
sikachu authored
154 Thank you to all [the contributors][contributors]
f802918 Dan Croak README improvments, added MIT-LICENSE
croaky authored
155
156 The names and logos for thoughtbot are trademarks of thoughtbot, inc.
157
5545140 Prem Sichanugrist Update README
sikachu authored
158 [thoughtbot]: http://thoughtbot.com/community
159 [contributors]: https://github.com/thoughtbot/appraisal/contributors
160
f802918 Dan Croak README improvments, added MIT-LICENSE
croaky authored
161 License
162 -------
163
5545140 Prem Sichanugrist Update README
sikachu authored
164 Appraisal is Copyright © 2010-2013 Joe Ferris and thoughtbot, inc. It is free
165 software, and may be redistributed under the terms specified in the MIT-LICENSE
166 file.
Something went wrong with that request. Please try again.