railties 3.1.0.rc4 → 3.1.0.rc5

data/guides/source/initialization.textile

@@ -512,7 +512,7 @@ h4. +railties/lib/rails/ruby_version_check.rb+
 
 This file simply checks if the Ruby version is less than 1.8.7 or is 1.9.1 and raises an error if that is the case. Rails 3 simply will not run on earlier versions of Ruby than 1.8.7 or 1.9.1.
 
-NOTE: You should always endeavour to run the latest version of Ruby with your Rails applications. The benefits are many, including security fixes and the like, and very often there is a speed increase associated with it. The caveat is that you could have code that potentially breaks on the latest version, which should be fixed to work on the latest version rather than kept around as an excuse not to upgrade.
+NOTE: You should always endeavor to run the latest version of Ruby with your Rails applications. The benefits are many, including security fixes and the like, and very often there is a speed increase associated with it. The caveat is that you could have code that potentially breaks on the latest version, which should be fixed to work on the latest version rather than kept around as an excuse not to upgrade.
 
 h4. +active_support/core_ext/kernel/reporting.rb+
 
@@ -661,9 +661,9 @@ require 'active_support/inflections'
 require 'active_support/core_ext/string/inflections'
 </ruby>
 
-The +active_support/inflector/methods+ file has already been required by +active_support/autoload+ and so won't be loaded again here.
+The +active_support/inflector/methods+ file has already been required by +active_support/autoload+ and so won't be loaded again here. The +activesupport/lib/active_support/inflector/inflections.rb+ is required by +active_support/inflector/methods+.
 
-h4. +activesupport/lib/active_support/inflector/inflections.rb+
+h4. +active_support/inflections+
 
 This file references the +ActiveSupport::Inflector+ constant which isn't loaded by this point. But there were autoloads set up in +activesupport/lib/active_support.rb+ which will load the file which loads this constant and so then it will be defined. Then this file defines pluralization and singularization rules for words in Rails. This is how Rails knows how to pluralize "tomato" to "tomatoes".
 
@@ -866,7 +866,7 @@ def +(other)
 end
 </ruby>
 
-So this <tt>+</tt> method is overriden to return a new collection comprising of the existing collection as an array and then using the <tt>Array#+</tt> method combines these two collections, returning a "super" +Collection+ object. In this case, the only initializer that's going to be in this new +Collection+ object is the +i18n.callbacks+ initializer.
+So this <tt>+</tt> method is overridden to return a new collection comprising of the existing collection as an array and then using the <tt>Array#+</tt> method combines these two collections, returning a "super" +Collection+ object. In this case, the only initializer that's going to be in this new +Collection+ object is the +i18n.callbacks+ initializer.
 
 The next method to be called after this +initializer+ method is the +after_initialize+ method on the +config+ object, which is defined like this:
 

data/guides/source/layouts_and_rendering.textile

@@ -94,7 +94,7 @@ NOTE: The actual rendering is done by subclasses of +ActionView::TemplateHandler
 
 h4. Using +render+
 
-In most cases, the +ActionController::Base#render+ method does the heavy lifting of rendering your application's content for use by a browser. There are a variety of ways to customise the behaviour of +render+. You can render the default view for a Rails template, or a specific template, or a file, or inline code, or nothing at all. You can render text, JSON, or XML. You can specify the content type or HTTP status of the rendered response as well.
+In most cases, the +ActionController::Base#render+ method does the heavy lifting of rendering your application's content for use by a browser. There are a variety of ways to customize the behaviour of +render+. You can render the default view for a Rails template, or a specific template, or a file, or inline code, or nothing at all. You can render text, JSON, or XML. You can specify the content type or HTTP status of the rendered response as well.
 
 TIP: If you want to see the exact results of a call to +render+ without needing to inspect it in a browser, you can call +render_to_string+. This method takes exactly the same options as +render+, but it returns a string instead of sending a response back to the browser.
 
@@ -123,7 +123,7 @@ Cache-Control: no-cache
  $
 </shell>
 
-We see there is an empty response (no data after the +Cache-Control+ line), but the request was successful because Rails has set the response to 200 OK. You can set the +:status+ option on render to change this response. Rendering nothing can be useful for AJAX requests where all you want to send back to the browser is an acknowledgement that the request was completed.
+We see there is an empty response (no data after the +Cache-Control+ line), but the request was successful because Rails has set the response to 200 OK. You can set the +:status+ option on render to change this response. Rendering nothing can be useful for AJAX requests where all you want to send back to the browser is an acknowledgment that the request was completed.
 
 TIP: You should probably be using the +head+ method, discussed later in this guide, instead of +render :nothing+. This provides additional flexibility and makes it explicit that you're only generating HTTP headers.
 

