RubyGems - railties - Versions diffs - 3.0.20 → 3.1.0.beta1 - Mend

railties 3.0.20 → 3.1.0.beta1

Files changed (193) hide show

data/guides/source/layout.html.erb CHANGED

@@ -12,6 +12,8 @@
 <link rel="stylesheet" type="text/css" href="stylesheets/syntaxhighlighter/shCore.css" />
 <link rel="stylesheet" type="text/css" href="stylesheets/syntaxhighlighter/shThemeRailsGuides.css" />
+<link rel="stylesheet" type="text/css" href="stylesheets/fixes.css" />
 </head>
 <body class="guide">
   <% if @edge %>
@@ -106,14 +108,14 @@
     <div class="wrapper">
       <div id="mainCol">
         <%= yield.html_safe %>
         <h3>Feedback</h3>
         <p>
-          You're encouraged to help in keeping the quality of this guide.
+          You're encouraged to help improve the quality of this guide.
         </p>
         <p>
           If you see any typos or factual errors you are confident to
-          patch please clone <%= link_to 'docrails', 'https://github.com/lifo/docrails' %>
+          patch, please clone <%= link_to 'docrails', 'https://github.com/lifo/docrails' %>
           and push the change yourself. That branch of Rails has public write access.
           Commits are still reviewed, but that happens after you've submitted your
           contribution. <%= link_to 'docrails', 'https://github.com/lifo/docrails' %> is
@@ -123,10 +125,7 @@
           You may also find incomplete content, or stuff that is not up to date.
           Please do add any missing documentation for master. Check the
           <%= link_to 'Ruby on Rails Guides Guidelines', 'ruby_on_rails_guides_guidelines.html' %>
-          guide for style and conventions.
-        </p>
-        <p>
-          Issues may also be reported <%= link_to 'in Github', 'https://github.com/lifo/docrails/issues' %>.
+          for style and conventions.
         </p>
         <p>And last but not least, any kind of discussion regarding Ruby on Rails
           documentation is very welcome in the <%= link_to 'rubyonrails-docs mailing list', 'http://groups.google.com/group/rubyonrails-docs' %>.

data/guides/source/layouts_and_rendering.textile CHANGED

@@ -27,7 +27,7 @@ I'll cover each of these methods in turn. But first, a few words about the very
 h4. Rendering by Default: Convention Over Configuration in Action
-You've heard that Rails promotes "convention over configuration." Default rendering is an excellent example of this. By default, controllers in Rails automatically render views with names that correspond to valid routes. For example, if you have this code in your +BooksController+ class:
+You've heard that Rails promotes "convention over configuration". Default rendering is an excellent example of this. By default, controllers in Rails automatically render views with names that correspond to valid routes. For example, if you have this code in your +BooksController+ class:
 <ruby>
 class BooksController < ApplicationController
@@ -46,7 +46,7 @@ And you have a view file +app/views/books/index.html.erb+:
 <h1>Books are coming soon!</h1>
 </ruby>
-Rails will automatically render +app/views/books/index.html.erb+ when you navigate to +/books+ and you will see on your screen that "Books are coming soon!"
+Rails will automatically render +app/views/books/index.html.erb+ when you navigate to +/books+ and you will see "Books are coming soon!" on your screen.
 However a coming soon screen is only minimally useful, so you will soon create your +Book+ model and add the index action to +BooksController+:
@@ -58,9 +58,9 @@ class BooksController < ApplicationController
 end
 </ruby>
-Note that again, we have convention over configuration, in that there is no explicit render at the end of this index action.  The rule is that if you do not explicitly render something by the end of the controller action, rails will look for the +action_name.html.erb+ template in the controllers view path and then render that, so in this case, Rails will render the  +app/views/books/index.html.erb+ file.
+Note that we don't have explicit render at the end of the index action in accordance with "convention over configuration" principle. The rule is that if you do not explicitly render something at the end of a controller action, Rails will automatically look for the +action_name.html.erb+ template in the controller's view path and render it. So in this case, Rails will render the +app/views/books/index.html.erb+ file.
-So in our view, we want to display the properties of all the books, we could do this with an ERB template like this:
+If we want to display the properties of all the books in our view, we can do so with an ERB template like this:
 <ruby>
 <h1>Listing Books</h1>
@@ -90,7 +90,7 @@ So in our view, we want to display the properties of all the books, we could do
 <%= link_to 'New book', new_book_path %>
 </ruby>
