From 72822800d58af8352072364aa1071fe4b8ae6702 Mon Sep 17 00:00:00 2001
From: Prem Sichanugrist <s@sikachu.com>
Date: Tue, 26 Apr 2011 23:30:08 +0700
Subject: Update guide to use `change` method in various places after migration
 generator has changed.

---
 railties/guides/source/migrations.textile | 76 ++++++++++++++++---------------
 1 file changed, 39 insertions(+), 37 deletions(-)

(limited to 'railties/guides/source/migrations.textile')

diff --git a/railties/guides/source/migrations.textile b/railties/guides/source/migrations.textile
index bf5d4d3e4d..238fe3603b 100644
--- a/railties/guides/source/migrations.textile
+++ b/railties/guides/source/migrations.textile
@@ -58,6 +58,23 @@ 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.
 
+Also, you might also found a smart migration file, which was introduced in the latest version of Rails:
+
+<ruby>
+class CreateProducts < ActiveRecord::Migration
+  def change
+    create_table :products do |t|
+      t.string :name
+      t.text :description
+
+      t.timestamps
+    end
+  end
+end
+</ruby>
+
+This smart migration file knows how to migrate your database and reverse it in case you needed. It's more preferrable way to write a constructive (i.e. add column or add table) migration file.
+
 NOTE: Some "caveats":#using-models-in-your-migrations apply to using models in your migrations.
 
 h4. Migrations are Classes
@@ -116,7 +133,7 @@ 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 +141,6 @@ class CreateProducts < ActiveRecord::Migration
       t.timestamps
     end
   end
-
-  def self.down
-    drop_table :products
-  end
 end
 </ruby>
 
@@ -146,10 +159,7 @@ 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>
@@ -164,13 +174,9 @@ 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>
 
@@ -194,6 +200,8 @@ class RemovePartNumberFromProducts < ActiveRecord::Migration
 end
 </ruby>
 
+NOTE: The generated migration file for destructive migration will be created using the old-style migration with +up+ and +down+ method. This because Rails doesn't know the original data type defined when you added the column.
+
 You are not limited to one magically generated column, for example
 
 <shell>
@@ -204,15 +212,10 @@ 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>
 
@@ -337,6 +340,17 @@ If the helpers provided by Active Record aren't enough you can use the +execute+
 
 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 of your migration reduce the need for you having to write both +up+ and +down+ method in some case that Rails knows how to revert it. Rails will revert the changes automatically when you rollback your change. Currently, +change+ method only support these migration definitions:
+
+* +create_table+
+* +add_column+
+* +rename_column+
+* +add_index+
+
+If you're going to use another methods, you'll have to write both +up+ and +down+ method normally.
+
 h4. Writing Your +down+ Method
 
 The +down+ method of your migration should revert the transformations done by the +up+ method. In other words the database schema should be unchanged if you do an +up+ followed by a +down+. For example if you create a table in the +up+ method you should drop it in the +down+ method. It is wise to do things in precisely the reverse order to in the +up+ method. For example
@@ -369,9 +383,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
 
@@ -449,7 +462,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 +478,6 @@ class CreateProducts < ActiveRecord::Migration
       250
     end
   end
-
-  def self.down
-    drop_table :products
-  end
 end
 </ruby>
 
@@ -499,11 +508,7 @@ class AddPartNumberToProducts < ActiveRecord::Migration
   class Product < ActiveRecord::Base
   end
 
-  def self.up
-    ...
-  end
-
-  def self.down
+  def change
     ...
   end
 end
@@ -519,15 +524,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>
 
@@ -590,5 +591,6 @@ Although Active Record does not provide any tools for working directly with such
 
 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
-- 
cgit v1.2.3


From d4259d8932c9fe4128bd4b0876f9e48085035032 Mon Sep 17 00:00:00 2001
From: Prem Sichanugrist <s@sikachu.com>
Date: Tue, 26 Apr 2011 23:33:39 +0700
Subject: Change from `self.(up|down)` to `(up|down)` method

---
 railties/guides/source/migrations.textile | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

(limited to 'railties/guides/source/migrations.textile')

diff --git a/railties/guides/source/migrations.textile b/railties/guides/source/migrations.textile
index 238fe3603b..39f8a458a0 100644
--- a/railties/guides/source/migrations.textile
+++ b/railties/guides/source/migrations.textile
@@ -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
@@ -190,11 +190,11 @@ 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
@@ -358,7 +358,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
@@ -375,7 +375,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"
-- 
cgit v1.2.3


From b105dc441b078e3b0db1affc94f970c6233ee709 Mon Sep 17 00:00:00 2001
From: Vijay Dev <vijaydev.cse@gmail.com>
Date: Tue, 26 Apr 2011 23:18:55 +0530
Subject: minor changes in migrations guide

---
 railties/guides/source/migrations.textile | 12 +++++-------
 1 file changed, 5 insertions(+), 7 deletions(-)

(limited to 'railties/guides/source/migrations.textile')

diff --git a/railties/guides/source/migrations.textile b/railties/guides/source/migrations.textile
index 39f8a458a0..18ae8a2251 100644
--- a/railties/guides/source/migrations.textile
+++ b/railties/guides/source/migrations.textile
@@ -58,7 +58,7 @@ 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.
 
-Also, you might also found a smart migration file, which was introduced in the latest version of Rails:
+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
@@ -73,8 +73,6 @@ class CreateProducts < ActiveRecord::Migration
 end
 </ruby>
 
-This smart migration file knows how to migrate your database and reverse it in case you needed. It's more preferrable way to write a constructive (i.e. add column or add table) migration file.
-
 NOTE: Some "caveats":#using-models-in-your-migrations apply to using models in your migrations.
 
 h4. Migrations are Classes
@@ -200,8 +198,6 @@ class RemovePartNumberFromProducts < ActiveRecord::Migration
 end
 </ruby>
 
-NOTE: The generated migration file for destructive migration will be created using the old-style migration with +up+ and +down+ method. This because Rails doesn't know the original data type defined when you added the column.
-
 You are not limited to one magically generated column, for example
 
 <shell>
@@ -221,6 +217,8 @@ end
 
 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!
@@ -342,14 +340,14 @@ For more details and examples of individual methods check the API documentation,
 
 h4. Writing Your +change+ Method
 
-The +change+ method of your migration reduce the need for you having to write both +up+ and +down+ method in some case that Rails knows how to revert it. Rails will revert the changes automatically when you rollback your change. Currently, +change+ method only support these migration definitions:
+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:
 
 * +create_table+
 * +add_column+
 * +rename_column+
 * +add_index+
 
-If you're going to use another methods, you'll have to write both +up+ and +down+ method normally.
+If you're going to use other methods, you'll have to write the +up+ and +down+ methods normally.
 
 h4. Writing Your +down+ Method
 
-- 
cgit v1.2.3


From c1132f7093b29e6acb95be4d262a07d5b04082d3 Mon Sep 17 00:00:00 2001
From: Vijay Dev <vijaydev.cse@gmail.com>
Date: Tue, 26 Apr 2011 23:40:47 +0530
Subject: added the list of reversible commands in the newer migrations

---
 railties/guides/source/migrations.textile | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

(limited to 'railties/guides/source/migrations.textile')

diff --git a/railties/guides/source/migrations.textile b/railties/guides/source/migrations.textile
index 18ae8a2251..27f8a9303e 100644
--- a/railties/guides/source/migrations.textile
+++ b/railties/guides/source/migrations.textile
@@ -342,10 +342,14 @@ 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:
 
-* +create_table+
 * +add_column+
-* +rename_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.
 
-- 
cgit v1.2.3

