<commit_before>h2. Ruby on Rails 3.0 Beta Release Notes

Rails 3.0 is a landmark release as it delivers on the Merb/Rails merge promise made in December 2008.  Rails 3.0 provides major upgrades to all of the components of Rails, including a complete overhaul of the router and query APIs.

One of the main achievements of this release, is that while there are loads of new features, old APIs have been deprecated with warnings wherever possible, so that you can implement the new features and conventions at your own pace.  There is a backwards compatibility layer that will be supported during 3.0.x and removed in 3.1.

Rails 3.0 adds Active Model ORM abstraction, Abstract Controller generic controller abstraction as well as a consistent Plugin API giving developers full access to all the Rails internals that make Action Mailer, Action Controller, Action View, Active Record and Active Resource work.

These release notes cover the major upgrades, but don't include every little bug fix and change. If you want to see everything, check out the "list of commits":http://github.com/rails/rails/commits/master in the main Rails repository on GitHub.

endprologue.


NOTE: These release notes are still being modified constantly.  Rails 3.0 beta is not out yet, so be sure to check back here on the actual release date to find any changes.  Comments and corrections welcome, please send to "<NAME>":http://lindsaar.net or "@raasdnil"::http://twitter.com/raasdnil or contribute via Doc Rails.

h3. Upgrading from Rails 2.3.5 to Rails 3.0

As always, having a high coverage, passing test suite is your friend when upgrading.  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.0. In general, the upgrade from Rails 2.x to 3.0 centers around three big changes:


h4. New Ruby Version Requirement

WARNING: Rails 3.0 was built to run on Ruby version 1.8.7.  Support for previous versions of Ruby has been dropped and Rails 3.0 will no longer boot on any of these versions.


h4. The new boot process

As part of the shift to treating Rails apps as Rack endpoints, you are now required to have a +config/application.rb+ file, which takes over much of the work +config/environment.rb+ used to handle.  Along with that comes a lot of internal change to the boot process, but those changes are mostly internal.


h4. Gems and gems and gems

The +config.gem+ method is gone and has been replaced by using +bundler+ and a +Gemfile+, see "Vendoring Gems":#vendoring-gems below.


h4. New APIs

Both the router and query interface have seen significant, breaking changes.  There is a backwards compatibility layer that is in place and will be supported until the 3.1 release.


h4. Upgrade Process

To help with the upgrade process, a plugin named "Rails Upgrade":http://github.com/rails/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:

<shell>
script/plugin install git://github.com/rails/rails_upgrade.git
</shell>

You can see an example of how that works at "Rails Upgrade is now an Official Plugin":http://omgbloglol.com/post/364624593/rails-upgrade-is-now-an-official-plugin

Aside from Rails Upgrade tool, if you need more help, there are people on IRC and "rubyonrails-talk":http://groups.google.com/group/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!

More information - "The Path to Rails 3: Approaching the upgrade":http://omgbloglol.com/post/353978923/the-path-to-rails-3-approaching-the-upgrade


h3. Application Creation

As stated above, you must be on Ruby 1.8.7 or later to boot up a Rails application.  Rails will no longer boot on Ruby 1.8.6 or earlier.

Rails 3.0 is designed to run on 1.8.7, support for 1.9.x is still in testing.

There have been a few changes to the +rails+ script that's used to generate Rails applications:

* The application name, <tt>rails my_app</tt>, can now optionally be a path instead <tt>rails ~/code/my_app</tt>, your rails application will be name spaced under the application name you pass the +rails+ command.
* Additionally, any flags you need to generate the application now need to come after the application path.

The new installing rails sequence (for the beta) is:

<shell>
$ gem install rails --prerelease
$ rails myapp
$ cd myapp
</shell>

h4. Vendoring Gems

Rails now uses a +Gemfile+ in the application root to determine the gems you require for your application to start. This +Gemfile+ is then read and acted on by the new "Bundler":http://github.com/wycats/bundler gem, which then vendors all your gems into the vendor directory, making your Rails application isolated from system gems.

More information: - "Using bundler":http://yehudakatz.com/2009/11/03/using-the-new-gem-bundler-today/


h4. Living on the Edge

Due to the use of the +Bundler+ gem with +Gemfile+, you can "freeze" your Rails app at any time through the <tt>bundle</tt> command, so the concept of <tt>rake freeze</tt> has been dropped.

If you want to bundle straight from the Git repository, you can pass the edge flag:

