Merge pull request #21538 from matthewd/migration-version

Add migration versioning via Migration subclasses

8 files changed, 106 insertions, 22 deletions

diff --git a/activerecord/lib/active_record/associations.rb b/activerecord/lib/active_record/associations.rb
index b806a2f832..04ad45f5da 100644
--- a/activerecord/lib/active_record/associations.rb
+++ b/activerecord/lib/active_record/associations.rb
@@ -1639,7 +1639,7 @@ module ActiveRecord
       # The join table should not have a primary key or a model associated with it. You must manually generate the
       # join table with a migration such as this:
       #
-      #   class CreateDevelopersProjectsJoinTable < ActiveRecord::Migration
+      #   class CreateDevelopersProjectsJoinTable < ActiveRecord::Migration[5.0]
       #     def change
       #       create_join_table :developers, :projects
       #     end
diff --git a/activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb b/activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb
index 159cbcb85a..1cda23dc1d 100644
--- a/activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb
+++ b/activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb
@@ -190,7 +190,7 @@ module ActiveRecord
     # Inside migration files, the +t+ object in {create_table}[rdoc-ref:SchemaStatements#create_table]
     # is actually of this type:
     #
-    #   class SomeMigration < ActiveRecord::Migration
+    #   class SomeMigration < ActiveRecord::Migration[5.0]
     #     def up
     #       create_table :foo do |t|
     #         puts t.class  # => "ActiveRecord::ConnectionAdapters::TableDefinition"
diff --git a/activerecord/lib/active_record/migration.rb b/activerecord/lib/active_record/migration.rb
index ca2537cdc3..43726d795e 100644
--- a/activerecord/lib/active_record/migration.rb
+++ b/activerecord/lib/active_record/migration.rb
@@ -13,7 +13,7 @@ module ActiveRecord
   # For example the following migration is not reversible.
   # Rolling back this migration will raise an ActiveRecord::IrreversibleMigration error.
   #
-  #   class IrreversibleMigrationExample < ActiveRecord::Migration
+  #   class IrreversibleMigrationExample < ActiveRecord::Migration[5.0]
   #     def change
   #       create_table :distributors do |t|
   #         t.string :zipcode
@@ -31,7 +31,7 @@ module ActiveRecord
   #
   # 1. Define <tt>#up</tt> and <tt>#down</tt> methods instead of <tt>#change</tt>:
   #
-  #  class ReversibleMigrationExample < ActiveRecord::Migration
+  #  class ReversibleMigrationExample < ActiveRecord::Migration[5.0]
   #    def up
   #      create_table :distributors do |t|
   #        t.string :zipcode
@@ -56,7 +56,7 @@ module ActiveRecord
   #
   # 2. Use the #reversible method in <tt>#change</tt> method:
   #
-  #   class ReversibleMigrationExample < ActiveRecord::Migration
+  #   class ReversibleMigrationExample < ActiveRecord::Migration[5.0]
   #     def change
   #       create_table :distributors do |t|
   #         t.string :zipcode
@@ -155,7 +155,7 @@ module ActiveRecord
   #
   # Example of a simple migration:
   #
-  #   class AddSsl < ActiveRecord::Migration
+  #   class AddSsl < ActiveRecord::Migration[5.0]
   #     def up
   #       add_column :accounts, :ssl_enabled, :boolean, default: true
   #     end
@@ -175,7 +175,7 @@ module ActiveRecord
   #
   # Example of a more complex migration that also needs to initialize data:
   #
-  #   class AddSystemSettings < ActiveRecord::Migration
+  #   class AddSystemSettings < ActiveRecord::Migration[5.0]
   #     def up
   #       create_table :system_settings do |t|
   #         t.string  :name
@@ -301,7 +301,7 @@ module ActiveRecord
   #   rails generate migration add_fieldname_to_tablename fieldname:string
   #
   # This will generate the file <tt>timestamp_add_fieldname_to_tablename.rb</tt>, which will look like this:
-  #   class AddFieldnameToTablename < ActiveRecord::Migration
+  #   class AddFieldnameToTablename < ActiveRecord::Migration[5.0]
   #     def change
   #       add_column :tablenames, :fieldname, :string
   #     end
@@ -332,7 +332,7 @@ module ActiveRecord
   #
   # Not all migrations change the schema. Some just fix the data:
   #
-  #   class RemoveEmptyTags < ActiveRecord::Migration
+  #   class RemoveEmptyTags < ActiveRecord::Migration[5.0]
   #     def up
   #       Tag.all.each { |tag| tag.destroy if tag.pages.empty? }
   #     end
@@ -345,7 +345,7 @@ module ActiveRecord
   #
   # Others remove columns when they migrate up instead of down:
   #