data/guides/source/migrations.textile

@@ -17,7 +17,7 @@ endprologue.
 
 h3. Anatomy of a Migration
 
-Before I dive into the details of a migration, here are a few examples of the sorts of things you can do:
+Before we dive into the details of a migration, here are a few examples of the sorts of things you can do:
 
 <ruby>
 class CreateProducts < ActiveRecord::Migration
@@ -117,6 +117,33 @@ Occasionally you will make a mistake when writing a migration. If you have alrea
 
 In general editing existing migrations is not a good idea: you will be creating extra work for yourself and your co-workers and cause major headaches if the existing version of the migration has already been run on production machines. Instead you should write a new migration that performs the changes you require. Editing a freshly generated migration that has not yet been committed to source control (or more generally which has not been propagated beyond your development machine) is relatively harmless.
 
+h4. Supported Types
+
+Active Record supports the following types:
+
+* +:primary_key+
+* +:string+
+* +:text+
+* +:integer+
+* +:float+
+* +:decimal+
+* +:datetime+
+* +:timestamp+
+* +:time+
+* +:date+
+* +:binary+
+* +:boolean+
+
+These will be mapped onto an appropriate underlying database type, for example with MySQL +:string+ is mapped to +VARCHAR(255)+. You can create columns of types not supported by Active Record when using the non-sexy syntax, for example
+
+<ruby>
+create_table :products do |t|
+  t.column :name, 'polygon', :null => false
+end
+</ruby>
+
+This may however hinder portability to other databases.
+
 h3. Creating a Migration
 
 h4. Creating a Model
@@ -261,18 +288,6 @@ end
 
 will append +ENGINE=BLACKHOLE+ to the SQL statement used to create the table (when using MySQL the default is +ENGINE=InnoDB+).
 
-The types supported by Active Record are +:primary_key+, +:string+, +:text+, +:integer+, +:float+, +:decimal+, +:datetime+, +:timestamp+, +:time+, +:date+, +:binary+, +:boolean+.
-
-These will be mapped onto an appropriate underlying database type, for example with MySQL +:string+ is mapped to +VARCHAR(255)+. You can create columns of types not supported by Active Record when using the non-sexy syntax, for example
-
-<ruby>
-create_table :products do |t|
-  t.column :name, 'polygon', :null => false
-end
-</ruby>
-
-This may however hinder portability to other databases.
-
 h4. Changing Tables
 
 A close cousin of +create_table+ is +change_table+, used for changing existing tables. It is used in a similar fashion to +create_table+ but the object yielded to the block knows more tricks. For example
@@ -344,7 +359,7 @@ The +change+ method removes the need to write both +up+ and +down+ methods in th
 
 * +add_column+
 * +add_index+
-* +add_timestamp+
+* +add_timestamps+
 * +create_table+
 * +remove_timestamps+
 * +rename_column+
@@ -462,7 +477,7 @@ Several methods are provided that allow you to control all this:
 
 For example, this migration
 
-<ruby>
+<pre>
 class CreateProducts < ActiveRecord::Migration
   def change
     suppress_messages do
@@ -481,7 +496,7 @@ class CreateProducts < ActiveRecord::Migration
     end
   end
 end
-</ruby>
+</pre>
 
 generates the following output
 
@@ -499,40 +514,107 @@ If you just want Active Record to shut up then running +rake db:migrate VERBOSE=
 
 h3. Using Models in Your Migrations
 
-When creating or updating data in a migration it is often tempting to use one of your models. After all they exist to provide easy access to the underlying data. This can be done but some caution should be observed.
+When creating or updating data in a migration it is often tempting to use one of your models. After all they exist to provide easy access to the underlying data. This can be done, but some caution should be observed.
 
-Consider for example a migration that uses the +Product+ model to update a row in the corresponding table. Alice later updates the +Product+ model, adding a new column and a validation on it. Bob comes back from holiday, updates the source and runs outstanding migrations with +rake db:migrate+, including the one that used the +Product+ model. When the migration runs the source is up to date and so the +Product+ model has the validation added by Alice. The database however is still old and so does not have that column and an error ensues because that validation is on a column that does not yet exist.
+For example, problems occur when the model uses database columns which are (1) not currently in the database and (2) will be created by this or a subsequent migration.
 