<shell>
$ rails myapp --edge
</shell>

More information:
* "Spinning up a new Rails app":http://yehudakatz.com/2009/12/31/spinning-up-a-new-rails-app/
* "Rails 3 and Passenger":http://cakebaker.42dh.com/2010/01/17/rails-3-and-passenger/


h3. Rails Architectural Changes

There are six major changes in the architecture of Rails.


h4. Railties Restrung

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.


h4. All Rails core components are decoupled

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.

More information: - "The Great Decoupling":http://yehudakatz.com/2009/07/19/rails-3-the-great-decoupling/


h4. Active Model Abstraction

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.

More information: - "Make Any Ruby Object Feel Like ActiveRecord":http://yehudakatz.com/2010/01/10/activemodel-make-any-ruby-object-feel-like-activerecord/


h4. Controller Abstraction

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.

More Information: - "Rails Edge Architecture":http://yehudakatz.com/2009/06/11/rails-edge-architecture/


h4. Arel Integration

"Arel":http://github.com/brynary/arel (or Active Relation) has been taken on as the underpinnings of Active Record and is now required for Rails (it is installed for you when you do a <tt>gem bundle</tt>).  Arel provides an SQL abstraction that simplifies out Active Record and provides the underpinnings for the relation functionality in Active Record.

More information: - "Why I wrote Arel":http://magicscalingsprinkles.wordpress.com/2010/01/28/why-i-wrote-arel/.


h4. Mail Extraction

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":http://github.com/mikel/mail gem.  This again reduces code duplication and helps create definable boundaries between Action Mailer and the email parser.

More information: - "New Action Mailer API in Rails 3":http://lindsaar.net/2010/1/26/new-actionmailer-api-in-rails-3


h3. Documentation

The documentation in the Rails tree is being updated with all the API changes, additionally, the "Rails Edge guides":http://guides.rails.info/ are being updated one by one to reflect the changes in Rails 3.0.  The guides at "guides.rubyonrails.org":http://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).

More Information: - "Rails Documentation Projects":http://weblog.rubyonrails.org/2009/1/15/rails-documentation-projects.


h3. Internationalization

Rails has many improvements in I18n support, including the latest "I18n":http://github.com/svenfuchs/i18n gem supplying many speed improvements.

* I18n for any object - I18n behavior can be added to any object by including <tt>ActiveModel::Translation</tt> and <tt>ActiveModel::Validations</tt>.  There is also an <tt>errors.messages</tt> fallback for translations.
* Attributes can have default translations.
* Form Submit Tags automatically pull the correct status (Create or Update) depending on the object status, and so pull the correct translation.
* Labels with I18n also now work by just passing the attribute name.

More Information: - "Speedup for I18n":http://blog.plataformatec.com.br/2009/12/run-i18n-run/


h3. Railties

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 it's own name space, application is started with <tt>YourAppName.boot</tt> for example, makes interacting with other applications a lot easier.
* You now have access to <tt>Rails.config</tt> which provides huge amount of configuration settings for your application.
* Anything under <tt>Rails.root/app</tt> is now added to the load path, so you can make <tt>app/observers/user_observer.rb</tt> and Rails will load it without any modifications.
* Rails 3.0 now provides a <tt>Rails.config</tt> 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 <tt>--dev</tt> 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 <tt>rails --help</tt> for more info.

Railties generators got a huge amount of attention in Rails 3.0, basically:

* Generators were completely rewritten and are backwards incompatible.
* Rails templates API and generators API were merged (they are the same as the former).
* Generators are no longer loaded from special paths anymore, they are just found in the Ruby load path, so calling <tt>script/generate foo</tt> will look for <tt>generators/foo_generator</tt>.
* New generators provide hooks, so any template engine, ORM, test framework can easily hook in.
* New generators allow you to override the templates by placing a copy at <tt>RAILS_ROOT/lib/templates</tt>.
* <tt>Rails::Generators::TestCase</tt> is also supplied so you can create your own generators and test them.

Also, the views generated by Railties generators had some overhaul:
<commit_msg>Fixing all the 'script' references<commit_after>h2. Ruby on Rails 3.0 Beta Release Notes

Rails 3.0 is a landmark release as it delivers on the Merb/Rails merge promise made in December 2008.  Rails 3.0 provides major upgrades to all of the components of Rails, including a complete overhaul of the router and query APIs.

