Ruby on Rails 3.0 Release Notes

Rails 3.0 is ponies and rainbows! It's going to cook you dinner and fold your laundry. You're going to wonder how life was ever possible before it arrived. It's the Best Version of Rails We've Ever Done!

But seriously now, it's really good stuff. There are all the good ideas brought over from when the Merb team joined the party and brought a focus on framework agnosticism, slimmer and faster internals, and a handful of tasty APIs. If you're coming to Rails 3.0 from Merb 1.x, you should recognize lots. If you're coming from Rails 2.x, you're going to love it too.

Even if you don't give a hoot about any of our internal cleanups, Rails 3.0 is going to delight. We have a bunch of new features and improved APIs. It's never been a better time to be a Rails developer. Some of the highlights are:

New Active Record chainable query language built on top of relational algebra

Unobtrusive JavaScript helpers with drivers for Prototype, jQuery, and more coming (end of inline JS)

Explicit dependency management with Bundler

On top of all that, we've tried our best to deprecate the old APIs with nice warnings. That means that you can move your existing application to Rails 3 without immediately rewriting all your old code to the latest best practices.

These release notes cover the major upgrades, but don't include every little bug fix and change. Rails 3.0 consists of almost 4,000 commits by more than 250 authors! If you want to see everything, check out the list of commits in the main Rails repository on GitHub.

If you're upgrading an existing application, it's a great idea to have good test coverage before going in. You should also first upgrade to Rails 2.3.5 and make sure your application still runs as expected before attempting to update to Rails 3. Then take heed of the following changes:

Rails 3.0 requires Ruby 1.8.7 or higher. Support for all of the previous Ruby versions has been dropped officially and you should upgrade as early as possible. Rails 3.0 is also compatible with Ruby 1.9.2.

Note that Ruby 1.8.7 p248 and p249 have marshalling bugs that crash Rails 3.0. Ruby Enterprise Edition have these fixed since release 1.8.7-2010.02 though. On the 1.9 front, Ruby 1.9.1 is not usable because it outright segfaults on Rails 3.0, so if you want to use Rails 3 with 1.9.x jump on 1.9.2 for smooth sailing.

As part of the groundwork for supporting running multiple Rails applications in the same process, Rails 3 introduces the concept of an Application object. An application object holds all the application specific configurations and is very similar in nature to config/environment.rb from the previous versions of Rails.

Each Rails application now must have a corresponding application object. The application object is defined in config/application.rb. If you're upgrading an existing application to Rails 3, you must add this file and move the appropriate configurations from config/environment.rb to config/application.rb.

The new script/rails replaces all the scripts that used to be in the script directory. You do not run script/rails directly though, the rails command detects it is being invoked in the root of a Rails application and runs the script for you. Intended usage is:

To help with the upgrade process, a plugin named Rails Upgrade has been created to automate part of it.

Simply install the plugin, then run rake rails:upgrade:check to check your app for pieces that need to be updated (with links to information on how to update them). It also offers a task to generate a Gemfile based on your current config.gem calls and a task to generate a new routes file from your current one. To get the plugin, simply run the following:

Aside from Rails Upgrade tool, if you need more help, there are people on IRC and rubyonrails-talk that are probably doing the same thing, possibly hitting the same issues. Be sure to blog your own experiences when upgrading so others can benefit from your knowledge!

Rails now uses a Gemfile in the application root to determine the gems you require for your application to start. This Gemfile is processed by the Bundler which then installs all your dependencies. It can even install all the dependencies locally to your application so that it doesn't depend on the system gems.

Railties was updated to provide a consistent plugin API for the entire Rails framework as well as a total rewrite of generators and the Rails bindings, the result is that developers can now hook into any significant stage of the generators and application framework in a consistent, defined manner.

With the merge of Merb and Rails, one of the big jobs was to remove the tight coupling between Rails core components. This has now been achieved, and all Rails core components are now using the same API that you can use for developing plugins. This means any plugin you make, or any core component replacement (like DataMapper or Sequel) can access all the functionality that the Rails core components have access to and extend and enhance at will.

