2.6. Living on the Edge

One of my favorite decisions that the core Rails team made when designing the Rails architecture was to allow each individual Rails project to easily maintain its own copy of Rails, thus making it trivial to have multiple projects require different versions of Rails. In particular, it's no trouble at all to have a new project use the cutting-edge version of Rails right off the trunk of the main Subversion repository, while every other project on your machine continues to use version 1.2.

2.6.1. Using a Specific Version of Rails

The current version of Rails under development and pre-release is usually called Edge Rails, in contrast to the official release versions, often called Gem Rails. There are a couple of different ways to ensure that your new project runs against a specific version of Rails, whether that version is Edge or a specific Gem version.

2.6.1.1. Using Subversion to Live on the Edge

Because the Soups OnLine project is being managed via Subversion, you'll use a Subversion-specific mechanism. Subversion enables you to specify that part of your project should be loaded from an external Subversion server — in this case, the Rails Subversion server. From your Soups OnLine top-level directory, run the following command:

$ svn propset svn:externals "rails http://dev.rubyonrails.org/svn/rails/

trunk/" vendor
property 'svn:externals' set on 'vendor'

This command tells Subversion that the rails directory of the specified Subversion server should be associated with the vendor directory of your Rails project. However, this command by itself does not give you the Edge Rails files. To do that, you need to update the directory as follows:

$ svn update vendor

Fetching external item into 'vendor/rails'
A    vendor/rails/cleanlogs.sh
A    vendor/rails/release.rb
A    vendor/rails/activeresource

[... An Oodle of files ...]

U   vendor/rails
Updated external to revision 7127.

Updated to revision 2.

At this point, not only will your project run using Edge Rails, but whenever you update your project, Subversion will automatically seek out the dev.rubyonrails.org server and update Rails for you.

However, there's now a slight discrepancy in your project. When you used the rails command to create the project, Edge Rails didn't exist on the system, so if there have been any changes to the Rails-generated project files since the Gem Rails version you used, you need to update your project to ensure you have the latest and greatest. Here's how:

$ rails .      exists
      exists  app/controllers
      exists  app/helpers

[...  Stuff ...]

   identical  log/development.log
   identical  log/test.log
$ svn commit -m "updating Rails"
Sending        vendor

Committed revision 3.

If any files need to be changed, Rails will prompt you before changing them. However, if you've made custom changes to Rails system files, your modifications may be lost.

After you get started on your project, it's less feasible to update the Rails-created files every time there is a Rails update. Luckily, you probably won't need to do this often. Most of the Rails-created files are structural and don't change frequently. However, you should keep an eye on the Edge Rails changes and be prepared to update files if necessary. You might want to particularly keep an eye on changes to vendor/rails/railties — especially the JavaScript files in vendor/rails/railties/html/javascripts that are directly used as the JavaScript engines for your Rails application.

You can also use the handy rake task rails:update to keep your Rails project current with your Rails code base. The update task has the following three subtasks that can be called separately if you wish to update only part of your Rails project:

• rails:update:configs updates the config/boot.rb file.

• rails:update:javascripts updates all the JavaScript files.

• rails:update:scripts updates all the files in your scripts directory that perform Rails administrative tasks. Remember to specify any new files here as executable in Subversion if you're going back and forth between Windows and a Unix-based operating system.

Running rails:update is equivalent to running all three of these subtasks.

2.6.1.2. Specifying a Particular Version

By using Edge Rails, the Soups OnLine program will have access to the most up-to-the-moment ideas and brainstorms of Rails core programmers the world over. They have only to commit, and the code will show up in the project on the next update.

However, this is not always the best idea. Sometimes, a change to Edge Rails might affect an API call that you depend on in your application. Every now and then, a bug might sneak in to Edge Rails and make itself at home before it is noticed and fixed. Although you might be able to live with this instability for awhile during development, at some point you need to draw a line in the sand and define the Rails version that works for your project.

Staying within Subversion, you can respecify the property for your vendor/rails directory and use the -r option to specify a particular revision of Rails in the trunk. The revision number is specified in the output generated by Subversion when you update. The update shown in the previous section was to revision 7127. If you, for some reason, decided this was the most perfect version of Rails there ever could be and wanted this to be your application's Rails version forevermore, you would specify it by overwriting the svn:externals property with a new property as shown here:

$ svn propset svn:externals "rails -r 7127 http://dev.rubyonrails.org/

svn/rails/trunk/" vendor
property 'svn:externals' set on 'vendor'

Further updates to your project will no longer update the vendor/rails directory — you will have locked your local version of Rails to that particular revision.

Although it's nice to be able to specify an arbitrary Rails revision for your project, you are more likely to lock your version to one of the official Rails releases. This is a slightly different command because the Rails releases have been copied from the Rails trunk to their own branch. As of this writing, there are two releases available as stable branches: 1-1-stable and 1-2-stable. Accessing them is a simple matter of changing the externals command to point to the proper directory as follows:

$ svn propset svn:externals "rails http://dev.rubyonrails.org/

svn/rails/branches/1-1-stable/" vendor

or

$ svn propset svn:externals "rails http://dev.rubyonrails.org/

svn/rails/branches/1-2-stable/" vendor

Because these are branches, further updates are not expected, so you'll have the stability you need.

If you want a little more granularity, the /tags directory can reproduce any Rails release from 0.9.1 all the way through 2.0.2 and counting. The name of each follows the form /tags/rel_2-0-2.

2.6.2. Living on the Edge With Rake

If you're not using Subversion, or you just don't need the automatic updating feature, you can also specify your Rails version via the following simple rake task:

$ rake rails:freeze:edge

This will perform the same checkout of the current Edge Rails that setting the Subversion property and updating did in the last section. As previously mentioned, though, you'll no longer get automatic updates when you update your project. Running the command again will perform another checkout, overwriting your vendor/rails/ directory with the newer version.

This mechanism also offers you the opportunity to specify a particular Rails revision to work against. To freeze your project to the same revision 7127 you loved from Subversion, issue the following command:

$ rake rails:freeze:edge REVISION=7127

There's no automatic mechanism in the freeze mechanism to manage branches. However, in the interest of preventing you from having to look it up, the following table lists the revision numbers for branches and tags that might be of interest.

An advantage of using rake to manage your Edge Rails is that it's particularly easy to undo. The following command will empty your vendor/rails directory, effectively reverting you to whatever Rails version you have installed via RubyGems:

$ rake rails:unfreeze

Alternatively, you can copy the RubyGems version to your local project directory with the following command:

$ rake rails:freeze:gems

This is helpful if you want to freeze an existing Rails project before you update your system-wide RubyGems.