-
Notifications
You must be signed in to change notification settings - Fork 2
Expand file tree
/
Copy pathmanaging-rails-versions-gems.html
More file actions
268 lines (268 loc) · 21.1 KB
/
managing-rails-versions-gems.html
File metadata and controls
268 lines (268 loc) · 21.1 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
<!DOCTYPE html>
<!--[if IE 9]><html class="lt-ie10" lang="en" > <![endif]-->
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<title>Managing Rails Versions and Gems · RailsApps</title>
<meta name="viewport" content="width=device-width">
<link href="https://plus.google.com/117374718581973393536" rel="publisher">
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/foundation/5.2.2/css/normalize.css">
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/foundation/5.2.2/css/foundation.min.css">
<link rel="stylesheet" href="http://railsapps.github.io/css/railsapps.css" />
<link rel="stylesheet" href="http://railsapps.github.io/css/syntax.css" />
<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/modernizr/2.6.2/modernizr.min.js"></script>
<script>!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0];if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src="http://platform.twitter.com/widgets.js";fjs.parentNode.insertBefore(js,fjs);}}(document,"script","twitter-wjs");</script>
<script type="text/javascript">
window.analytics=window.analytics||[],window.analytics.methods=["identify","group","track","page","pageview","alias","ready","on","once","off","trackLink","trackForm","trackClick","trackSubmit"],window.analytics.factory=function(t){return function(){var a=Array.prototype.slice.call(arguments);return a.unshift(t),window.analytics.push(a),window.analytics}};for(var i=0;i<window.analytics.methods.length;i++){var key=window.analytics.methods[i];window.analytics[key]=window.analytics.factory(key)}window.analytics.load=function(t){if(!document.getElementById("analytics-js")){var a=document.createElement("script");a.type="text/javascript",a.id="analytics-js",a.async=!0,a.src=("https:"===document.location.protocol?"https://":"http://")+"cdn.segment.io/analytics.js/v1/"+t+"/analytics.min.js";var n=document.getElementsByTagName("script")[0];n.parentNode.insertBefore(a,n)}},window.analytics.SNIPPET_VERSION="2.0.9",
window.analytics.load("l1stqfqqbf");
window.analytics.page();
window.analytics.ready(function () {
ga('require', 'linker');
ga('linker:autoLink', ['railscomposer.com','learn-rails.com','blog.railsapps.org','tutorials.railsapps.org']);
});
</script>
</head>
<body>
<div class="fixed">
<nav class="top-bar" data-topbar>
<ul class="title-area">
<li class="name">
<a href="http://railsapps.github.io/" class="brand">RailsApps Project</a>
</li>
<li class="toggle-topbar menu-icon"><a href="#"><span>Menu</span></a></li>
</ul>
<section class="top-bar-section">
<ul class="right">
<li><a href="https://tutorials.railsapps.org/" class="google">Tutorials</a></li>
<li><a href="http://twitter.com/rails_apps" class="twitter">Twitter</a></li>
<li><a href="http://blog.railsapps.org/" class="twitter">Blog</a></li>
<li><a href="https://github.com/RailsApps" class="github">GitHub Repository</a></li>
</ul>
</section>
</nav>
</div>
<div class="row">
<div class="large-12 columns">
<div class="content wikistyle gollum textile">
<h1>Managing Rails Versions and Gems</h1>
<h4>by Daniel Kehoe</h4>
<p><em>Last updated 7 January 2017</em></p>
<p>Learn tips and tricks for managing Rails and Ruby gems. Relieve your headaches when versions collide.</p>
<p>This is a guide for developers using the example apps from the <a href="http://railsapps.github.io/">Rails Apps</a> repository. Others may find it helpful as well.</p>
<p>Before you install one of the <a href="https://github.com/RailsApps">Rails example apps</a>, there are a few things you should know about managing the pieces of the Rails platform. Often, everything “just works,” but when it doesn’t, here’s what you need to review. Read on if you’d like to know how all the moving parts work together.</p>
<p>If you’re new to Rails, see <a href="http://railsapps.github.io/what-is-ruby-rails.html">What is Ruby on Rails?</a>, the book <a href="http://learn-rails.com/learn-ruby-on-rails.html">Learn Ruby on Rails</a>, and recommendations for a <a href="https://tutorials.railsapps.org/rails-tutorial">Rails tutorial</a>.</p>
<h2>Install Rails</h2>
<p>See <a href="http://railsapps.github.io/installing-rails.html">Installing Rails</a> for detailed instructions and advice.</p>
<h2>Example Apps</h2>
<p>The example apps from the <a href="http://railsapps.github.io/">Rails Apps</a> repository help you keep current with changing Rails and gem versions.</p>
<p>Each example provides a set of useful, popular Rails gems integrated into a working application. Each example is known to work and can serve as your personal “reference implementation”. Each is an open source project. Many developers use the apps, report problems as they arise, and propose solutions as GitHub issues.</p>
<p>These examples provide a working <strong>Rails app</strong> with a <strong>detailed tutorial</strong> that can be used to create a <strong>starter app</strong>. Each of these example apps can be created using the <a href="http://railsapps.github.io/rails-composer/">Rails Composer</a> tool (“like the ‘rails new’ command on steroids”):</p>
<table>
<tr>
<th>Example Applications for Rails </th>
<th>Tutorial </th>
<th>Comments </th>
</tr>
<tr>
<td> <a href="https://github.com/RailsApps/learn-rails">Learn Rails</a> </td>
<td> <a href="http://learn-rails.com/learn-ruby-on-rails.html">Learn Ruby on Rails</a> </td>
<td> introduction to Rails for beginners </td>
</tr>
<tr>
<td> <a href="https://github.com/RailsApps/rails-bootstrap">Rails and Bootstrap</a> </td>
<td> <a href="http://railsapps.github.io/rails-bootstrap">Rails Bootstrap Tutorial</a> </td>
<td> starter app for Rails and Bootstrap </td>
</tr>
<tr>
<td> <a href="https://github.com/RailsApps/rails-foundation">Rails and Foundation</a> </td>
<td> <a href="http://railsapps.github.io/rails-foundation">Rails Foundation Tutorial</a> </td>
<td> starter app for Rails and Zurb Foundation </td>
</tr>
<tr>
<td> <a href="https://github.com/RailsApps/rails-mailinglist-activejob">Mailing List with Active Job</a> </td>
<td> <a href="http://railsapps.github.io/rails-mailinglist-activejob">Mailing List with Active Job Tutorial</a> </td>
<td> background processing </td>
</tr>
<tr>
<td> <a href="https://github.com/RailsApps/rails-omniauth">OmniAuth and Rails</a> </td>
<td> <a href="http://railsapps.github.io/rails-omniauth/">OmniAuth Tutorial</a> </td>
<td> OmniAuth for authentication </td>
</tr>
<tr>
<td> <a href="https://github.com/RailsApps/rails-devise">Devise and Rails</a> </td>
<td> <a href="http://railsapps.github.io/rails-devise">Devise Tutorial</a> </td>
<td> Devise for authentication </td>
</tr>
<tr>
<td> <a href="https://github.com/RailsApps/rails-devise-role">Role-Based Authorization</a> </td>
<td> <a href="http://railsapps.github.io/rails-devise-roles">Role-Based Authorization Tutorial</a> </td>
<td> Simple authorization </td>
</tr>
<tr>
<td> <a href="https://github.com/RailsApps/rails-devise-pundit">Pundit and Rails</a> </td>
<td> <a href="http://railsapps.github.io/rails-devise-pundit">Rails Pundit Tutorial</a> </td>
<td> Pundit for authorization </td>
</tr>
<tr>
<td> <a href="https://github.com/RailsApps/rails-signup-download">Sign Up and Download</a> </td>
<td> <a href="http://railsapps.github.io/rails-signup-download">Sign Up and Download Tutorial</a> </td>
<td> Devise with authorization to download a <span class="caps">PDF</span> file </td>
</tr>
<tr>
<td> <a href="https://github.com/RailsApps/rails-stripe-checkout">Stripe Checkout</a> </td>
<td> <a href="http://railsapps.github.io/rails-stripe-checkout">Stripe Checkout Tutorial</a> </td>
<td> selling a product with Stripe Checkout </td>
</tr>
</table>
<h2>Ruby</h2>
<p>Ruby is the programming language used for Rails projects.</p>
<p>What version of Ruby is installed on your machine? Check with:</p>
<p><code>$ ruby -v</code></p>
<p>Make sure it is the most recent version of Ruby.</p>
<p>You can check for the current <a href="http://www.ruby-lang.org/en/downloads/">recommended version of Ruby</a>.</p>
<p>See instructions for <a href="http://railsapps.github.io/installing-rails.html">Installing Rails</a> to install a newer version of Ruby if necessary.</p>
<h2>RubyGems</h2>
<p>RubyGems is a package management framework for Ruby. A gem is a packaged Ruby application or library. You can <a href="http://docs.rubygems.org/shelf/index">read more about gems</a> if you wish. Gems come from a wonderful pool of open source love but can be a headache to track and integrate.</p>
<p>The RubyGems package management system comes as part of a standard Ruby language installation.</p>
<p>What version of the RubyGems system is installed on your machine? Check with:</p>
<p><code>$ gem -v</code></p>
<p>Use <code>gem update --system</code> to upgrade the RubyGems system.</p>
<h2>Rails</h2>
<p>Rails itself is a gem, which means it can be installed and updated like any other gem.</p>
<p>What version of Rails is installed on your machine? Check with:</p>
<p><code>$ rails -v</code></p>
<p>You can check for the newest released <a href="https://rubygems.org/gems/rails">Rails version</a>.</p>
<p>See instructions for <a href="http://railsapps.github.io/installing-rails.html">Installing Rails</a> to install or update Rails. I recommend that you create a new gemset using <a href="http://rvm.beginrescueend.com/">rvm</a> before installing a new version of Rails (rather than using <code>gem update rails</code>). With rvm, you can switch gemsets to run your application under an earlier version of Rails.</p>
<h2>Bundler and the Gemfile</h2>
<p>The <a href="http://gembundler.com/">Ruby Bundler</a> manages an application’s gems. Bundler works by reading a <strong>Gemfile</strong> in an application’s root directory, downloading and unpacking specified versions of each required gem, resolving any dependencies among gems, and creating a <strong>Gemfile.lock</strong> file to force use of the specified gem versions.</p>
<p>Each of the example apps is provided with a gemfile that specifies a known working set of required gems.</p>
<p>After creating an example app, run <code>bundle install</code> to install all the necessary gems.</p>
<p>If you add a new gem to the gemfile, run <code>bundle install</code> again.</p>
<p>If you want to force an upgrade to all the gems that have newer versions, run <code>bundle update</code>. When you update a gem, bundler will not update a dependency of that gem if another gem still depends on it.</p>
<h4>Gem Version Constraint</h4>
<p>You will specify the gems you need in your application’s Gemfile. If you don’t specify a version, your application will use the newest gem version installed on your machine.</p>
<p>If you run <code>bundle update</code>, each gem will be updated to the newest available. You may benefit from the features (or the bug fixes) of the newest version. Or you may discover integration issues with other gems which cause failures. To avoid surprises and manage gem updates cautiously, you can specify gem versions in your Gemfile (<a href="http://docs.rubygems.org/read/chapter/16">described in the RubyGems manual</a>).</p>
<h4>Optimistic Version Constraint</h4>
<p>In the gemfiles for the example apps, you’ll often see “optimistic version constraint” specified with the <code>>=</code> operator like this:</p>
<p><code>gem 'devise', '>= 1.3.4'</code></p>
<p>This means, “use any version of the Devise gem that is newer than version 1.3.4.” It will force an upgrade of the Devise gem to version 1.3.4 the first time you run <code>bundle update</code> and check and install newer versions each subsequent time you run <code>bundle update</code>. That’s a good scheme for keeping your gems up-to-date unless there is a known issue with a gem.</p>
<h4>Pessimistic Version Constraint</h4>
<p>In the some gemfiles you may see “pessimistic version constraint” like this:</p>
<p><code>gem 'library', '~> 2.2'</code></p>
<p>which is shorthand for</p>
<p><code>gem 'library', '>= 2.2.0', '< 3.0'</code></p>
<p>which means use any gem version newer than 2.2.0 but don’t install 3.0 or anything newer.</p>
<p>We seldom specify pessimistic version constraint for gems in the example apps unless a gem developer recommends it.</p>
<p>See recommendations about using pessimistic version constraint in a blog post by Dan Croak titled <a href="http://robots.thoughtbot.com/post/2508037841/twiddle-wakka">Twiddle Wakka</a> (yes, the <code>~></code> operator is variously known as the “twiddle wakka,” “tildemator,” or “spermy operator.”)</p>
<h4>Absolute Version Constraint</h4>
<p>In the example apps, we use “absolute version constraint” to specify a known working version of a gem if we’ve seen reported problems with newer versions. Absolute version constraint looks like this:</p>
<p><code>gem 'library', '2.2'</code></p>
<h2>Using rvm to Manage Multiple Versions of Rails</h2>
<p>I recommend installing rvm, the <a href="http://rvm.beginrescueend.com/">Ruby Version Manager</a>. It’s essential if you must use multiple versions of Rails. And rvm makes it easy to switch sets of gems if you suspect a problem with incompatibilities among gems.</p>
<h4>Install <span class="caps">RVM</span>
</h4>
<p>The rvm website explains <a href="https://rvm.beginrescueend.com/rvm/install/">how to install rvm</a>.</p>
<h4>Create a Gemset for a Project</h4>
<p>See instructions for <a href="http://railsapps.github.io/installing-rails.html">Installing Rails</a> to install Rails and create a new gemset using rvm.</p>
<h4>Setting a Project-Specific Gemset</h4>
<p><span class="caps">RVM</span> recognizes <strong>.ruby-version</strong> and <strong>.ruby-gemset</strong> files in a directory and loads a specified gemset.</p>
<p>Here’s how to create <strong>.ruby-version</strong> and <strong>.ruby-gemset</strong> files if you’re using a gemset named “ruby-2.2.0@myapp”:</p>
<pre>
$ echo "ruby-2.4.0" > .ruby-version
$ echo "myapp" > .ruby-gemset
</pre>
<p>Using <strong>.ruby-version</strong> and <strong>.ruby-gemset</strong> files means you’ll automatically be using the correct Rails and gem version when you run your application on your local machine. This works best if you create an rvm gemset specifically for your application.</p>
</div>
<div class="comments" id="comments">
<div class="content wikistyle gollum">
<h2>Comments</h2>
</div>
<p>Is this helpful? Your encouragement fuels the project. Please tweet or add a comment. Couldn't get something to work? For the example apps and tutorials, it's best to open an issue on GitHub so we can help you.</p>
<div id="disqus_thread"></div>
<script type="text/javascript">
/* * * CONFIGURATION VARIABLES: EDIT BEFORE PASTING INTO YOUR WEBPAGE * * */
var disqus_shortname = 'railsapps'; // required: replace example with your forum shortname
/* * * DON'T EDIT BELOW THIS LINE * * */
(function() {
var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true;
dsq.src = 'http://' + disqus_shortname + '.disqus.com/embed.js';
(document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq);
})();
</script>
<noscript>Please enable JavaScript to view the <a href="http://disqus.com/?ref_noscript">comments powered by Disqus.</a></noscript>
<a href="http://disqus.com" class="dsq-brlink">comments powered by <span class="logo-disqus">Disqus</span></a>
</div><!-- class="comments" -->
</div><!-- class="columns" -->
</div><!-- class="row" -->
<footer class="row">
<div class="large-12 columns">
<div class="row">
<div class="medium-4 large-4 columns">
<dl class="footer_nav">
<dt>RailsApps · Getting Started</dt>
<dd><a href="http://railsapps.github.io/ruby-and-rails.html">Ruby on Rails</a></dd>
<dd><a href="http://railsapps.github.io/what-is-ruby-rails.html">What is Ruby on Rails?</a></dd>
<dd><a href="http://learn-rails.com/learn-ruby-on-rails.html">Learn Ruby on Rails</a></dd>
<dd><a href="https://tutorials.railsapps.org/rails-tutorial">Rails Tutorial</a></dd>
<dd><a href="http://learn-rails.com/ruby-on-rails-tutorial-for-beginners">Ruby on Rails Tutorial for Beginners</a></dd>
<dd><a href="http://railsapps.github.io/installing-rails.html">Install Ruby on Rails</a></dd>
<dd><a href="http://railsapps.github.io/installrubyonrails-mac.html">Install Ruby on Rails - Mac OS X</a></dd>
<dd><a href="http://railsapps.github.io/installrubyonrails-ubuntu.html">Install Ruby on Rails - Ubuntu</a></dd>
<dd><a href="http://railsapps.github.io/rubyonrails-nitrous-io.html">Ruby on Rails - Nitrous.io</a></dd>
<dd><a href="http://railsapps.github.io/updating-rails.html">Update Rails</a></dd>
<dd><a href="http://railsapps.github.io/rails-composer/">Rails Composer</a></dd>
<dd><a href="http://railsapps.github.io/">Rails Examples</a></dd>
<dd><a href="http://railsapps.github.io/rails-examples-tutorials.html">Rails Starter Apps</a></dd>
</dl>
</div>
<div class="medium-4 large-4 columns">
<dl class="footer_nav">
<dt>RailsApps · Articles</dt>
<dd><a href="http://railsapps.github.io/rails-authorization.html">Rails Authorization</a></dd>
<dd><a href="http://railsapps.github.io/rails-google-analytics.html">Analytics for Rails</a></dd>
<dd><a href="http://railsapps.github.io/rails-heroku-tutorial.html">Heroku and Rails</a></dd>
<dd><a href="http://railsapps.github.io/rails-javascript-include-external.html">JavaScript and Rails</a></dd>
<dd><a href="http://railsapps.github.io/rails-environment-variables.html">Rails Environment Variables</a></dd>
<dd><a href="http://railsapps.github.io/rails-git.html">Git and Rails</a></dd>
<dd><a href="http://railsapps.github.io/rails-github.html">Rails GitHub</a></dd>
<dd><a href="http://railsapps.github.io/rails-send-email.html">Send Email with Rails</a></dd>
<dd><a href="http://railsapps.github.io/rails-haml.html">Haml and Rails</a></dd>
<dd><a href="http://railsapps.github.io/rails-default-application-layout.html">Rails Application Layout</a></dd>
<dd><a href="http://railsapps.github.io/rails-html5-boilerplate.html">HTML5 Boilerplate for Rails</a></dd>
<dd><a href="http://railsapps.github.io/rails-3-2-example-gemfile.html">Example Gemfiles for Rails</a></dd>
<dd><a href="http://railsapps.github.io/rails-application-templates.html">Rails Application Templates</a></dd>
<dd><a href="http://railsapps.github.io/rails-product-planning.html">Rails Product Planning</a></dd>
<dd><a href="http://railsapps.github.io/rails-project-management.html">Rails Project Management</a></dd>
</dl>
</div>
<div class="medium-4 large-4 columns">
<dl class="footer_nav">
<dt>RailsApps · Tutorials</dt>
<dd><a href="http://railsapps.github.io/twitter-bootstrap-rails.html">Rails Bootstrap</a></dd>
<dd><a href="http://railsapps.github.io/rails-foundation.html">Rails Foundation</a></dd>
<dd><a href="http://railsapps.github.io/rails-omniauth/">OmniAuth Tutorial</a></dd>
<dd><a href="http://railsapps.github.io/tutorial-rails-devise.html">Rails Devise Tutorial</a></dd>
<dd><a href="http://railsapps.github.io/tutorial-rails-devise-rspec-cucumber.html">Devise RSpec</a></dd>
<dd><a href="http://railsapps.github.io/tutorial-rails-bootstrap-devise-cancan.html">Devise Bootstrap</a></dd>
<dd><a href="http://railsapps.github.io/rails-devise-roles">Role-Based Authorization</a></dd>
<dd><a href="http://railsapps.github.io/rails-devise-pundit">Rails Authorization with Pundit</a></dd>
<dd><a href="https://tutorials.railsapps.org/rails-stripe-membership-saas">Rails Membership Site with Stripe</a></dd>
<dd><a href="https://tutorials.railsapps.org/rails-recurly-subscription-saas">Rails Subscription Site with Recurly</a></dd>
<dd><a href="https://tutorials.railsapps.org/rails-prelaunch-signup">Startup Prelaunch Signup Application</a></dd>
</dl>
<dl class="footer_nav">
<dt>RailsApps Profile</dt>
<dd><a href="https://plus.google.com/108039160165742774777?rel=author">Google</a></dd>
<dd><a href="https://plus.google.com/117374718581973393536" rel="publisher">Find us on Google+</a></dd>
</dl>
</div>
</div>
</div>
</footer>
<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/jquery/2.0.3/jquery.min.js"></script>
<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/foundation/5.2.2/js/foundation.min.js"></script>
<script>
$(document).foundation();
</script>
</body>
</html>