Part of decoupling the core components was extracting all ties to Active Record from Action Pack. This has now been completed. All new ORM plugins now just need to implement Active Model interfaces to work seamlessly with Action Pack.

Another big part of decoupling the core components was creating a base superclass that is separated from the notions of HTTP in order to handle rendering of views etc. This creation of AbstractController allowed ActionController and ActionMailer to be greatly simplified with common code removed from all these libraries and put into Abstract Controller.

Arel (or Active Relation) has been taken on as the underpinnings of Active Record and is now required for Rails. Arel provides an SQL abstraction that simplifies out Active Record and provides the underpinnings for the relation functionality in Active Record.

Action Mailer ever since its beginnings has had monkey patches, pre parsers and even delivery and receiver agents, all in addition to having TMail vendored in the source tree. Version 3 changes that with all email message related functionality abstracted out to the Mail gem. This again reduces code duplication and helps create definable boundaries between Action Mailer and the email parser.

The documentation in the Rails tree is being updated with all the API changes, additionally, the Rails Edge Guides are being updated one by one to reflect the changes in Rails 3.0. The guides at guides.rubyonrails.org however will continue to contain only the stable version of Rails (at this point, version 2.3.5, until 3.0 is released).

With the decoupling of the main Rails frameworks, Railties got a huge overhaul so as to make linking up frameworks, engines, or plugins as painless and extensible as possible:

Each application now has its own name space, application is started with YourAppName.boot for example, makes interacting with other applications a lot easier.

Anything under Rails.root/app is now added to the load path, so you can make app/observers/user_observer.rb and Rails will load it without any modifications.

Rails 3.0 now provides a Rails.config object, which provides a central repository of all sorts of Rails wide configuration options.

Application generation has received extra flags allowing you to skip the installation of test-unit, Active Record, Prototype and Git. Also a new --dev flag has been added which sets the application up with the Gemfile pointing to your Rails checkout (which is determined by the path to the rails binary). See rails --help for more info.

Abstract Controller pulls out the generic parts of Action Controller into a reusable module that any library can use to render templates, render partials, helpers, translations, logging, any part of the request response cycle. This abstraction allowed ActionMailer::Base to now just inherit from AbstractController and just wrap the Rails DSL onto the Mail gem.

It also provided an opportunity to clean up Action Controller, abstracting out what could to simplify the code.

Note however that Abstract Controller is not a user facing API, you will not run into it in your day to day use of Rails.

The cookie_verifier_secret has been deprecated and now instead it is assigned through Rails.application.config.cookie_secret and moved into its own file: config/initializers/cookie_verification_secret.rb.

The session_store was configured in ActionController::Base.session, and that is now moved to Rails.application.config.session_store. Defaults are set up in config/initializers/session_store.rb.

cookies.secure allowing you to set encrypted values in cookies with cookie.secure[:key] => value.

cookies.permanent allowing you to set permanent values in the cookie hash cookie.permanent[:key] => value that raise exceptions on signed values if verification failures.

You can now pass :notice => 'This is a flash message' or :alert => 'Something went wrong' to the format call inside a respond_to block. The flash[] hash still works as previously.

respond_with method has now been added to your controllers simplifying the venerable format blocks.

ActionController::Responder added allowing you flexibility in how your responses get generated.

Deprecations:

filter_parameter_logging is deprecated in favor of config.filter_parameters << :password.

Major re-write was done in the Action View helpers, implementing Unobtrusive JavaScript (UJS) hooks and removing the old inline AJAX commands. This enables Rails to use any compliant UJS driver to implement the UJS hooks in the helpers.

What this means is that all previous remote_<method> helpers have been removed from Rails core and put into the Prototype Legacy Helper. To get UJS hooks into your HTML, you now pass :remote => true instead. For example:

Part of decoupling the core components was extracting all ties to Active Record from Action Pack. This has now been completed. All new ORM plugins now just need to implement Active Model interfaces to work seamlessly with Action Pack.