-Frequently I just want to update rows in the database without writing out the SQL by hand: I'm not using anything specific to the model. One pattern for this is to define a copy of the model inside the migration itself, for example:
+Consider this example, where Alice and Bob are working on the same code base which contains a +Product+ model:
 
-<ruby>
-class AddPartNumberToProducts < ActiveRecord::Migration
-  class Product < ActiveRecord::Base
+Bob goes on vacation.
+
+Alice creates a migration for the +products+ table which adds a new column and initializes it.
+She also adds a validation to the Product model for the new column.
+
+<pre>
+# db/migrate/20100513121110_add_flag_to_product.rb
+
+class AddFlagToProduct < ActiveRecord::Migration
+  def change
+    add_column :products, :flag, :int
+    Product.all.each { |f| f.update_attributes!(:flag => 'false') }
   end
+end
+</pre>
+
+<pre>
+# app/model/product.rb
+
+class Product < ActiveRecord::Base
+  validates_presence_of :flag
+end
+</pre>
+
+Alice adds a second migration which adds and initializes another column to the +products+ table and also adds a validation to the Product model for the new column.
 
+<pre>
+# db/migrate/20100515121110_add_fuzz_to_product.rb
+
+class AddFuzzToProduct < ActiveRecord::Migration
   def change
-    ...
+    add_column :products, :fuzz, :string
+    Product.all.each { |f| f.update_attributes! :fuzz => 'fuzzy' }
   end
 end
-</ruby>
-The migration has its own minimal copy of the +Product+ model and no longer cares about the +Product+ model defined in the application.
+</pre>
 
-h4. Dealing with Changing Models
+<pre>
+# app/model/product.rb
 
-For performance reasons information about the columns a model has is cached. For example if you add a column to a table and then try and use the corresponding model to insert a new row it may try to use the old column information. You can force Active Record to re-read the column information with the +reset_column_information+ method, for example
+class Product < ActiveRecord::Base
+  validates_presence_of :flag
+  validates_presence_of :fuzz
+end
+</pre>
 