-  #   class RemoveUnnecessaryItemAttributes < ActiveRecord::Migration
+  #   class RemoveUnnecessaryItemAttributes < ActiveRecord::Migration[5.0]
   #     def up
   #       remove_column :items, :incomplete_items_count
   #       remove_column :items, :completed_items_count
@@ -359,7 +359,7 @@ module ActiveRecord
   #
   # And sometimes you need to do something in SQL not abstracted directly by migrations:
   #
-  #   class MakeJoinUnique < ActiveRecord::Migration
+  #   class MakeJoinUnique < ActiveRecord::Migration[5.0]
   #     def up
   #       execute "ALTER TABLE `pages_linked_pages` ADD UNIQUE `page_id_linked_page_id` (`page_id`,`linked_page_id`)"
   #     end
@@ -376,7 +376,7 @@ module ActiveRecord
   # <tt>Base#reset_column_information</tt> in order to ensure that the model has the
   # latest column data from after the new column was added. Example:
   #
-  #   class AddPeopleSalary < ActiveRecord::Migration
+  #   class AddPeopleSalary < ActiveRecord::Migration[5.0]
   #     def up
   #       add_column :people, :salary, :integer
   #       Person.reset_column_information
@@ -434,7 +434,7 @@ module ActiveRecord
   # To define a reversible migration, define the +change+ method in your
   # migration like this:
   #
-  #   class TenderloveMigration < ActiveRecord::Migration
+  #   class TenderloveMigration < ActiveRecord::Migration[5.0]
   #     def change
   #       create_table(:horses) do |t|
   #         t.column :content, :text
@@ -464,7 +464,7 @@ module ActiveRecord
   # can't execute inside a transaction though, and for these situations
   # you can turn the automatic transactions off.
   #
-  #   class ChangeEnum < ActiveRecord::Migration
+  #   class ChangeEnum < ActiveRecord::Migration[5.0]
   #     disable_ddl_transaction!
   #
   #     def up
@@ -476,6 +476,32 @@ module ActiveRecord
   # are in a Migration with <tt>self.disable_ddl_transaction!</tt>.
   class Migration
     autoload :CommandRecorder, 'active_record/migration/command_recorder'
+    autoload :Compatibility, 'active_record/migration/compatibility'
+
+    # This must be defined before the inherited hook, below
+    class Current < Migration # :nodoc:
+    end
+
+    def self.inherited(subclass) # :nodoc:
+      super
+      if subclass.superclass == Migration
+        subclass.include Compatibility::Legacy
+      end
+    end
+
+    def self.[](version)
+      version = version.to_s
+      name = "V#{version.tr('.', '_')}"
+      unless Compatibility.const_defined?(name)
+        versions = Compatibility.constants.grep(/\AV[0-9_]+\z/).map { |s| s.to_s.delete('V').tr('_', '.').inspect }
+        raise "Unknown migration version #{version.inspect}; expected one of #{versions.sort.join(', ')}"
+      end
+      Compatibility.const_get(name)
+    end
+
+    def self.current_version
+      Rails.version.to_f
+    end
 
     MigrationFilenameRegexp = /\A([0-9]+)_([_a-z0-9]*)\.?([_a-z0-9]*)?\.rb\z/ # :nodoc:
 
@@ -509,6 +535,10 @@ module ActiveRecord
       attr_accessor :delegate # :nodoc:
       attr_accessor :disable_ddl_transaction # :nodoc:
 
+      def nearest_delegate # :nodoc:
+        delegate || superclass.nearest_delegate
+      end
+
       # Raises <tt>ActiveRecord::PendingMigrationError</tt> error if any migrations are pending.
       def check_pending!(connection = Base.connection)
         raise ActiveRecord::PendingMigrationError if ActiveRecord::Migrator.needs_migration?(connection)
@@ -535,7 +565,7 @@ module ActiveRecord
       end
 
       def method_missing(name, *args, &block) # :nodoc:
-        (delegate || superclass.delegate).send(name, *args, &block)
+        nearest_delegate.send(name, *args, &block)
       end
 
       def migrate(direction)
@@ -575,7 +605,7 @@ module ActiveRecord
     # and create the table 'apples' on the way up, and the reverse
     # on the way down.
     #
-    #   class FixTLMigration < ActiveRecord::Migration
+    #   class FixTLMigration < ActiveRecord::Migration[5.0]
     #     def change
     #       revert do
     #         create_table(:horses) do |t|
@@ -594,7 +624,7 @@ module ActiveRecord
     #
     #   require_relative '20121212123456_tenderlove_migration'
     #
-    #   class FixupTLMigration < ActiveRecord::Migration
+    #   class FixupTLMigration < ActiveRecord::Migration[5.0]
     #     def change
     #       revert TenderloveMigration
     #