One of the main achievements of this release, is that while there are loads of new features, old APIs have been deprecated with warnings wherever possible, so that you can implement the new features and conventions at your own pace.  There is a backwards compatibility layer that will be supported during 3.0.x and removed in 3.1.

Rails 3.0 adds Active Model ORM abstraction, Abstract Controller generic controller abstraction as well as a consistent Plugin API giving developers full access to all the Rails internals that make Action Mailer, Action Controller, Action View, Active Record and Active Resource work.

These release notes cover the major upgrades, but don't include every little bug fix and change. If you want to see everything, check out the "list of commits":http://github.com/rails/rails/commits/master in the main Rails repository on GitHub.

endprologue.


NOTE: These release notes are still being modified constantly.  Rails 3.0 beta is not out yet, so be sure to check back here on the actual release date to find any changes.  Comments and corrections welcome, please send to "<NAME>":http://lindsaar.net or "@raasdnil"::http://twitter.com/raasdnil or contribute via Doc Rails.

h3. Upgrading from Rails 2.3.5 to Rails 3.0

As always, having a high coverage, passing test suite is your friend when upgrading.  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.0. In general, the upgrade from Rails 2.x to 3.0 centers around three big changes:


h4. New Ruby Version Requirement

WARNING: Rails 3.0 was built to run on Ruby version 1.8.7.  Support for previous versions of Ruby has been dropped and Rails 3.0 will no longer boot on any of these versions.


h4. The new boot process

As part of the shift to treating Rails apps as Rack endpoints, you are now required to have a +config/application.rb+ file, which takes over much of the work +config/environment.rb+ used to handle.  Along with that comes a lot of internal change to the boot process, but those changes are mostly internal.


h4. New rails binary

The +rails+ binary has been upgraded in Rails 3.0  It lives as <tt>script/rails</tt> and is a one stop command for all of the commands that used to live in <tt>script/</tt>.  You now call <tt>rails <command_name></tt> instead.


h4. Gems and gems and gems

The +config.gem+ method is gone and has been replaced by using +bundler+ and a +Gemfile+, see "Vendoring Gems":#vendoring-gems below.


h4. New APIs

Both the router and query interface have seen significant, breaking changes.  There is a backwards compatibility layer that is in place and will be supported until the 3.1 release.


h4. Upgrade Process

To help with the upgrade process, a plugin named "Rails Upgrade":http://github.com/rails/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:

<shell>
rails plugin install git://github.com/rails/rails_upgrade.git
</shell>

You can see an example of how that works at "Rails Upgrade is now an Official Plugin":http://omgbloglol.com/post/364624593/rails-upgrade-is-now-an-official-plugin

Aside from Rails Upgrade tool, if you need more help, there are people on IRC and "rubyonrails-talk":http://groups.google.com/group/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!

More information - "The Path to Rails 3: Approaching the upgrade":http://omgbloglol.com/post/353978923/the-path-to-rails-3-approaching-the-upgrade


h3. Application Creation

As stated above, you must be on Ruby 1.8.7 or later to boot up a Rails application.  Rails will no longer boot on Ruby 1.8.6 or earlier.

Rails 3.0 is designed to run on 1.8.7, support for 1.9.x is still in testing.

There have been a few changes to the +rails+ script that's used to generate Rails applications:

* The application name, <tt>rails my_app</tt>, can now optionally be a path instead <tt>rails ~/code/my_app</tt>, your rails application will be name spaced under the application name you pass the +rails+ command.
* Additionally, any flags you need to generate the application now need to come after the application path.

The new installing rails sequence (for the beta) is:

<shell>
$ gem install rails --prerelease
$ rails myapp
$ cd myapp
</shell>

h4. Vendoring Gems

Rails now uses a +Gemfile+ in the application root to determine the gems you require for your application to start. This +Gemfile+ is then read and acted on by the new "Bundler":http://github.com/wycats/bundler gem, which then vendors all your gems into the vendor directory, making your Rails application isolated from system gems.

More information: - "Using bundler":http://yehudakatz.com/2009/11/03/using-the-new-gem-bundler-today/


h4. Living on the Edge

Due to the use of the +Bundler+ gem with +Gemfile+, you can "freeze" your Rails app at any time through the <tt>bundle</tt> command, so the concept of <tt>rake freeze</tt> has been dropped.

If you want to bundle straight from the Git repository, you can pass the edge flag:

