kotovalexarian-likes-github/rails--rails
1
0
Fork 0
mirror of https://github.com/rails/rails.git synced 2022-11-09 12:12:34 -05:00
Code Releases Activity

Copy over latest release notes from docrails

Browse source
This commit is contained in:
David Heinemeier Hansson 2010-02-03 17:22:08 -08:00
parent efa850558f
commit 36e6daac67
1 changed files with 111 additions and 39 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

150
railties/guides/source/3_0_release_notes.textile
View file

@ -1,35 +1,54 @@
h2. Ruby on Rails 3.0 Release Notes
h2. Rails 3.0: 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.
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 you it arrived. It's the Best Version of Rails We've Ever Done!
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.
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.
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.
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:
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.
* Brand new router with an emphasis on RESTful declarations
* New Action Mailer API modelled after Action Controller (now without the agonizing pain of sending multipart messages!)
* 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":http://github.com/rails/rails/commits/master in the main Rails repository on GitHub.
endprologue.
h3. Upgrading from Rails 2.3.5 to Rails 3.0
WARNING: Rails 3.0 is currently in beta. This means that there are probably bugs and that you should "report them":http://rails.lighthouseapp.com/projects/8994-ruby-on-rails/overview if you see them. You also may not want to run the NORAD nuclear launch application off a beta version. But if you're starting development on a new application and you don't mind getting wind in your hair, please do jump on board!
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:
h3. Upgrading to Rails 3
h4. New Ruby Version Requirement
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:
WARNING: Rails only runs on version 1.8.7 of Ruby or later. Support for previous versions of Ruby has been dropped and Rails 3.0 will no longer boot on any of these versions.
h4. Rails 3 requires Ruby 1.8.7+
h4. The new boot process
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.
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. Rails Application object
h4. Gems and gems and gems
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+.
h4. script/* replaced by script/rails
The new <tt>script/rails</tt> replaces all the scripts that used to be in the <tt>script</tt> directory. You do not run <tt>script/rails</tt> 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:
<shell>
rails console # => ./script/console
rails g scaffold post title:string # => ./script/generate scaffold post title:string
</shell>
Run rails --help for a list of all the options.
h4. Dependencies and config.gem
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.
@ -37,7 +56,7 @@ To help with the upgrade process, a plugin named "Rails Upgrade":http://github.c
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
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
@ -46,30 +65,29 @@ Aside from Rails Upgrade tool, if you need more help, there are people on IRC an
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.
h3. Creating a Rails 3.0 application
Rails 3.0 is designed to run on 1.8.7 and also support Ruby 1.9.
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, for example:
The new installing rails sequence (for the beta) is:
<shell>
$ rails myapp --database=mysql
$ 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.
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":http://github.com/carlhuda/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.
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 +Gemfile+, the concept of freezing Rails was dropped, because it's always bundled/frozen inside your application. By default, it uses your system gems when bundling; however, if you want to bundle straight from the Git repository, you can pass the edge flag:
+Bundler+ and +Gemfile+ makes freezing your Rails application easy as pie with the new dedicated <tt>bundle</tt> command, so <tt>rake freeze</tt> is no longer relevant and has been dropped.
If you want to bundle straight from the Git repository, you can pass the edge flag:
<shell>
$ rails myapp --edge
@ -79,56 +97,76 @@ 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.
"Arel":http://github.com/rails/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.
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
A large amount of work has been done with I18n support in Rails 3, 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: - "Rails 3 I18n changes":http://blog.plataformatec.com.br/2010/02/rails-3-i18n-changes/
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.
@ -138,7 +176,7 @@ 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>.
* 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.
@ -149,6 +187,11 @@ Also, the views generated by Railties generators had some overhaul:
* Scaffolds generated now make use of <tt>_form</tt> partials, instead of duplicated code in the edit and new views.
* Scaffold forms now use <tt>f.submit</tt> which returns "Create ModelName" or "Update ModelName" depending on the state of the object passed in.
Finally a couple of enhancements were added to the rake tasks:
* <tt>rake db:forward</tt> was added, allowing you to roll forward your migrations individually or in groups.
* <tt>rake routes CONTROLLER=x</tt> was added allowing you to just view the routes for one controller.
Railties now deprecates:
* <tt>RAILS_ROOT</tt> in favour of <tt>Rails.root</tt>,
@ -161,10 +204,12 @@ More information:
* "Discovering Rails 3 generators":http://blog.plataformatec.com.br/2010/01/discovering-rails-3-generators
* "Making Generators for Rails 3 with Thor":http://caffeinedd.com/guides/331-making-generators-for-rails-3-with-thor
h3. Action Pack
There have been significant internal and external changes in Action Pack.
h4. Abstract Controller
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 <tt>ActionMailer::Base</tt> to now just inherit from +AbstractController+ and just wrap the Rails DSL onto the Mail gem.
@ -175,6 +220,7 @@ Note however that Abstract Controller is not a user facing API, you will not run
More Information: - "Rails Edge Architecture":http://yehudakatz.com/2009/06/11/rails-edge-architecture/
h4. Action Controller
* <tt>application_controller.rb</tt> now has <tt>protect_from_forgery</tt> on by default.
@ -194,6 +240,7 @@ More Information:
* "Render Options in Rails 3":http://www.engineyard.com/blog/2010/render-options-in-rails-3/
* "Three reasons to love ActionController::Responder":http://weblog.rubyonrails.org/2009/8/31/three-reasons-love-responder
h4. Action Dispatch
Action Dispatch is new in Rails 3.0 and provides a new, cleaner implementation for routing.
@ -220,9 +267,9 @@ end
* Added +scope+ method to the router, allowing you to namespace routes for different languages or different actions, for example:
<ruby>
scope 'es' { resources :projects,
:path_names => { :edit => 'cambiar' },
:as => 'projeto' }
scope 'es' do
resources :projects, :path_names => { :edit => 'cambiar' }, :as => 'projeto'
end
# Gives you the edit action with /es/projeto/1/cambiar
</ruby>
@ -243,6 +290,7 @@ More Information:
* "Revamped Routes in Rails 3":http://rizwanreza.com/2009/12/20/revamped-routes-in-rails-3
* "Generic Actions in Rails 3":http://yehudakatz.com/2009/12/20/generic-actions-in-rails-3/
h4. Action View
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.
@ -264,17 +312,23 @@ Produces:
* Form label helper now pulls values from I18n with a single value, so <tt>f.label :name</tt> will pull the <tt>:name</tt> translation.
* I18n select label on should now be :en.helpers.select instead of :en.support.select.
* You no longer need to place a minus sign at the end of a ruby interpolation inside an ERb template to remove the trailing carriage return in the HTML output.
* Added +grouped_collection_select+ helper to Action View.
* Action View now will raise exceptions if CSS stylesheets and javascript files listed in the +javascript_include_tag+ and +stylesheet_include_tag+ helpers are missing.
* +content_for?+ has been added allowing you to check for the existence of content in a view before rendering.
h3. Active Model
Active Model is new in Rails 3.0. It provides an abstraction layer for any ORM libraries to use to interact with Rails by implementing an Active Model interface.
h4. ORM Abstraction and Action Pack Interface
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. Validations
Validations have been moved from Active Record into Active Model, providing an interface to validations that works across ORM libraries in Rails 3.
@ -324,8 +378,12 @@ More Information:
* "Sexy Validation in Rails 3":http://thelucid.com/2010/01/08/sexy-validation-in-edge-rails-rails-3/
* "Rails 3 Validations Explained":http://lindsaar.net/2010/1/31/validates_rails_3_awesome_is_true
h3. Active Record
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.
h4. Query Interface
Active Record, through the use of Arel, now returns relations on it's 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:
@ -350,6 +408,13 @@ More Information:
* "Active Record Query Interface":http://m.onkey.org/2010/1/22/active-record-query-interface
* "Let your SQL Growl in Rails 3":http://hasmanyquestions.wordpress.com/2010/01/17/let-your-sql-growl-in-rails-3/
h4. Enhancements
* Added <tt>:destroyed?</tt> to Active Record objects.
* Added <tt>:inverse_of</tt> to Active Record associations allowing you to pull the instance of an already loaded association without hitting the database.
h4. Patches and Deprecations
Additionally, many fixes in the Active Record branch:
@ -357,19 +422,24 @@ Additionally, many fixes in the Active Record branch:
* SQLite 2 support has been dropped in favour of SQLite 3.
* MySQL support for column order.
* PostgreSQL adapter has had it's +TIME ZONE+ support fixed so it no longer inserts incorrect values.
* Support multiple schemas in table names for PostgreSQL.
* PostgreSQL support for the XML data type column.
* +table_name+ is now cached.
* A large amount of work done on the Oracle adapter as well with many bug fixes.
As well as the following deprecations:
* +named_scope+ in an Active Record class is deprecated and has been renamed to just +scope+.
* In +scope+ methods, you should move to using the relation methods, instead of a <tt>:conditions => {}</tt> finder method, for example <tt>scope :since, lambda {|time| where("created_at > ?", time) }</tt>.
* <tt>save(false)</tt> is deprecated, in favour of <tt>save(:validate => false)</tt>.
* I18n error messages for ActiveRecord should be changed from :en.activerecord.errors to <tt>:en.errors</tt>.
* I18n error messages for ActiveRecord should be changed from :en.activerecord.errors.template to <tt>:en.errors.template</tt>.
* <tt>model.errors.on</tt> is deprecated in favour of <tt>model.errors[]</tt>
* validates_presence_of => validates... :presence => true
* <tt>ActiveRecord::Base.colorize_logging</tt> and <tt>config.active_record.colorize_logging</tt> are deprecated in favour of <tt>Rails::Subscriber.colorize_logging</tt> or <tt>config.colorize_logging</tt>
NOTE: While an implementation of State Machine has been in Active Record edge for some months now, it has been removed from the Rails 3.0 release.
h3. Active Resource
Active Resource was also extracted out to Active Model allowing you to use Active Resource objects with Action Pack seamlessly.
@ -400,6 +470,7 @@ Deprecations:
* <tt>save(false)</tt> is deprecated, in favour of <tt>save(:validate => false)</tt>.
* Ruby 1.9.2: <tt>URI.parse</tt> and <tt>.decode</tt> are deprecated and are no longer used in the library.
h3. Active Support
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.
@ -438,7 +509,7 @@ The following methods have been removed because they are now available in Ruby 1
* <tt>Integer#even?</tt> and <tt>Integer#odd?</tt>
* <tt>String#each_char</tt>
* <tt>String#start_with?</tt> and <tt>String#end_with?</tt> (plural aliases still kept)
* <tt>String#start_with?</tt> and <tt>String#end_with?</tt> (3rd person aliases still kept)
* <tt>String#bytesize</tt>
* <tt>Object#tap</tt>
* <tt>Symbol#to_proc</tt>
@ -449,8 +520,8 @@ The security patch for REXML remains in Active Support because early patchlevels
The following methods have been removed because they are no longer used in the framework:
* <tt>Class#subclasses</tt>, <tt>Class#reachable?</tt>, <tt>Class#remove_class</tt>
* <tt>Object#remove_subclasses_of</tt>, <tt>Object#subclasses_of</tt>, <tt>Object#extend_with_included_modules_from</tt>, <tt>Object#extended_by</tt>
* <tt>Class#subclasses</tt>, <tt>Class#reachable?</tt>, <tt>Class#remove_class</tt>
* <tt>Regexp#number_of_captures</tt>
* <tt>Regexp.unoptionalize</tt>, <tt>Regexp.optionalize</tt>, <tt>Regexp#number_of_captures</tt>
@ -481,8 +552,9 @@ More Information:
* "New Action Mailer API in Rails 3":http://lindsaar.net/2010/1/26/new-actionmailer-api-in-rails-3
* "New Mail Gem for Ruby":http://lindsaar.net/2010/1/23/mail-gem-version-2-released
h3. Credits
See the "full list of contributors to Rails":http://contributors.rubyonrails.org/, many people have spent many hours making Rails 3 what it is. Kudos to all of them.
See the "full list of contributors to Rails":http://contributors.rubyonrails.org/ for the many people who spent many hours making Rails 3. Kudos to all of them.
Rails 3.0 Release Notes were compiled by "Mikel Lindsaar":http://lindsaar.net, who can be found "feeding":http://feeds.feedburner.com/lindsaar-net and "tweeting":http://twitter.com/raasdnil.
Rails 3.0 Release Notes were compiled by "Mikel Lindsaar":http://lindsaar.net.