-NOTE: The actual rendering is done by subclasses of +ActionView::TemplateHandlers+. This guide does not dig into that process, but it's important to know that the file extension on your view controls the choice of template handler. In Rails 2, the standard extensions are +.erb+ for ERB (HTML with embedded Ruby), +.rjs+ for RJS (javascript with embedded ruby) and +.builder+ for Builder (XML generator).
+NOTE: The actual rendering is done by subclasses of +ActionView::TemplateHandlers+. This guide does not dig into that process, but it's important to know that the file extension on your view controls the choice of template handler. In Rails 2, the standard extensions are +.erb+ for ERB (HTML with embedded Ruby), and +.builder+ for Builder (XML generator).
 h4. Using +render+
@@ -109,7 +109,7 @@ render :nothing => true
 If you look at the response for this using cURL, you will see the following:
 <shell>
- $ curl -i 127.0.0.1:3000/books
+$ curl -i 127.0.0.1:3000/books
 HTTP/1.1 200 OK
 Connection: close
 Date: Sun, 24 Jan 2010 09:25:18 GMT
@@ -134,11 +134,10 @@ If you want to render the view that corresponds to a different action within the
 <ruby>
 def update
   @book = Book.find(params[:id])
-    if @book.update_attributes(params[:book])
-      redirect_to(@book)
-    else
-      render "edit"
-    end
+  if @book.update_attributes(params[:book])
+    redirect_to(@book)
+  else
+    render "edit"
   end
 end
 </ruby>
@@ -150,11 +149,10 @@ If you prefer, you can use a symbol instead of a string to specify the action to
 <ruby>
 def update
   @book = Book.find(params[:id])
-    if @book.update_attributes(params[:book])
-      redirect_to(@book)
-    else
-      render :edit
-    end
+  if @book.update_attributes(params[:book])
+    redirect_to(@book)
+  else
+    render :edit
   end
 end
 </ruby>
