Introduce versioned GitLab migration class

This introduces a versioned parent class for database migrations.

This implements a simple versioning scheme for migration helpers.

We need to be able to version helpers, so we can change their behavior
without altering the behavior of already existing migrations in
incompatible ways.

We can continue to change the behavior of helpers without bumping the
version here, *if* the change is backwards-compatible.

If not, we would typically override the helper method in a new
MigrationHelpers::V[0-9]+ class and create a new entry with a bumped
version below.

We use major version bumps to indicate significant changes and minor
version bumps to indicate backwards-compatible or otherwise minor
changes (e.g. a Rails version bump). However, this hasn't been
strictly formalized yet.

Changelog: other

generator_templates/active_record/migration/migration.rb

@@ -3,10 +3,7 @@
 # See https://docs.gitlab.com/ee/development/migration_style_guide.html
 # for more information on how to write migrations for GitLab.
 
-class <%= migration_class_name %> < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
-  # Uncomment the following include if you require helper functions:
-  # include Gitlab::Database::MigrationHelpers
-
+class <%= migration_class_name %> < Gitlab::Database::Migration[<%= Gitlab::Database::Migration.current_version %>]
   # When using the methods "add_concurrent_index" or "remove_concurrent_index"
   # you must disable the use of transactions
   # as these methods can not run in an existing transaction.

generator_templates/post_deployment_migration/post_deployment_migration/migration.rb

@@ -3,10 +3,7 @@
 # See https://docs.gitlab.com/ee/development/migration_style_guide.html
 # for more information on how to write migrations for GitLab.
 
-class <%= migration_class_name %> < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
-  # Uncomment the following include if you require helper functions:
-  # include Gitlab::Database::MigrationHelpers
-
+class <%= migration_class_name %> < Gitlab::Database::Migration[<%= Gitlab::Database::Migration.current_version %>]
   # When using the methods "add_concurrent_index" or "remove_concurrent_index"
   # you must disable the use of transactions
   # as these methods can not run in an existing transaction.
@@ -20,6 +17,9 @@ class <%= migration_class_name %> < ActiveRecord::Migration[<%= ActiveRecord::Mi
   # comments:
   # disable_ddl_transaction!
 
-  def change
+  def up
+  end
+
+  def down
   end
 end

lib/gitlab/database/migration.rb

+# frozen_string_literal: true
+
+module Gitlab
+  module Database
+    class Migration
+      # This implements a simple versioning scheme for migration helpers.
+      #
+      # We need to be able to version helpers, so we can change their behavior without
+      # altering the behavior of already existing migrations in incompatible ways.
+      #
+      # We can continue to change the behavior of helpers without bumping the version here,
+      # *if* the change is backwards-compatible.
+      #
+      # If not, we would typically override the helper method in a new MigrationHelpers::V[0-9]+
+      # class and create a new entry with a bumped version below.
+      #
+      # We use major version bumps to indicate significant changes and minor version bumps
+      # to indicate backwards-compatible or otherwise minor changes (e.g. a Rails version bump).
+      # However, this hasn't been strictly formalized yet.
+      MIGRATION_CLASSES = {
+        1.0 => Class.new(ActiveRecord::Migration[6.1]) do
+          include Gitlab::Database::MigrationHelpers::V2
+        end
+      }.freeze
+
+      def self.[](version)
+        MIGRATION_CLASSES[version] || raise(ArgumentError, "Unknown migration version: #{version}")
+      end
+
+      # The current version to be used in new migrations
+      def self.current_version
+        1.0
+      end
+    end
+  end
+end

spec/lib/gitlab/database/migration_spec.rb

+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Gitlab::Database::Migration do
+  describe '.[]' do
+    context 'version: 1.0' do
+      subject { described_class[1.0] }
+
+      it 'inherits from ActiveRecord::Migration[6.1]' do
+        expect(subject.superclass).to eq(ActiveRecord::Migration[6.1])
+      end
+
+      it 'includes migration helpers version 2' do
+        expect(subject.included_modules).to include(Gitlab::Database::MigrationHelpers::V2)
+      end
+    end
+
+    context 'unknown version' do
+      it 'raises an error' do
+        expect { described_class[0] }.to raise_error(ArgumentError, /Unknown migration version/)
+      end
+    end
+  end
+
+  describe '.current_version' do
+    it 'includes current ActiveRecord migration class' do
+      # This breaks upon Rails upgrade. In that case, we'll add a new version in Gitlab::Database::Migration::MIGRATION_CLASSES,
+      # bump .current_version and leave existing migrations and already defined versions of Gitlab::Database::Migration
+      # untouched.
+      expect(described_class[described_class.current_version].superclass).to eq(ActiveRecord::Migration::Current)
+    end
+  end
+end