h2. Ruby on Rails 3.1 Release Notes
Highlights in Rails 3.1:
* Streaming
* Reversible Migrations
* Assets Pipeline
* jQuery as the default JavaScript library
This release notes cover the major changes, but don't include every little bug fix and change. If you want to see everything, check out the "list of commits":https://github.com/rails/rails/commits/master in the main Rails repository on GitHub.
endprologue.
h3. Upgrading to Rails 3.1
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 3 and make sure your application still runs as expected before attempting to update to Rails 3.1. Then take heed of the following changes:
h4. Rails 3.1 requires at least Ruby 1.8.7
Rails 3.1 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.1 is also compatible with Ruby 1.9.2.
TIP: Note that Ruby 1.8.7 p248 and p249 have marshaling bugs that crash Rails. 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, so if you want to use 1.9.x jump on 1.9.2 for smooth sailing.
TODO. What else?
h3. Creating a Rails 3.1 application
# You should have the 'rails' rubygem installed
$ rails new myapp
$ cd myapp
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 processed by the "Bundler":https://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: - "bundler homepage":http://gembundler.com
h4. Living on the Edge
+Bundler+ and +Gemfile+ makes freezing your Rails application easy as pie with the new dedicated bundle command. If you want to bundle straight from the Git repository, you can pass the +--edge+ flag:
$ rails new myapp --edge
If you have a local checkout of the Rails repository and want to generate an application using that, you can pass the +--dev+ flag:
$ ruby /path/to/rails/bin/rails new myapp --dev
h3. Rails Architectural Changes
h4. Assets Pipeline
TODO. point to assets guide, talk about rake assets:* tasks
h3. Documentation
The documentation in the Rails tree is being updated with all the API changes, additionally, the "Rails Edge Guides":http://edgeguides.rubyonrails.org/ 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
h3. Railties
* jQuery is the new default JavaScript library.
* jQuery and prototype are no longer vendored and is provided from now on by the jquery-rails and prototype-rails gems.
* The application generator accepts an option -j which can be an arbitrary string. If passed "foo", the gem "foo-rails" is added to the Gemfile, and the application JavaScript manifest requires "foo" and "foo_ujs". Currently only "prototype-rails" and "jquery-rails" exist and provide those files via the asset pipeline.
* Generating an application or a plugin runs bundle install unless --skip-gemfile or --skip-bundle is specified.
* The controller and resource generators will now automatically produce asset stubs (this can be turned off with --skip-assets). These stubs will use CoffeeScript and Sass, if those libraries are available.
* Scaffold and app generators use the Ruby 1.9 style hash when running on Ruby 1.9. To generate old style hash, --old-style-hash can be passed.
* Scaffold controller generator creates format block for JSON instead of XML.
* Active Record logging is directed to STDOUT and shown inline in the console.
* Added +config.force_ssl+ configuration which loads Rack::SSL middleware and force all requests to be under HTTPS protocol.
* Added +rails plugin new+ command which generates a Rails plugin with gemspec, tests and a dummy application for testing.
* Added Rack::Etag and Rack::ConditionalGet to the default middleware stack.
* Added Rack::Cache to the default middleware stack.
* TODO Engine related changes
h3. Action Pack
TODO split items into controller/view sections.
* A warning is given out if the CSRF token authenticity cannot be verified.
* Allows AM/PM format in datetime selectors.
* auto_link has been removed from Rails and extracted into the "rails_autolink gem":https://github.com/tenderlove/rails_autolink
* Added streaming support, you can enable it with:
class PostsController < ActionController::Base
stream :only => :index
end
Please read the docs at ActionController::Streaming for more information. TODO add links to api docs.
* Added ActionDispatch::Request.ignore_accept_header to ignore accept headers.
* Created ActionView::Renderer and specified an API for ActionView::Context.
* Added ActionController::ParamsWrapper to wrap parameters into a nested hash, and will be turned on for JSON request in new applications by default. This can be customized by setting ActionController::Base.wrap_parameters in config/initializer/wrap_parameters.rb.
* Added Base.http_basic_authenticate_with to do simple http basic authentication with a single class method call.
class PostsController < ApplicationController
USER_NAME, PASSWORD = "dhh", "secret"
before_filter :authenticate, :except => [ :index ]
def index
render :text => "Everyone can see me!"
end
def edit
render :text => "I'm only accessible if you know the password"
end
private
def authenticate
authenticate_or_request_with_http_basic do |user_name, password|
user_name == USER_NAME && password == PASSWORD
end
end
end
..can now be written as
class PostsController < ApplicationController
http_basic_authenticate_with :name => "dhh", :password => "secret", :except => :index
def index
render :text => "Everyone can see me!"
end
def edit
render :text => "I'm only accessible if you know the password"
end
end
* Specify +force_ssl+ in a controller to force the browser to transfer data via HTTPS protocol on that particular controller. To limit to specific actions, :only or :except can be used.
* Allows FormHelper#form_for to specify the :method as a direct option instead of through the :html hash. form_for(@post, remote: true, method: :delete) instead of form_for(@post, remote: true, html: { method: :delete })
* Provided JavaScriptHelper#j() as an alias for JavaScriptHelper#escape_javascript(). This supersedes the Object#j() method that the JSON gem adds within templates using the JavaScriptHelper.
* Sensitive query string parameters specified in config.filter_parameters will now be filtered out from the request paths in the log.
* URL parameters which return nil for +to_param+ are now removed from the query string.
* ActionDispatch::MiddlewareStack now uses composition over inheritance and is no longer an array.
* Added an :authenticity_token option to +form_tag+ for custom handling or to omit the token by passing :authenticity_token => false.
* Added HTML5 button_tag helper.
* Template lookup now searches further up in the inheritance chain.
* config.action_view.cache_template_loading is brought back which allows to decide whether templates should be cached or not. TODO from which version?
* url_for and named url helpers now accept :subdomain and :domain as options.
* The redirect route method now also accepts a hash of options which will only change the parts of the url in question, or an object which responds to call, allowing for redirects to be reused.
* Added config.action_controller.include_all_helpers. By default helper :all is done in ActionController::Base, which includes all the helpers by default. Setting +include_all_helpers+ to false will result in including only application_helper and the helper corresponding to controller (like foo_helper for foo_controller).
* Added a convenience idiom to generate HTML5 data-* attributes in tag helpers from a :data hash of options:
tag("div", :data => {:name => 'Stephen', :city_state => %w(Chicago IL)})
# =>
Keys are dasherized. Values are JSON-encoded, except for strings and symbols.
* The old template handler API is deprecated and the new API simply requires a template handler to respond to call.
* rhtml and rxml are finally removed as template handlers.
* Moved etag responsibility from ActionDispatch::Response to the middleware stack.
* Rely on Rack::Session stores API for more compatibility across the Ruby world. This is backwards incompatible since Rack::Session expects #get_session to accept four arguments and requires #destroy_session instead of simply #destroy.
* file_field automatically adds :multipart => true to the enclosing form.
* +csrf_meta_tag+ is renamed to +csrf_meta_tags+ and aliases csrf_meta_tag for backwards compatibility.
* Added Rack::Cache to the default stack.
h4. Abstract Controller
h4. Action Controller
h4. Action Dispatch
h4. Action View
h3. Active Record
h3. Active Model
The major changes in Active Model are:
* +attr_accessible+ accepts an option +:as+ to specify a role.
* +InclusionValidator+, +ExclusionValidator+, and +FormatValidator+ now accepts an option which can be a proc, a lambda, or anything that respond to +call+. This option will be called with the current record as an argument and returns an object which respond to +include?+ for +InclusionValidator+ and +ExclusionValidator+, and returns a regular expression object for +FormatValidator+.
* Added ActiveModel::SecurePassword to encapsulate dead-simple password usage with BCrypt encryption and salting.
* ActiveModel::AttributeMethods allows attributes to be defined on demand.
h3. Active Resource
The changes in Active Resource are:
* The default format has been changed to JSON for all requests. If you want to continue to use XML you will need to set self.format = :xml in the class. For example,
class User < ActiveResource::Base
self.format = :xml
end
h3. Active Support
The main changes in Active Support are:
* ActiveSupport::Dependencies now raises +NameError+ if it finds an existing constant in load_missing_constant.
* Added a new reporting method Kernel#quietly which silences both STDOUT and STDERR.
* Added String#inquiry as a convenience method for turning a String into a +StringInquirer+ object.
* Added Object#in? to test if an object is included in another object.
* LocalCache strategy is now a real middleware class and no longer an anonymous class.
* ActiveSupport::Dependencies::ClassCache class has been introduced for holding references to reloadable classes.
* ActiveSupport::Dependencies::Reference has been refactored to take direct advantage of the new ClassCache.
* Backports Range#cover? as an alias for Range#include? in Ruby 1.8.
* Added +weeks_ago+ and +prev_week+ to Date/DateTime/Time.
* Added +before_remove_const+ callback to ActiveSupport::Dependencies.remove_unloadable_constants!
Deprecations:
* ActiveSupport::SecureRandom is deprecated in favor of +SecureRandom+ from the Ruby standard library.
h3. Credits
See the "full list of contributors to Rails":http://contributors.rubyonrails.org/ for the many people who spent many hours making Rails, the stable and robust framework it is. Kudos to all of them.
Rails 3.1 Release Notes were compiled by "Vijay Dev":https://github.com/vijaydev.