-<ruby>
-class AddPartNumberToProducts < ActiveRecord::Migration
+Both migrations work for Alice.
+
+Bob comes back from vacation and:
+
+# updates the source - which contains both migrations and the latests version of the Product model.
+# runs outstanding migrations with +rake db:migrate+, which includes the one that updates the +Product+ model.
+
+The migration crashes because when the model attempts to save, it tries to validate the second added column, which is not in the database when the _first_ migration runs.
+
+<pre>
+rake aborted!
+An error has occurred, this and all later migrations canceled:
+
+undefined method `fuzz' for #<Product:0x000001049b14a0>
+</pre>
+
+A fix for this is to create a local model within the migration. This keeps rails from running the validations, so that the migrations run to completion.
+
+When using a faux model, it's a good idea to call +Product.reset_column_information+ to refresh the ActiveRecord cache for the Product model prior to updating data in the database.
+
+If Alice had done this instead, there would have been no problem:
+
+<pre>
+# db/migrate/20100513121110_add_flag_to_product.rb
+
+class AddFlagToProduct < ActiveRecord::Migration
   class Product < ActiveRecord::Base
   end
+  def change
+    add_column :products, :flag, :int
+    Product.reset_column_information  
+    Product.all.each { |f| f.update_attributes!(:flag => false) }
+  end
+end
+</pre>
+
+<pre>
+# db/migrate/20100515121110_add_fuzz_to_product.rb
 
+class AddFuzzToProduct < ActiveRecord::Migration
+  class Product < ActiveRecord::Base
+  end
   def change
-    add_column :product, :part_number, :string
+    add_column :products, :fuzz, :string
     Product.reset_column_information
-    ...
+    Product.all.each { |f| f.update_attributes! :fuzz => 'fuzzy' }
   end
 end
-</ruby>
+</pre>
 
 
 h3. Schema Dumping and You

data/guides/source/nested_model_forms.textile

@@ -90,7 +90,7 @@ h3. Views
 
 h4. Controller code
 
-A nested model form will _only_ be build if the associated object(s) exist. This means that for a new model instance you would probably want to build the associated object(s) first.
+A nested model form will _only_ be built if the associated object(s) exist. This means that for a new model instance you would probably want to build the associated object(s) first.
 
 Consider the following typical RESTful controller which will prepare a new Person instance and its +address+ and +projects+ associations before rendering the +new+ template:
 
@@ -144,7 +144,7 @@ Now add a nested form for the +address+ association:
   <%= f.text_field :name %>
 
   <%= f.fields_for :address do |af| %>
-    <%= f.text_field :street %>
+    <%= af.text_field :street %>
   <% end %>
 <% end %>
 </erb>
@@ -159,7 +159,7 @@ This generates:
 </form>
 </html>
 
-Notice that +fields_for+ recognized the +address+ as an association for which a nested model form should be build by the way it has namespaced the +name+ attribute.
+Notice that +fields_for+ recognized the +address+ as an association for which a nested model form should be built by the way it has namespaced the +name+ attribute.
 
 When this form is posted the Rails parameter parser will construct a hash like the following:
 
@@ -185,7 +185,7 @@ The form code for an association collection is pretty similar to that of a singl
   <%= f.text_field :name %>
 
   <%= f.fields_for :projects do |pf| %>
-    <%= f.text_field :name %>
+    <%= pf.text_field :name %>
   <% end %>
 <% end %>
 </erb>
@@ -201,7 +201,7 @@ Which generates:
 </form>
 </html>
 
-As you can see it has generated 2 +project name+ inputs, one for each new +project+ that’s build in the controllers +new+ action. Only this time the +name+ attribute of the input contains a digit as an extra namespace. This will be parsed by the Rails parameter parser as:
+As you can see it has generated 2 +project name+ inputs, one for each new +project+ that was built in the controller's +new+ action. Only this time the +name+ attribute of the input contains a digit as an extra namespace. This will be parsed by the Rails parameter parser as:
 
 <ruby>
 {
@@ -215,7 +215,7 @@ As you can see it has generated 2 +project name+ inputs, one for each new +proje
 }
 </ruby>
 
-You can basically see the +projects_attributes+ hash as an array of attribute hashes. One for each model instance.
+You can basically see the +projects_attributes+ hash as an array of attribute hashes, one for each model instance.
 
 NOTE: The reason that +fields_for+ constructed a form which would result in a hash instead of an array is that it won't work for any forms nested deeper than one level deep.
 

data/guides/source/performance_testing.textile

@@ -66,7 +66,7 @@ resources :posts
 # home_controller.rb
 class HomeController < ApplicationController
   def dashboard
-    @users = User.last_ten(:include => :avatars)
+    @users = User.last_ten.includes(:avatars)
     @posts = Post.all_today
   end
 end
@@ -151,7 +151,7 @@ Performance tests can be run in two modes: Benchmarking and Profiling.
 
 h5. Benchmarking
 
-Benchmarking makes it easy to quickly gather a few metrics about each test tun. By default, each test case is run +4 times+ in benchmarking mode.
+Benchmarking makes it easy to quickly gather a few metrics about each test tun. By default, each test case is run *4 times* in benchmarking mode.
 
 To run performance tests in benchmarking mode:
 
@@ -161,7 +161,7 @@ $ rake test:benchmark
 
 h5. Profiling
 
-Profiling allows you to make an in-depth analysis of each of your tests by using an external profiler. Depending on your Ruby interpreter, this profiler can be native (Rubinius, JRuby) or not (MRI, which uses RubyProf). By default, each test case is run +1 time+ in profiling mode.
+Profiling allows you to make an in-depth analysis of each of your tests by using an external profiler. Depending on your Ruby interpreter, this profiler can be native (Rubinius, JRuby) or not (MRI, which uses RubyProf). By default, each test case is run *once* in profiling mode.
 
 To run performance tests in profiling mode:
 
@@ -276,7 +276,7 @@ measurement,created_at,app,rails,ruby,platform
 
 h5(#output-profiling). Profiling
 
-In profiling mode, performance tests can generate multiple types of outputs. The command line output is always presented but support for the others is dependant on the interpreter in use. A brief description of each type and their availability across interpreters is given below.
+In profiling mode, performance tests can generate multiple types of outputs. The command line output is always presented but support for the others is dependent on the interpreter in use. A brief description of each type and their availability across interpreters is given below.
 
 h6. Command Line
 
@@ -481,7 +481,7 @@ h4. +profiler+
 Usage:
 
 <shell>
-Usage: rails benchmarker 'Ruby.code' 'Ruby.more_code' ... [OPTS]
+Usage: rails profiler 'Ruby.code' 'Ruby.more_code' ... [OPTS]
     -r, --runs N                     Number of runs.
                                      Default: 1
     -o, --output PATH                Directory to use when writing the results.
@@ -573,7 +573,7 @@ h3. Useful Links
 h4. Rails Plugins and Gems
 
 * "Rails Analyzer":http://rails-analyzer.rubyforge.org
-* "Palmist":http://www.flyingmachinestudios.com/projects/
+* "Palmist":http://www.flyingmachinestudios.com/programming/announcing-palmist
 * "Rails Footnotes":https://github.com/josevalim/rails-footnotes/tree/master
 * "Query Reviewer":https://github.com/dsboulder/query_reviewer/tree/master
 

data/guides/source/plugins.textile

@@ -25,33 +25,36 @@ endprologue.
 
 h3. Setup
 
-h4. Generating the Plugin Skeleton
+Before you continue, take a moment to decide if your new plugin will be potentially shared across different Rails applications.
 
-Rails currently ships with a generator to generate a plugin within a Rails application. Help text is available that will explain
-how this generator works.
+* If your plugin is specific to your application, your new plugin will be a _vendored plugin_.
+* If you think your plugin may be used across applications, build it as a _gemified plugin_.
+
+h4. Either generate a vendored plugin...
+
+Use the +rails generate plugin+ command in your Rails root directory
+ to create a new plugin that will live in the +vendor/plugins+
+ directory. See usage and options by asking for help:
 
 <shell>
 $ rails generate plugin --help
 </shell>
 
-This generator places the plugin into the vendor/plugins directory.
+h4. Or generate a gemified plugin.
 
-Vendored plugins are useful for quickly prototyping your plugin but current thinking in the Rails community is shifting towards
-packaging plugins as gems, especially with the inclusion of Bundler as the Rails dependency manager.
-Packaging a plugin as a gem may be overkill for any plugins that will not be shared across projects but doing so from the start makes it easier to share the plugin going forward without adding too much additional overhead during development.
+Writing your Rails plugin as a gem, rather than as a vendored plugin,
+ lets you share your plugin across different rails applications using
+ RubyGems and Bundler.
 
-Rails 3.1 will ship with a plugin generator that will default to setting up a plugin
-as a gem. This tutorial will begin to bridge that gap by demonstrating how to create a gem based plugin using the
-"Enginex gem":http://www.github.com/josevalim/enginex.
+Rails 3.1 ships with a +rails plugin new+ command which creates a
+ skeleton for developing any kind of Rails extension with the ability
+ to run integration tests using a dummy Rails application. See usage
+ and options by asking for help:
 
 <shell>
-$ gem install enginex
-$ enginex --help
-$ enginex yaffle
+$ rails plugin --help
 </shell>
 
-This command will create a new directory named "yaffle" within the current directory.
-
 h3. Testing your newly generated plugin
 
 You can navigate to the directory that contains the plugin, run the +bundle install+ command
@@ -83,7 +86,7 @@ class CoreExtTest < Test::Unit::TestCase
 end
 </ruby>
 
-Run +rake+ to run the test. This test should fail because we haven't implemented the +to_squak+ method:
+Run +rake+ to run the test. This test should fail because we haven't implemented the +to_squawk+ method:
 
 <shell>
 	  1) Error:
@@ -215,8 +218,8 @@ test/dummy directory:
 
 <shell>
 $ cd test/dummy
-$ rails generate model Hickwall last_squak:string
-$ rails generate model Wickwall last_squak:string last_tweet:string
+$ rails generate model Hickwall last_squawk:string
+$ rails generate model Wickwall last_squawk:string last_tweet:string
 </shell>
 
 Now you can create the necessary database tables in your testing database by navigating to your dummy app
@@ -319,7 +322,7 @@ When you run +rake+ you should see the tests all pass:
 
 h4. Add an Instance Method
 
-This plugin will add a method named 'squawk' to any Active Record objects that call 'acts_as_yaffle'.  The 'squawk'
+This plugin will add a method named 'squawk' to any Active Record objects that call 'acts_as_yaffle'. The 'squawk'
 method will simply set the value of one of the fields in the database.
 
 To start out, write a failing test that shows the behavior you'd like:
@@ -387,9 +390,7 @@ Run +rake+ one final time and you should see:
 	7 tests, 7 assertions, 0 failures, 0 errors, 0 skips
 </shell>
 
-NOTE: The use of +write_attribute+ to write to the field in model is just one example of how a plugin can
-interact with the model, and will not always be the right method to use. For example, you could also
-use +send("#{self.class.yaffle_text_field}=", string.to_squawk)+.
+NOTE: The use of +write_attribute+ to write to the field in model is just one example of how a plugin can interact with the model, and will not always be the right method to use. For example, you could also use <tt>send("#{self.class.yaffle_text_field}=", string.to_squawk)</tt>.
 
 h3. Generators