<shell>
$ rails myapp --edge
</shell>

More information:
* "Spinning up a new Rails app":http://yehudakatz.com/2009/12/31/spinning-up-a-new-rails-app/
* "Rails 3 and Passenger":http://cakebaker.42dh.com/2010/01/17/rails-3-and-passenger/


h3. Rails Architectural Changes

There are six major changes in the architecture of Rails.


h4. Railties Restrung

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.


h4. All Rails core components are decoupled

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.

More information: - "The Great Decoupling":http://yehudakatz.com/2009/07/19/rails-3-the-great-decoupling/


h4. Active Model Abstraction

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.

More information: - "Make Any Ruby Object Feel Like ActiveRecord":http://yehudakatz.com/2010/01/10/activemodel-make-any-ruby-object-feel-like-activerecord/


h4. Controller Abstraction

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.

More Information: - "Rails Edge Architecture":http://yehudakatz.com/2009/06/11/rails-edge-architecture/


h4. Arel Integration

"Arel":http://github.com/brynary/arel (or Active Relation) has been taken on as the underpinnings of Active Record and is now required for Rails (it is installed for you when you do a <tt>gem bundle</tt>).  Arel provides an SQL abstraction that simplifies out Active Record and provides the underpinnings for the relation functionality in Active Record.

More information: - "Why I wrote Arel":http://magicscalingsprinkles.wordpress.com/2010/01/28/why-i-wrote-arel/.


h4. Mail Extraction

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":http://github.com/mikel/mail gem.  This again reduces code duplication and helps create definable boundaries between Action Mailer and the email parser.

More information: - "New Action Mailer API in Rails 3":http://lindsaar.net/2010/1/26/new-actionmailer-api-in-rails-3


h3. Documentation

The documentation in the Rails tree is being updated with all the API changes, additionally, the "Rails Edge guides":http://guides.rails.info/ are being updated one by one to reflect the changes in Rails 3.0.  The guides at "guides.rubyonrails.org":http://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).

More Information: - "Rails Documentation Projects":http://weblog.rubyonrails.org/2009/1/15/rails-documentation-projects.


h3. Internationalization

Rails has many improvements in I18n support, including the latest "I18n":http://github.com/svenfuchs/i18n gem supplying many speed improvements.

* I18n for any object - I18n behavior can be added to any object by including <tt>ActiveModel::Translation</tt> and <tt>ActiveModel::Validations</tt>.  There is also an <tt>errors.messages</tt> fallback for translations.
* Attributes can have default translations.
* Form Submit Tags automatically pull the correct status (Create or Update) depending on the object status, and so pull the correct translation.
* Labels with I18n also now work by just passing the attribute name.

More Information: - "Speedup for I18n":http://blog.plataformatec.com.br/2009/12/run-i18n-run/


h3. Railties

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 it's own name space, application is started with <tt>YourAppName.boot</tt> for example, makes interacting with other applications a lot easier.
* You now have access to <tt>Rails.config</tt> which provides huge amount of configuration settings for your application.
* Anything under <tt>Rails.root/app</tt> is now added to the load path, so you can make <tt>app/observers/user_observer.rb</tt> and Rails will load it without any modifications.
* Rails 3.0 now provides a <tt>Rails.config</tt> 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 <tt>--dev</tt> 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 <tt>rails --help</tt> for more info.

Railties generators got a huge amount of attention in Rails 3.0, basically:

* Generators were completely rewritten and are backwards incompatible.
* Rails templates API and generators API were merged (they are the same as the former).
* Generators are no longer loaded from special paths anymore, they are just found in the Ruby load path, so calling <tt>rails generate foo</tt> will look for <tt>generators/foo_generator</tt>.
* New generators provide hooks, so any template engine, ORM, test framework can easily hook in.
* New generators allow you to override the templates by placing a copy at <tt>RAILS_ROOT/lib/templates</tt>.
* <tt>Rails::Generators::TestCase</tt> is also supplied so you can create your own generators and test them.

Also, the views generated by Railties generators had some overhaul:

{'fraction_non_alphanumeric': 0.06431671170064686, 'fraction_numerical': 0.016826332596413657, 'mean_word_length': 4.379211627394847, 'pattern_counts': {'":': 48, '<': 100, '<?xml version=': 0, '>': 100, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6979863', 'n_tokens_mistral': 6989, 'n_tokens_neox': 6354, 'n_words': 3438}