Validations have been moved from Active Record into Active Model, providing an interface to validations that works across ORM libraries in Rails 3.

There is now a validates :attribute, options_hash shortcut method that allows you to pass options for all the validates class methods, you can pass more than one option to a validate method.

The validates method has the following options:

:acceptance => Boolean.

:confirmation => Boolean.

:exclusion => { :in => Enumerable }.

:inclusion => { :in => Enumerable }.

:format => { :with => Regexp, :on => :create }.

:length => { :maximum => Fixnum }.

:numericality => Boolean.

:presence => Boolean.

:uniqueness => Boolean.

All the Rails version 2.3 style validation methods are still supported in Rails 3.0, the new validates method is designed as an additional aid in your model validations, not a replacement for the existing API.

You can also pass in a validator object, which you can then reuse between objects that use Active Model:

Active Record received a lot of attention in Rails 3.0, including abstraction into Active Model, a full update to the Query interface using Arel, validation updates, and many enhancements and fixes. All of the Rails 2.x API will be usable through a compatibility layer that will be supported until version 3.1.

Active Record, through the use of Arel, now returns relations on its core methods. The existing API in Rails 2.3.x is still supported and will not be deprecated until Rails 3.1 and not removed until Rails 3.2, however, the new API provides the following new methods that all return relations allowing them to be chained together:

where - provides conditions on the relation, what gets returned.

select - choose what attributes of the models you wish to have returned from the database.

group - groups the relation on the attribute supplied.

having - provides an expression limiting group relations (GROUP BY constraint).

A large effort was made in Active Support to make it cherry pickable, that is, you no longer have to require the entire Active Support library to get pieces of it. This allows the various core components of Rails to run slimmer.

These are the main changes in Active Support:

Large clean up of the library removing unused methods throughout.

Active Support no longer provides vendored versions of TZInfo, Memcache Client and Builder. These are all included as dependencies and installed via the bundle install command.

Safe buffers are implemented in ActiveSupport::SafeBuffer.

Added Array.uniq_by and Array.uniq_by!.

Removed Array#rand and backported Array#sample from Ruby 1.9.

Fixed bug on TimeZone.seconds_to_utc_offset returning wrong value.

Added ActiveSupport::Notifications middleware.

ActiveSupport.use_standard_json_time_format now defaults to true.

ActiveSupport.escape_html_entities_in_json now defaults to false.

Integer#multiple_of? accepts zero as an argument, returns false unless the receiver is zero.

Action Mailer has been given a new API with TMail being replaced out with the new Mail as the email library. Action Mailer itself has been given an almost complete re-write with pretty much every line of code touched. The result is that Action Mailer now simply inherits from Abstract Controller and wraps the Mail gem in a Rails DSL. This reduces the amount of code and duplication of other libraries in Action Mailer considerably.

All mailers are now in app/mailers by default.

Can now send email using new API with three methods: attachments, headers and mail.

Action Mailer now has native support for inline attachments using the attachments.inline method.

Action Mailer emailing methods now return Mail::Message objects, which can then be sent the deliver message to send itself.

All delivery methods are now abstracted out to the Mail gem.

The mail delivery method can accept a hash of all valid mail header fields with their value pair.

The mail delivery method acts in a similar way to Action Controller's respond_to, and you can explicitly or implicitly render templates. Action Mailer will turn the email into a multipart email as needed.

You can pass a proc to the format.mime_type calls within the mail block and explicitly render specific types of text, or add layouts or different templates. The render call inside the proc is from Abstract Controller and supports the same options.

What were mailer unit tests have been moved to functional tests.

Action Mailer now delegates all auto encoding of header fields and bodies to Mail Gem

Feedback

You may also find incomplete content or stuff that is not up to date.
Please do add any missing documentation for master. Make sure to check
Edge Guides first to verify
if the issues are already fixed or not on the master branch.
Check the Ruby on Rails Guides Guidelines
for style and conventions.

If for whatever reason you spot something to fix but cannot patch it yourself, please
open an issue.