diff options
Diffstat (limited to 'railties/guides/source/3_2_release_notes.textile')
| -rw-r--r-- | railties/guides/source/3_2_release_notes.textile | 124 |
1 files changed, 106 insertions, 18 deletions
diff --git a/railties/guides/source/3_2_release_notes.textile b/railties/guides/source/3_2_release_notes.textile index 927abc7944..d669a7fdfa 100644 --- a/railties/guides/source/3_2_release_notes.textile +++ b/railties/guides/source/3_2_release_notes.textile @@ -7,19 +7,47 @@ Highlights in Rails 3.2: * Automatic Query Explains * Tagged Logging -These 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/3-2-stable in the main Rails repository on GitHub. +These release notes cover the major changes, but do not include each bug-fix and changes. If you want to see everything, check out the "list of commits":https://github.com/rails/rails/commits/3-2-stable in the main Rails repository on GitHub. endprologue. h3. Upgrading to Rails 3.2 -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.1 in case you haven't and make sure your application still runs as expected before attempting to update to Rails 3.2. Then take heed of the following changes: +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.1 in case you haven't and make sure your application still runs as expected before attempting an update to Rails 3.2. Then take heed of the following changes: h4. Rails 3.2 requires at least Ruby 1.8.7 Rails 3.2 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.2 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. 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 or 1.9.3 for smooth sailing. +TIP: Note that Ruby 1.8.7 p248 and p249 have marshaling bugs that crash Rails. Ruby Enterprise Edition has these fixed since the release of 1.8.7-2010.02. 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 to 1.9.2 or 1.9.3 for smooth sailing. + +h4. What to update in your apps + +* Update your Gemfile to depend on +** <tt>rails = 3.2.0</tt> +** <tt>sass-rails ~> 3.2.3</tt> +** <tt>coffee-rails ~> 3.2.1</tt> +** <tt>uglifier >= 1.0.3</tt> + +* Rails 3.2 deprecates <tt>vendor/plugins</tt> and Rails 4.0 will remove them completely. You can start replacing these plugins by extracting them as gems and adding them in your Gemfile. If you choose not to make them gems, you can move them into, say, <tt>lib/my_plugin/*</tt> and add an appropriate initializer in <tt>config/initializers/my_plugin.rb</tt>. + +* There are a couple of new configuration changes you'd want to add in <tt>config/environments/development.rb</tt>: + +<ruby> +# Raise exception on mass assignment protection for Active Record models +config.active_record.mass_assignment_sanitizer = :strict + +# Log the query plan for queries taking more than this (works +# with SQLite, MySQL, and PostgreSQL) +config.active_record.auto_explain_threshold_in_seconds = 0.5 +</ruby> + +The <tt>mass_assignment_sanitizer</tt> config also needs to be added in <tt>config/environments/test.rb</tt>: + +<ruby> +# Raise exception on mass assignment protection for Active Record models +config.active_record.mass_assignment_sanitizer = :strict +</ruby> h3. Creating a Rails 3.2 application @@ -33,7 +61,7 @@ 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 gem, 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 +More information: "Bundler homepage":http://gembundler.com h4. Living on the Edge @@ -46,7 +74,7 @@ $ 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: <shell> -$ ruby /path/to/rails/bin/rails new myapp --dev +$ ruby /path/to/rails/railties/bin/rails new myapp --dev </shell> h3. Major Features @@ -63,10 +91,13 @@ Queries that take more than half a second to run are *automatically* explained i h4. Tagged Logging -When running a multi-user, multi-account application, it's a great help to be able to filter the log by who did what. TaggedLogging in Active Support helps in doing exactly that by stamping log lines with subdomains, request ids, and anything else to aid debugging of such applications. +When running a multi-user, multi-account application, it's a great help to be able to filter the log by who did what. TaggedLogging in Active Support helps in doing exactly that by stamping log lines with subdomains, request ids, and anything else to aid debugging such applications. -h3. Railties +h3. Documentation + +From Rails 3.2, the Rails guides are available for the Kindle and free Kindle Reading Apps for the iPad, iPhone, Mac, Android, etc. +h3. Railties * Speed up development by only reloading classes if dependencies files changed. This can be turned off by setting <tt>config.reload_classes_only_on_change</tt> to false. @@ -86,9 +117,9 @@ config.railties_order = [Blog::Engine, :main_app, :all] * Scaffold returns 204 No Content for API requests without content. This makes scaffold work with jQuery out of the box. -* Update Rails::Rack::Logger middleware to apply any tags set in config.log_tags to the newly ActiveSupport::TaggedLogging Rails.logger. This makes it easy to tag log lines with debug information like subdomain and request id -- both very helpful in debugging multi-user production applications +* Update <tt>Rails::Rack::Logger</tt> middleware to apply any tags set in <tt>config.log_tags</tt> to <tt>ActiveSupport::TaggedLogging</tt>. This makes it easy to tag log lines with debug information like subdomain and request id -- both very helpful in debugging multi-user production applications. -* Default options to +rails new+ can be set in <tt>~/.railsrc</tt>. +* Default options to +rails new+ can be set in <tt>~/.railsrc</tt>. You can specify extra command-line arguments to be used every time 'rails new' runs in the <tt>.railsrc</tt> configuration file in your home directory. * Add an alias +d+ for +destroy+. This works for engines too. @@ -102,14 +133,22 @@ rails g scaffold Post title:string:index author:uniq price:decimal{7,2} will create indexes for +title+ and +author+ with the latter being an unique index. Some types such as decimal accept custom options. In the example, +price+ will be a decimal column with precision and scale set to 7 and 2 respectively. +* Turn gem has been removed from default Gemfile. + * Remove old plugin generator +rails generate plugin+ in favor of +rails plugin new+ command. * Remove old <tt>config.paths.app.controller</tt> API in favor of <tt>config.paths["app/controller"]</tt>. -h4. Deprecations +h4(#railties_deprecations). Deprecations * +Rails::Plugin+ is deprecated and will be removed in Rails 4.0. Instead of adding plugins to +vendor/plugins+ use gems or bundler with path or git dependencies. +h3. Action Mailer + +* Upgraded <tt>mail</tt> version to 2.4.0. + +* Removed the old Action Mailer API which was deprecated since Rails 3.0. + h3. Action Pack h4. Action Controller @@ -166,7 +205,7 @@ We now no longer write out HTTP_COOKIE and the cookie jar is persistent between * Assets should use the request protocol by default or default to relative if no request is available. -h5. Deprecations +h5(#actioncontroller_deprecations). Deprecations * Deprecated implied layout lookup in controllers whose parent had a explicit layout set: @@ -181,14 +220,28 @@ end In the example above, Posts controller will no longer automatically look up for a posts layout. If you need this functionality you could either remove <tt>layout "application"</tt> from +ApplicationController+ or explicitly set it to +nil+ in +PostsController+. +* Deprecated <tt>ActionController::UnknownAction</tt> in favour of <tt>AbstractController::ActionNotFound</tt>. + +* Deprecated <tt>ActionController::DoubleRenderError</tt> in favour of <tt>AbstractController::DoubleRenderError</tt>. + +* Deprecated <tt>method_missing</tt> in favour of +action_missing+ for missing actions. + +* Deprecated <tt>ActionController#rescue_action</tt>, <tt>ActionController#initialize_template_class</tt> and <tt>ActionController#assign_shortcuts</tt>. + h4. Action Dispatch +* Add <tt>config.action_dispatch.default_charset</tt> to configure default charset for <tt>ActionDispatch::Response</tt>. + * Added <tt>ActionDispatch::RequestId</tt> middleware that'll make a unique X-Request-Id header available to the response and enables the <tt>ActionDispatch::Request#uuid</tt> method. This makes it easy to trace requests from end-to-end in the stack and to identify individual requests in mixed logs like Syslog. * The <tt>ShowExceptions</tt> middleware now accepts a exceptions application that is responsible to render an exception when the application fails. The application is invoked with a copy of the exception in +env["action_dispatch.exception"]+ and with the <tt>PATH_INFO</tt> rewritten to the status code. * Allow rescue responses to be configured through a railtie as in <tt>config.action_dispatch.rescue_responses</tt>. +h5(#actiondispatch_deprecations). Deprecations + +* Deprecated the ability to set a default charset at the controller level, use the new <tt>config.action_dispatch.default_charset</tt> instead. + h4. Action View * Add +button_tag+ support to <tt>ActionView::Helpers::FormBuilder</tt>. This support mimics the default behavior of +submit_tag+. @@ -199,7 +252,7 @@ h4. Action View <% end %> </ruby> -* Date helpers accept a new option <tt>:use_two_digit_numbers => true</tt>, that renders select boxes for months and days with a leading zero without changing the respective values. For example, this is useful for displaying ISO8601-style dates such as '2011-08-01'. +* Date helpers accept a new option <tt>:use_two_digit_numbers => true</tt>, that renders select boxes for months and days with a leading zero without changing the respective values. For example, this is useful for displaying ISO 8601-style dates such as '2011-08-01'. * You can provide a namespace for your form to ensure uniqueness of id attributes on form elements. The namespace attribute will be prefixed with underscore on the generated HTML id. @@ -232,17 +285,25 @@ end * Added +font_path+ helper method that computes the path to a font asset in <tt>public/fonts</tt>. -h5. Deprecations +h5(#actionview_deprecations). Deprecations * Passing formats or handlers to render :template and friends like <tt>render :template => "foo.html.erb"</tt> is deprecated. Instead, you can provide :handlers and :formats directly as an options: <tt> render :template => "foo", :formats => [:html, :js], :handlers => :erb</tt>. +h4. Sprockets + +* Adds a configuration option <tt>config.assets.logger</tt> to control Sprockets logging. Set it to +false+ to turn off logging and to +nil+ to default to +Rails.logger+. + h3. Active Record +* Boolean columns with 'on' and 'ON' values are type cast to true. + +* When the +timestamps+ method creates the +created_at+ and +updated_at+ columns, it makes them non-nullable by default. + * Implemented <tt>ActiveRecord::Relation#explain</tt>. * Implements <tt>AR::Base.silence_auto_explain</tt> which allows the user to selectively disable automatic EXPLAINs within a block. -* Implements automatic EXPLAIN logging for slow queries. A new configuration parameter +config.active_record.auto_explain_threshold_in_seconds+ determines what's to be considered a slow query. Setting that to nil disables this feature. Defaults are 0.5 in development mode, and nil in test and production modes. As of this writing there's support for SQLite, MySQL (mysql2 adapter), and PostgreSQL. +* Implements automatic EXPLAIN logging for slow queries. A new configuration parameter +config.active_record.auto_explain_threshold_in_seconds+ determines what's to be considered a slow query. Setting that to nil disables this feature. Defaults are 0.5 in development mode, and nil in test and production modes. Rails 3.2 supports this feature in SQLite, MySQL (mysql2 adapter), and PostgreSQL. * Added <tt>ActiveRecord::Base.store</tt> for declaring simple single-column key/value stores. @@ -311,7 +372,34 @@ has_many :clients, :class_name => :Client # Note that the symbol need to be capi User.where(:first_name => "Scarlett").first_or_create!(:last_name => "Johansson") </ruby> -h4. Deprecations +* Added a <tt>with_lock</tt> method to Active Record objects, which starts a transaction, locks the object (pessimistically) and yields to the block. The method takes one (optional) parameter and passes it to +lock!+. + +This makes it possible to write the following: + +<ruby> +class Order < ActiveRecord::Base + def cancel! + transaction do + lock! + # ... cancelling logic + end + end +end +</ruby> + +as: + +<ruby> +class Order < ActiveRecord::Base + def cancel! + with_lock do + # ... cancelling logic + end + end +end +</ruby> + +h4(#activerecord_deprecations). Deprecations * Automatic closure of connections in threads is deprecated. For example the following code is deprecated: @@ -359,7 +447,7 @@ h3. Active Model * Provide mass_assignment_sanitizer as an easy API to replace the sanitizer behavior. Also support both :logger (default) and :strict sanitizer behavior. -h4. Deprecations +h4(#activemodel_deprecations). Deprecations * Deprecated <tt>define_attr_method</tt> in <tt>ActiveModel::AttributeMethods</tt> because this only existed to support methods like +set_table_name+ in Active Record, which are themselves being deprecated. @@ -419,7 +507,7 @@ Event.where(:created_at => Time.now.all_day) * Removed <tt>ActiveSupport::SecureRandom</tt> in favor of <tt>SecureRandom</tt> from the standard library. -h4. Deprecations +h4(#activesupport_deprecations). Deprecations * +ActiveSupport::Base64+ is deprecated in favor of <tt>::Base64</tt>. @@ -429,7 +517,7 @@ h4. Deprecations * Deprecated <tt>ActiveSupport::MessageEncryptor#encrypt</tt> and <tt>ActiveSupport::MessageEncryptor#decrypt</tt>. -* <tt>ActiveSupport::BufferedLogger#silence</tt> is deprecated. If you want to squelch logs for a certain block, change the log level for that block. +* <tt>ActiveSupport::BufferedLogger#silence</tt> is deprecated. If you want to squelch logs for a certain block, change the log level for that block. * <tt>ActiveSupport::BufferedLogger#open_log</tt> is deprecated. This method should not have been public in the first place. |