@@ -164,11 +162,10 @@ To be explicit, you can use +render+ with the +:action+ option (though this is n
 <ruby>
 def update
   @book = Book.find(params[:id])
-    if @book.update_attributes(params[:book])
-      redirect_to(@book)
-    else
-      render :action => "edit"
-    end
+  if @book.update_attributes(params[:book])
+    redirect_to(@book)
+  else
+    render :action => "edit"
   end
 end
 </ruby>
@@ -208,13 +205,13 @@ The +:file+ option takes an absolute file-system path. Of course, you need to ha
 NOTE: By default, the file is rendered without using the current layout. If you want Rails to put the file into the current layout, you need to add the +:layout => true+ option.
-TIP: If you're running on Microsoft Windows, you should use the +:file+ option to render a file, because Windows filenames do not have the same format as Unix filenames.
+TIP: If you're running Rails on Microsoft Windows, you should use the +:file+ option to render a file, because Windows filenames do not have the same format as Unix filenames.
 h5. Wrapping it up
-The above three methods of render (rendering another template within the controller, rendering a template within another controller and rendering an arbitrary file on the file system) are actually all variants of the same action.
+The above three ways of rendering (rendering another template within the controller, rendering a template within another controller and rendering an arbitrary file on the file system) are actually variants of the same action.
-In fact, in the BooksController method, inside of the edit action where we want to render the edit template if the book does not update successfully, all of the following render calls would all render the +edit.html.erb+ template in the +views/books+ directory:
+In fact, in the BooksController class, inside of the update action where we want to render the edit template if the book does not update successfully, all of the following render calls would all render the +edit.html.erb+ template in the +views/books+ directory:
 <ruby>
 render :edit
@@ -241,30 +238,18 @@ The +render+ method can do without a view completely, if you're willing to use t
 <ruby>
 render :inline =>
-  "<% products.each do |p| %><p><%= p.name %><p><% end %>"
+  "<% products.each do |p| %><p><%= p.name %></p><% end %>"
 </ruby>
 WARNING: There is seldom any good reason to use this option. Mixing ERB into your controllers defeats the MVC orientation of Rails and will make it harder for other developers to follow the logic of your project. Use a separate erb view instead.
-By default, inline rendering uses ERb. You can force it to use Builder instead with the +:type+ option:
+By default, inline rendering uses ERB. You can force it to use Builder instead with the +:type+ option:
 <ruby>
 render :inline =>
   "xml.p {'Horrid coding practice!'}", :type => :builder
 </ruby>
-h5. Using +render+ with +:update+
-You can also render javascript-based page updates inline using the +:update+ option to +render+:
-<ruby>
-render :update do |page|
-  page.replace_html 'warning', "Invalid options supplied"
-end
-</ruby>
-WARNING: Placing javascript updates in your controller may seem to streamline small updates, but it defeats the MVC orientation of Rails and will make it harder for other developers to follow the logic of your project. We recommend using a separate rjs template instead, no matter how small the update.
 h5. Rendering Text
 You can send plain text - with no markup at all - back to the browser by using the +:text+ option to +render+:
@@ -275,11 +260,11 @@ render :text => "OK"
 TIP: Rendering pure text is most useful when you're responding to AJAX or web service requests that are expecting something other than proper HTML.
-NOTE: By default, if you use the +:text+ option the text is rendered without using the current layout. If you want Rails to put the text into the current layout, you need to add the +:layout => true+ option.
+NOTE: By default, if you use the +:text+ option, the text is rendered without using the current layout. If you want Rails to put the text into the current layout, you need to add the +:layout => true+ option.
 h5. Rendering JSON
-JSON is a javascript data format used by many AJAX libraries. Rails has built-in support for converting objects to JSON and rendering that JSON back to the browser:
+JSON is a JavaScript data format used by many AJAX libraries. Rails has built-in support for converting objects to JSON and rendering that JSON back to the browser:
 <ruby>
 render :json => @product
@@ -299,7 +284,7 @@ TIP: You don't need to call +to_xml+ on the object that you want to render. If y
 h5. Rendering Vanilla JavaScript
-Rails can render vanilla JavaScript (as an alternative to using +update+ with an +.rjs+ file):
+Rails can render vanilla JavaScript:
 <ruby>
 render :js => "alert('Hello Rails');"
@@ -342,7 +327,7 @@ render :layout => false
 h6. The +:status+ Option
-Rails will automatically generate a response with the correct HTML status code (in most cases, this is +200 OK+). You can use the +:status+ option to change this:
+Rails will automatically generate a response with the correct HTTP status code (in most cases, this is +200 OK+). You can use the +:status+ option to change this:
 <ruby>
 render :status => 500
@@ -409,7 +394,7 @@ end
 Now, if the current user is a special user, they'll get a special layout when viewing a product. You can even use an inline method to determine the layout:
-You can also decide the layout by passing a Proc object, the block you give the Proc will be given the +controller+ instance, so you can make decisions based on the current request.  For example:
+You can also decide the layout by passing a Proc object, the block you give the Proc will be given the +controller+ instance, so you can make decisions based on the current request. For example:
 <ruby>
 class ProductsController < ApplicationController
@@ -498,7 +483,7 @@ def show
 end
 </ruby>
-If +@book.special?+ evaluates to +true+, Rails will start the rendering process to dump the +@book+ variable into the +special_show+ view. But this will _not_ stop the rest of the code in the +show+ action from running, and when Rails hits the end of the action, it will start to render the +show+ view - and throw an error. The solution is simple: make sure that you only have one call to +render+ or +redirect+ in a single code path. One thing that can help is +and return+. Here's a patched version of the method:
+If +@book.special?+ evaluates to +true+, Rails will start the rendering process to dump the +@book+ variable into the +special_show+ view. But this will _not_ stop the rest of the code in the +show+ action from running, and when Rails hits the end of the action, it will start to render the +regular_show+ view - and throw an error. The solution is simple: make sure that you have only one call to +render+ or +redirect+ in a single code path. One thing that can help is +and return+. Here's a patched version of the method:
 <ruby>
 def show
@@ -568,7 +553,7 @@ def show
 end
 </ruby>
-With the code in this form, there will be likely be a problem if the +@book+ variable is +nil+. Remember, a +render :action+ doesn't run any code in the target action, so nothing will set up the +@books+ variable that the +index+ view is presumably depending on. One way to fix this is to redirect instead of rendering:
+With the code in this form, there will likely be a problem if the +@book+ variable is +nil+. Remember, a +render :action+ doesn't run any code in the target action, so nothing will set up the +@books+ variable that the +index+ view is presumably depending on. One way to fix this is to redirect instead of rendering:
 <ruby>
 def index
@@ -585,9 +570,9 @@ end
 With this code, the browser will make a fresh request for the index page, the code in the +index+ method will run, and all will be well.
-The only downside to this code, is that it requires a round trip to the browser, the browser requested the show action with +/books/1+ and the controller finds that there are no books, so the controller sends out a 301 redirect response to the browser telling it to go to +/books/+, the browser complies and sends a new request back to the controller asking now for the +index+ action, the controller then gets all the books in the database and renders the index template, sending it back down to the browser which then shows it on your screen.
+The only downside to this code, is that it requires a round trip to the browser, the browser requested the show action with +/books/1+ and the controller finds that there are no books, so the controller sends out a 302 redirect response to the browser telling it to go to +/books/+, the browser complies and sends a new request back to the controller asking now for the +index+ action, the controller then gets all the books in the database and renders the index template, sending it back down to the browser which then shows it on your screen.
-While in a small app, this added latency might not be a problem, it is something to think about when speed of response is of the essence.  One way to handle this double request (though a contrived example) could be:
+While in a small app, this added latency might not be a problem, it is something to think about when speed of response is of the essence. One way to handle this double request (though a contrived example) could be:
 <ruby>
 def index
@@ -603,7 +588,7 @@ def show
 end
 </ruby>
-Which would detect that there are no books populate the +@books+ instance variable with all the books in the database and then directly render the +index.html.erb+ template returning it to the browser with a flash alert message telling the user what happened.
+Which would detect that there are no books, populate the +@books+ instance variable with all the books in the database and then directly render the +index.html.erb+ template returning it to the browser with a flash alert message telling the user what happened.
 h4. Using +head+ To Build Header-Only Responses
@@ -684,7 +669,7 @@ There are three tag options available for +auto_discovery_link_tag+:
 * +:type+ specifies an explicit MIME type. Rails will generate an appropriate MIME type automatically.
 * +:title+ specifies the title of the link
-h5. Linking to Javascript Files with +javascript_include_tag+
+h5. Linking to JavaScript Files with +javascript_include_tag+
 The +javascript_include_tag+ helper returns an HTML +script+ tag for each source provided. Rails looks in +public/javascripts+ for these files by default, but you can specify a full path relative to the document root, or a URL, if you prefer. For example, to include +public/javascripts/main.js+:
@@ -710,25 +695,35 @@ To include +http://example.com/main.js+:
 <%= javascript_include_tag "http://example.com/main.js" %>
 </erb>
-The +defaults+ option loads the Prototype and Scriptaculous libraries:
+If the application does not use the asset pipeline, the +:defaults+ option loads jQuery by default:
 <erb>
 <%= javascript_include_tag :defaults %>
 </erb>
-The +all+ option loads every javascript file in +public/javascripts+, starting with the Prototype and Scriptaculous libraries:
+And you can in any case override the expansion in <tt>config/application.rb</tt>:
+<ruby>
+config.action_view.javascript_expansions[:defaults] = %w(foo.js bar.js)
+</ruby>
+When using <tt>:defaults</tt>, if an <tt>application.js</tt> file exists in <tt>public/javascripts</tt> it will be included as well at then end.
+Also, the +:all+ option loads every JavaScript file in +public/javascripts+:
 <erb>
 <%= javascript_include_tag :all %>
 </erb>
+Note that your defaults of choice will be included first, so they will be available to all subsequently included files.
 You can supply the +:recursive+ option to load files in subfolders of +public/javascripts+ as well:
 <erb>
 <%= javascript_include_tag :all, :recursive => true %>
 </erb>
-If you're loading multiple javascript files, you can create a better user experience by combining multiple files into a single download. To make this happen in production, specify +:cache => true+ in your +javascript_include_tag+:
+If you're loading multiple JavaScript files, you can create a better user experience by combining multiple files into a single download. To make this happen in production, specify +:cache => true+ in your +javascript_include_tag+:
 <erb>
 <%= javascript_include_tag "main", "columns", :cache => true %>
@@ -804,7 +799,9 @@ You can even use dynamic paths such as +cache/#{current_site}/main/display+.
 h5. Linking to Images with +image_tag+
-The +image_tag+ helper builds an HTML +&lt;img /&gt;+ tag to the specified file. By default, files are loaded from +public/images+, note, you must specify the extension, previous versions of Rails would allow you to just call the image name and would append +.png+ if no extension was given, Rails 3.0 does not.
+The +image_tag+ helper builds an HTML +&lt;img /&gt;+ tag to the specified file. By default, files are loaded from +public/images+.
+WARNING: Note that you must specify the extension of the image. Previous versions of Rails would allow you to just use the image name and would append +.png+ if no extension was given but Rails 3.0 does not.
 <erb>
 <%= image_tag "header.png" %>
@@ -841,7 +838,7 @@ You can also specify a special size tag, in the format "{width}x{height}":
 <%= image_tag "home.gif", :size => "50x20" %>
 </erb>
-In addition to the above special tags, you can supply a final hash of standard HTML options, such as +:class+ or +:id+ or +:name+:
+In addition to the above special tags, you can supply a final hash of standard HTML options, such as +:class+, +:id+ or +:name+:
 <erb>
 <%= image_tag "home.gif", :alt => "Go Home",
@@ -863,7 +860,7 @@ Produces
 <video src="/videos/movie.ogg" />
 </erb>
-Like an +image_tag+ you can supply a path, either absolute, or relative to the +public/videos+ directory.  Additionally you can specify the +:size => "#{width}x#{height}"+ option just like an +image_tag+.  Video tags can also have any of the HTML options specified at the end (+id+, +class+ et al).
+Like an +image_tag+ you can supply a path, either absolute, or relative to the +public/videos+ directory. Additionally you can specify the +:size => "#{width}x#{height}"+ option just like an +image_tag+. Video tags can also have any of the HTML options specified at the end (+id+, +class+ et al).
 The video tag also supports all of the +&lt;video&gt;+ HTML options through the HTML options hash, including:
@@ -961,7 +958,7 @@ The result of rendering this page into the supplied layout would be this HTML:
 </html>
 </erb>
-The +content_for+ method is very helpful when your layout contains distinct regions such as sidebars and footers that should get their own blocks of content inserted. It's also useful for inserting tags that load page-specific javascript or css files into the header of an otherwise generic layout.
+The +content_for+ method is very helpful when your layout contains distinct regions such as sidebars and footers that should get their own blocks of content inserted. It's also useful for inserting tags that load page-specific JavaScript or css files into the header of an otherwise generic layout.
 h4. Using Partials
@@ -1007,11 +1004,13 @@ h5. Partial Layouts
 A partial can use its own layout file, just as a view can use a layout. For example, you might call a partial like this:
 <erb>
-<%= render "link_area", :layout => "graybar" %>
+<%= render :partial => "link_area", :layout => "graybar" %>
 </erb>
 This would look for a partial named +_link_area.html.erb+ and render it using the layout +_graybar.html.erb+. Note that layouts for partials follow the same leading-underscore naming as regular partials, and are placed in the same folder with the partial that they belong to (not in the master +layouts+ folder).
+Also note that explicitly specifying +:partial+ is required when passing additional options such as +:layout+.
 h5. Passing Local Variables
 You can also pass local variables into partials, making them even more powerful and flexible. For example, you can use this technique to reduce duplication between new and edit pages, while still keeping a bit of distinct content:
@@ -1134,7 +1133,7 @@ You can also pass in arbitrary local variables to any partial you are rendering
 Would render a partial +_products.html.erb+ once for each instance of +product+ in the +@products+ instance variable passing the instance to the partial as a local variable called +item+ and to each partial, make the local variable +title+ available with the value +Products Page+.
-TIP: Rails also makes a counter variable available within a partial called by the collection, named after the member of the collection followed by +_counter+. For example, if you're rendering +@products+, within the partial you can refer to +product_counter+ to tell you how many times the partial has been rendered.  This does not work in conjunction with the +:as => :value+ option.
+TIP: Rails also makes a counter variable available within a partial called by the collection, named after the member of the collection followed by +_counter+. For example, if you're rendering +@products+, within the partial you can refer to +product_counter+ to tell you how many times the partial has been rendered. This does not work in conjunction with the +:as => :value+ option.
 You can also specify a second partial to be rendered between instances of the main partial by using the +:spacer_template+ option:
@@ -1182,12 +1181,12 @@ On pages generated by +NewsController+, you want to hide the top menu and add a
   <div id="right_menu">Right menu items here</div>
   <%= yield(:news_content) or yield %>
 <% end %>
-<%= render :file => 'layouts/application' %>
+<%= render :template => 'layouts/application' %>
 </erb>
 That's it. The News views will use the new layout, hiding the top menu and adding a new right menu inside the "content" div.
-There are several ways of getting similar results with different sub-templating schemes using this technique. Note that there is no limit in nesting levels. One can use the +ActionView::render+ method via +render :file => 'layouts/news'+ to base a new layout on the News layout. If you are sure you will not subtemplate the +News+ layout, you can replace the +yield(:news_content) or yield+ with simply +yield+.
+There are several ways of getting similar results with different sub-templating schemes using this technique. Note that there is no limit in nesting levels. One can use the +ActionView::render+ method via +render :template => 'layouts/news'+ to base a new layout on the News layout. If you are sure you will not subtemplate the +News+ layout, you can replace the +yield(:news_content) or yield+ with simply +yield+.
 h3. Changelog

data/guides/source/migrations.textile CHANGED

@@ -21,7 +21,7 @@ Before I dive into the details of a migration, here are a few examples of the so
 <ruby>
 class CreateProducts < ActiveRecord::Migration
-  def self.up
+  def up
     create_table :products do |t|
       t.string :name
       t.text :description
@@ -30,7 +30,7 @@ class CreateProducts < ActiveRecord::Migration
     end
   end
-  def self.down
+  def down
     drop_table :products
   end
 end
@@ -42,14 +42,14 @@ Migrations are not limited to changing the schema. You can also use them to fix
 <ruby>
 class AddReceiveNewsletterToUsers < ActiveRecord::Migration
-  def self.up
+  def up
     change_table :users do |t|
       t.boolean :receive_newsletter, :default => false
     end
     User.update_all ["receive_newsletter = ?", true]
   end
-  def self.down
+  def down
     remove_column :users, :receive_newsletter
   end
 end
@@ -58,6 +58,21 @@ end
 This migration adds a +receive_newsletter+ column to the +users+ table. We want it to default to +false+ for new users, but existing users are considered
 to have already opted in, so we use the User model to set the flag to +true+ for existing users.
+Rails 3.1 makes migrations smarter by providing a new <tt>change</tt> method. This method is preferred for writing constructive migrations (adding columns or tables). The migration knows how to migrate your database and reverse it when the migration is rolled back without the need to write a separate +down+ method.
+<ruby>
+class CreateProducts < ActiveRecord::Migration
+  def change
+    create_table :products do |t|
+      t.string :name
+      t.text :description
+      t.timestamps
+    end
+  end
+end
+</ruby>
 NOTE: Some "caveats":#using-models-in-your-migrations apply to using models in your migrations.
 h4. Migrations are Classes
@@ -109,14 +124,14 @@ h4. Creating a Model
 The model and scaffold generators will create migrations appropriate for adding a new model. This migration will already contain instructions for creating the relevant table. If you tell Rails what columns you want then statements for adding those will also be created. For example, running
 <shell>
-rails generate model Product name:string description:text
+$ rails generate model Product name:string description:text
 </shell>
 will create a migration that looks like this
 <ruby>
 class CreateProducts < ActiveRecord::Migration
-  def self.up
+  def change
     create_table :products do |t|
       t.string :name
       t.text :description
@@ -124,10 +139,6 @@ class CreateProducts < ActiveRecord::Migration
       t.timestamps
     end
   end
-  def self.down
-    drop_table :products
-  end
 end
 </ruby>
@@ -139,17 +150,14 @@ h4. Creating a Standalone Migration
 If you are creating migrations for other purposes (for example to add a column to an existing table) then you can use the migration generator:
 <shell>
-rails generate migration AddPartNumberToProducts
+$ rails generate migration AddPartNumberToProducts
 </shell>
 This will create an empty but appropriately named migration:
 <ruby>
 class AddPartNumberToProducts < ActiveRecord::Migration
-  def self.up
-  end
-  def self.down
+  def change
   end
 end
 </ruby>
@@ -157,38 +165,34 @@ end
 If the migration name is of the form "AddXXXToYYY" or "RemoveXXXFromYYY" and is followed by a list of column names and types then a migration containing the appropriate +add_column+ and +remove_column+ statements will be created.
 <shell>
-rails generate migration AddPartNumberToProducts part_number:string
+$ rails generate migration AddPartNumberToProducts part_number:string
 </shell>
 will generate
 <ruby>
 class AddPartNumberToProducts < ActiveRecord::Migration
-  def self.up
+  def change
     add_column :products, :part_number, :string
   end
-  def self.down
-    remove_column :products, :part_number
-  end
 end
 </ruby>
 Similarly,
 <shell>
-rails generate migration RemovePartNumberFromProducts part_number:string
+$ rails generate migration RemovePartNumberFromProducts part_number:string
 </shell>
 generates
 <ruby>
 class RemovePartNumberFromProducts < ActiveRecord::Migration
-  def self.up
+  def up
     remove_column :products, :part_number
   end
-  def self.down
+  def down
     add_column :products, :part_number, :string
   end
 end
@@ -197,27 +201,24 @@ end
 You are not limited to one magically generated column, for example
 <shell>
-rails generate migration AddDetailsToProducts part_number:string price:decimal
+$ rails generate migration AddDetailsToProducts part_number:string price:decimal
 </shell>
 generates
 <ruby>
 class AddDetailsToProducts < ActiveRecord::Migration
-  def self.up
+  def change
     add_column :products, :part_number, :string
     add_column :products, :price, :decimal
   end
-  def self.down
-    remove_column :products, :price
-    remove_column :products, :part_number
-  end
 end
 </ruby>
 As always, what has been generated for you is just a starting point. You can add or remove from it as you see fit.
+NOTE: The generated migration file for destructive migrations will still be old-style using the +up+ and +down+ methods. This is because Rails doesn't know the original data types defined when you made the original changes.
 h3. Writing a Migration
 Once you have created your migration using one of the generators it's time to get to work!
@@ -284,7 +285,7 @@ change_table :products do |t|
   t.rename :upccode, :upc_code
 end
 </ruby>
-removes the +description+ and +name+ columns, creates a +part_number+ column and adds an index on it. Finally it renames the +upccode+ column.   This is the same as doing
+removes the +description+ and +name+ columns, creates a +part_number+ column and adds an index on it. Finally it renames the +upccode+ column. This is the same as doing
 <ruby>
 remove_column :products, :description
@@ -335,7 +336,22 @@ NOTE: The +references+ helper does not actually create foreign key constraints f
 If the helpers provided by Active Record aren't enough you can use the +execute+ function to execute arbitrary SQL.
-For more details and examples of individual methods check the API documentation, in particular the documentation for "<tt>ActiveRecord::ConnectionAdapters::SchemaStatements</tt>":http://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html (which provides the methods available in the +up+ and +down+ methods),  "<tt>ActiveRecord::ConnectionAdapters::TableDefinition</tt>":http://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/TableDefinition.html (which provides the methods available on the object yielded by +create_table+) and "<tt>ActiveRecord::ConnectionAdapters::Table</tt>":http://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/Table.html (which provides the methods available on the object yielded by +change_table+).
+For more details and examples of individual methods check the API documentation, in particular the documentation for "<tt>ActiveRecord::ConnectionAdapters::SchemaStatements</tt>":http://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html (which provides the methods available in the +up+ and +down+ methods), "<tt>ActiveRecord::ConnectionAdapters::TableDefinition</tt>":http://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/TableDefinition.html (which provides the methods available on the object yielded by +create_table+) and "<tt>ActiveRecord::ConnectionAdapters::Table</tt>":http://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/Table.html (which provides the methods available on the object yielded by +change_table+).
+h4. Writing Your +change+ Method
+The +change+ method removes the need to write both +up+ and +down+ methods in those cases that Rails know how to revert the changes automatically. Currently, the +change+ method supports only these migration definitions:
+* +add_column+
+* +add_index+
+* +add_timestamp+
+* +create_table+
+* +remove_timestamps+
+* +rename_column+
+* +rename_index+
+* +rename_table+
+If you're going to use other methods, you'll have to write the +up+ and +down+ methods normally.
 h4. Writing Your +down+ Method
@@ -344,7 +360,7 @@ The +down+ method of your migration should revert the transformations done by th
 <ruby>
 class ExampleMigration < ActiveRecord::Migration
-  def self.up
+  def up
     create_table :products do |t|
       t.references :category
     end
@@ -361,7 +377,7 @@ class ExampleMigration < ActiveRecord::Migration
     rename_column :users, :email, :email_address
   end
-  def self.down
+  def down
     rename_column :users, :email_address, :email
     remove_column :users, :home_page_url
     execute "ALTER TABLE products DROP FOREIGN KEY fk_products_categories"
@@ -369,9 +385,8 @@ class ExampleMigration < ActiveRecord::Migration
   end
 end
 </ruby>
-Sometimes your migration will do something which is just plain irreversible, for example it might destroy some data. In cases like those when you can't reverse the migration you can raise +IrreversibleMigration+ from your +down+ method. If someone tries to revert your migration an error message will be
-displayed saying that it can't be done.
+Sometimes your migration will do something which is just plain irreversible, for example it might destroy some data. In cases like those when you can't reverse the migration you can raise +IrreversibleMigration+ from your +down+ method. If someone tries to revert your migration an error message will be displayed saying that it can't be done.
 h3. Running Migrations
@@ -383,7 +398,7 @@ If you specify a target version, Active Record will run the required migrations
 version is the numerical prefix on the migration's filename. For example to migrate to version 20080906120000 run
 <shell>
-rake db:migrate VERSION=20080906120000
+$ rake db:migrate VERSION=20080906120000
 </shell>
 If this is greater than the current version (i.e. it is migrating upwards) this will run the +up+ method on all migrations up to and including 20080906120000, if migrating downwards this will run the +down+ method on all the migrations down to, but not including, 20080906120000.
@@ -393,13 +408,13 @@ h4. Rolling Back
 A common task is to rollback the last migration, for example if you made a mistake in it and wish to correct it. Rather than tracking down the version number associated with the previous migration you can run
 <shell>
-rake db:rollback
+$ rake db:rollback
 </shell>
 This will run the +down+ method from the latest migration. If you need to undo several migrations you can provide a +STEP+ parameter:
 <shell>
-rake db:rollback STEP=3
+$ rake db:rollback STEP=3
 </shell>
 will run the +down+ method from the last 3 migrations.
@@ -407,7 +422,7 @@ will run the +down+ method from the last 3 migrations.
 The +db:migrate:redo+ task is a shortcut for doing a rollback and then migrating back up again. As with the +db:rollback+ task you can use the +STEP+ parameter if you need to go more than one version back, for example
 <shell>
-rake db:migrate:redo STEP=3
+$ rake db:migrate:redo STEP=3
 </shell>
 Neither of these Rake tasks do anything you could not do with +db:migrate+, they are simply more convenient since you do not need to explicitly specify the version to migrate to.
@@ -421,7 +436,7 @@ h4. Being Specific
 If you need to run a specific migration up or down the +db:migrate:up+ and +db:migrate:down+ tasks will do that. Just specify the appropriate version and the corresponding migration will have its +up+ or +down+ method invoked, for example
 <shell>
-rake db:migrate:up VERSION=20080906120000
+$ rake db:migrate:up VERSION=20080906120000
 </shell>
 will run the +up+ method from the 20080906120000 migration. These tasks check whether the migration has already run, so for example +db:migrate:up VERSION=20080906120000+ will do nothing if Active Record believes that 20080906120000 has already been run.
@@ -449,7 +464,7 @@ For example, this migration
 <ruby>
 class CreateProducts < ActiveRecord::Migration
-  def self.up
+  def change
     suppress_messages do
       create_table :products do |t|
         t.string :name
@@ -465,10 +480,6 @@ class CreateProducts < ActiveRecord::Migration
       250
     end
   end
-  def self.down
-    drop_table :products
-  end
 end
 </ruby>
@@ -499,11 +510,7 @@ class AddPartNumberToProducts < ActiveRecord::Migration
   class Product < ActiveRecord::Base
   end
-  def self.up
-    ...
-  end
-  def self.down
+  def change
     ...
   end
 end
@@ -519,15 +526,11 @@ class AddPartNumberToProducts < ActiveRecord::Migration
   class Product < ActiveRecord::Base
   end
-  def self.up
+  def change
     add_column :product, :part_number, :string
     Product.reset_column_information
     ...
   end
-  def self.down
-    ...
-  end
 end
 </ruby>
@@ -584,11 +587,12 @@ h3. Active Record and Referential Integrity
 The Active Record way claims that intelligence belongs in your models, not in the database. As such, features such as triggers or foreign key constraints, which push some of that intelligence back into the database, are not heavily used.
-Validations such as +validates_uniqueness_of+ are one way in which models can enforce data integrity. The +:dependent+ option on associations allows models to automatically destroy child objects when the parent is destroyed. Like anything which operates at the application level these cannot guarantee referential integrity and so some people augment them with foreign key constraints.
+Validations such as +validates :foreign_key, :uniqueness => true+ are one way in which models can enforce data integrity. The +:dependent+ option on associations allows models to automatically destroy child objects when the parent is destroyed. Like anything which operates at the application level these cannot guarantee referential integrity and so some people augment them with foreign key constraints.
-Although Active Record does not provide any tools for working directly with such features, the +execute+ method can be used to execute arbitrary SQL. There are also a number of plugins such as "foreign_key_migrations":http://github.com/harukizaemon/redhillonrails/tree/master/foreign_key_migrations/ which add foreign key support to Active Record (including support for dumping foreign keys in +db/schema.rb+).
+Although Active Record does not provide any tools for working directly with such features, the +execute+ method can be used to execute arbitrary SQL. There are also a number of plugins such as "foreign_key_migrations":https://github.com/harukizaemon/redhillonrails/tree/master/foreign_key_migrations/ which add foreign key support to Active Record (including support for dumping foreign keys in +db/schema.rb+).
 h3. Changelog
+* April 26, 2011: change generated +up+ and +down+ methods to +change+ method, and describe detail about +change+ method by "Prem Sichanugrist":http://sikachu.com
 * July 15, 2010: minor typos corrected by "Jaime Iniesta":http://jaimeiniesta.com
 * September 14, 2008: initial version by "Frederick Cheung":credits.html#fcheung