@@ -647,7 +677,7 @@ module ActiveRecord
     # when the three columns 'first_name', 'last_name' and 'full_name' exist,
     # even when migrating down:
     #
-    #    class SplitNameMigration < ActiveRecord::Migration
+    #    class SplitNameMigration < ActiveRecord::Migration[5.0]
     #      def change
     #        add_column :users, :first_name, :string
     #        add_column :users, :last_name, :string
diff --git a/activerecord/lib/active_record/migration/compatibility.rb b/activerecord/lib/active_record/migration/compatibility.rb
new file mode 100644
index 0000000000..4c8db8a2d5
--- /dev/null
+++ b/activerecord/lib/active_record/migration/compatibility.rb
@@ -0,0 +1,54 @@
+module ActiveRecord
+  class Migration
+    module Compatibility # :nodoc: all
+      V5_0 = Current
+
+      module FourTwoShared
+        module TableDefinition
+          def timestamps(*, **options)
+            options[:null] = true if options[:null].nil?
+            super
+          end
+        end
+
+        def create_table(table_name, options = {})
+          if block_given?
+            super(table_name, options) do |t|
+              class << t
+                prepend TableDefinition
+              end
+              yield t
+            end
+          else
+            super
+          end
+        end
+
+        def add_timestamps(*, **options)
+          options[:null] = true if options[:null].nil?
+          super
+        end
+      end
+
+      class V4_2 < V5_0
+        # 4.2 is defined as a module because it needs to be shared with
+        # Legacy. When the time comes, V5_0 should be defined straight
+        # in its class.
+        include FourTwoShared
+      end
+
+      module Legacy
+        include FourTwoShared
+
+        def run(*)
+          ActiveSupport::Deprecation.warn \
+            "Directly inheriting from ActiveRecord::Migration is deprecated. " \
+            "Please specify the Rails release the migration was written for:\n" \
+            "\n" \
+            "  class #{self.class.name} < ActiveRecord::Migration[4.2]"
+          super
+        end
+      end
+    end
+  end
+end
diff --git a/activerecord/lib/active_record/model_schema.rb b/activerecord/lib/active_record/model_schema.rb
index e3f304b0af..5df67cdbe7 100644
--- a/activerecord/lib/active_record/model_schema.rb
+++ b/activerecord/lib/active_record/model_schema.rb
@@ -275,7 +275,7 @@ module ActiveRecord
       # when just after creating a table you want to populate it with some default
       # values, eg:
       #
-      #  class CreateJobLevels < ActiveRecord::Migration
+      #  class CreateJobLevels < ActiveRecord::Migration[5.0]
       #    def up
       #      create_table :job_levels do |t|
       #        t.integer :id
diff --git a/activerecord/lib/active_record/schema.rb b/activerecord/lib/active_record/schema.rb
index 31dd584538..fdf9965a82 100644
--- a/activerecord/lib/active_record/schema.rb
+++ b/activerecord/lib/active_record/schema.rb
@@ -27,7 +27,7 @@ module ActiveRecord
   #
   # ActiveRecord::Schema is only supported by database adapters that also
   # support migrations, the two features being very similar.
-  class Schema < Migration
+  class Schema < Migration::Current
     # Eval the given block. All methods available to the current connection
     # adapter are available within the block, so you can easily use the
     # database definition DSL to build up your schema (
diff --git a/activerecord/lib/rails/generators/active_record/migration/templates/create_table_migration.rb b/activerecord/lib/rails/generators/active_record/migration/templates/create_table_migration.rb
index fadab2a1e6..5f7201cfe1 100644
--- a/activerecord/lib/rails/generators/active_record/migration/templates/create_table_migration.rb
+++ b/activerecord/lib/rails/generators/active_record/migration/templates/create_table_migration.rb
@@ -1,4 +1,4 @@
-class <%= migration_class_name %> < ActiveRecord::Migration
+class <%= migration_class_name %> < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
   def change
     create_table :<%= table_name %><%= primary_key_type %> do |t|
 <% attributes.each do |attribute| -%>
diff --git a/activerecord/lib/rails/generators/active_record/migration/templates/migration.rb b/activerecord/lib/rails/generators/active_record/migration/templates/migration.rb
index 23a377db6a..107f107dc4 100644
--- a/activerecord/lib/rails/generators/active_record/migration/templates/migration.rb
+++ b/activerecord/lib/rails/generators/active_record/migration/templates/migration.rb
@@ -1,4 +1,4 @@
-class <%= migration_class_name %> < ActiveRecord::Migration
+class <%= migration_class_name %> < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
 <%- if migration_action == 'add' -%>
   def change
 <% attributes.each do |attribute| -%>