spree_core 6.0.0.rc6 → 6.0.0

data/app/models/spree/maintenance_task.rb

@@ -0,0 +1,221 @@
+module Spree
+  # Base class for the data work an upgrade runs: one step of an upgrade
+  # manifest (docs/plans/6.0-maintenance-tasks.md).
+  #
+  # A task walks a stable-ordered collection and processes one record at a
+  # time. The runner (Spree::MaintenanceTasks::RunJob) supplies batching,
+  # checkpointing, cancelling and the audit row, so a task body says
+  # only what it does.
+  #
+  #   class Spree::MaintenanceTasks::Upgrade::BackfillOrderMarkets < Spree::MaintenanceTask
+  #     supports_dry_run
+  #
+  #     def collection
+  #       Spree::Order.where(market_id: nil).order(:id)
+  #     end
+  #
+  #     def process(order)
+  #       return tally(:would_update) if dry_run?
+  #
+  #       order.update_columns(market_id: order.store.default_market.id)
+  #       tally(:updated)
+  #     end
+  #   end
+  #
+  # A manifest step names its task class, which registers it in
+  # `Spree.maintenance_tasks`; nothing else is runnable.
+  class MaintenanceTask
+    include ActiveModel::Model
+    include ActiveModel::Attributes
+    extend Spree::ApiTyped
+
+    # A rake body that stopped itself with `abort`.
+    class RakeTaskAborted < StandardError; end
+
+    # Two threads of one worker must not both find a task undefined and both
+    # load its file — the second load would make the task run twice.
+    RAKE_LOAD_LOCK = Mutex.new
+
+    DEFAULT_BATCH_SIZE = 100
+
+    # How long one execution may run before the runner checkpoints and
+    # re-enqueues itself, so a long step cannot hold a worker indefinitely.
+    MAX_RUN_TIME = 5.minutes
+
+    class_attribute :dry_run_supported, instance_writer: false, default: false
+    class_attribute :collection_kind, instance_writer: false, default: :relation
+    class_attribute :batch_size, instance_writer: false, default: DEFAULT_BATCH_SIZE
+
+    attr_accessor :run
+
+    class << self
+      # Declares that `process` honors `dry_run?`. The runner never fakes a
+      # dry run by rolling a transaction back, which would silently lie about
+      # external calls, enqueued jobs and cache writes.
+      def supports_dry_run
+        self.dry_run_supported = true
+      end
+
+      # The task performs a single operation instead of iterating; `process`
+      # is called once with no argument.
+      def no_collection
+        self.collection_kind = :none
+      end
+
+      def collection_batch_size(size)
+        self.batch_size = size
+      end
+
+      # @return [Array<Class>] registered task classes, sorted by name
+      def registered_classes
+        Spree.maintenance_tasks.filter_map do |entry|
+          entry.is_a?(Class) ? entry : entry.to_s.safe_constantize
+        end.uniq.sort_by(&:name)
+      end
+
+      # @param name [String] a task class name
+      # @return [Class, nil] nil when the name is not registered — an
+      #   unregistered task is never runnable, so the runner and the API can
+      #   treat nil as "no such task" without a second check
+      def find_registered(name)
+        return nil if name.blank?
+
+        registered_classes.find { |klass| klass.name == name.to_s }
+      end
+
+      # A task class name as the API shows it. A task that is no longer
+      # registered is shortened the same way rather than loaded by name.
+      #
+      # @param class_name [String]
+      # @return [String]
+      def api_type_for(class_name)
+        find_registered(class_name)&.api_type || class_name.to_s.demodulize.underscore
+      end
+
+      # The registered task an API caller names. Matches the short name only,
+      # so a Ruby class name arriving over the API is an unknown task.
+      #
+      # @param api_type [String] e.g. "capture_methods"
+      # @return [Class, nil]
+      def find_by_api_type(api_type)
+        Spree::ApiTyped.find(Spree.maintenance_tasks, api_type)
+      end
+    end
+
+    # The records to walk, ordered by primary key — the cursor is the last id
+    # processed, so any other order would resume in the wrong place.
+    #
+    # @return [ActiveRecord::Relation]
+    def collection
+      raise NotImplementedError, "#{self.class.name} must implement #collection or declare `no_collection`"
+    end
+
+    # @param item [Object] one record from the collection; omitted for
+    #   `no_collection` tasks
+    def process(item = nil)
+      raise NotImplementedError, "#{self.class.name} must implement #process"
+    end
+
+    # Total records, for the progress bar. Return nil when counting is more
+    # expensive than the work itself — the run then reports ticks only.
+    #
+    # @return [Integer, nil]
+    def count
+      collection.count unless no_collection?
+    end
+
+    def no_collection?
+      self.class.collection_kind == :none
+    end
+
+    def dry_run?
+      run&.dry_run? || false
+    end
+
+    # Records a counter shown on the run page: what was updated, skipped, or
+    # would have changed in a dry run.
+    def tally(key, by = 1)
+      @tallies ||= Hash.new(0)
+      @tallies[key.to_s] += by
+    end
+
+    def tallies
+      @tallies ||= Hash.new(0)
+    end
+
+    # Runs an engine rake task as part of this task.
+    #
+    # Rake bodies stop themselves with `abort`, which raises SystemExit — not
+    # an error the runner records. Left alone it would end the whole process
+    # from the command line and, in a worker, leave the run marked running
+    # with nothing to finish it.
+    #
+    # @param task_name [String]
+    # @raise [RakeTaskAborted] carrying the body's own message
+    def invoke_rake_task(task_name)
+      load_engine_rake_tasks(task_name)
+
+      task = ::Rake::Task[task_name]
+      task.reenable
+      task.invoke
+    rescue SystemExit => e
+      raise RakeTaskAborted, e.message
+    end
+
+    # Finds the file that defines a task by reading the files rather than
+    # loading them: loading a .rake file to discover whether it is the right
+    # one would append its blocks to every task it defines, which is the very
+    # duplication this avoids.
+    #
+    # Searches every engine and the host application, since a step may ship in
+    # an extension gem. When two files define the same task name, the one
+    # that also declares the task's namespaces wins.
+    #
+    # @return [String, nil]
+    def rake_file_defining(task_name)
+      *namespaces, leaf = task_name.split(':')
+      candidates = rake_files.select do |path|
+        File.read(path).match?(/^\s*(?:desc\s.*\n\s*)?task\s+:?["']?#{Regexp.escape(leaf)}["']?\b/)
+      end
+
+      candidates.find do |path|
+        source = File.read(path)
+        namespaces.all? { |name| source.match?(/namespace\s+:?["']?#{Regexp.escape(name)}["']?\b/) }
+      end || candidates.first
+    end
+
+    # Called once the last record has been processed, before the run is
+    # marked succeeded — for a summary tally of what the walk left alone.
+    def after_complete; end
+
+    private
+
+    # Rake tasks are defined by the Rakefile, which a web process never loads —
+    # a task fired from the dashboard has to load the engine's tasks itself.
+    #
+    # Loads the one file that defines the task, and only when it is not already
+    # defined. Both halves matter: re-loading a .rake file APPENDS its block to
+    # a task that already exists, so a second load makes that task run twice,
+    # and loading every file would do that to every task in the engine. The
+    # symptom is invisible until something counts what it did.
+    #
+    # @param task_name [String] the rake task about to be invoked
+    def load_engine_rake_tasks(task_name)
+      require 'rake'
+
+      RAKE_LOAD_LOCK.synchronize do
+        next if ::Rake::Task.task_defined?(task_name)
+
+        ::Rake::Task.define_task(:environment) unless ::Rake::Task.task_defined?(:environment)
+
+        path = rake_file_defining(task_name)
+        load(path) if path
+      end
+    end
+
+    def rake_files
+      roots = Rails.application.railties.grep(Rails::Engine).map(&:root) + [Rails.root]
+      roots.uniq.flat_map { |root| Dir.glob(File.join(root, 'lib/tasks/**/*.rake')).sort }
+    end
+  end
+end

data/app/models/spree/maintenance_task_run.rb

@@ -0,0 +1,78 @@
+module Spree
+  # One execution of a Spree::MaintenanceTask — the durable record of what was
+  # run, by whom, with which arguments, and how far it got
+  # (docs/plans/6.0-maintenance-tasks.md).
+  #
+  # The row is both the checkpoint and the audit trail. Its `cursor` is the
+  # authoritative resume point: Active Job serializes its own continuation
+  # into the job data, but that copy is lost whenever the job is dropped by
+  # the backend, so the runner writes both in the same checkpoint and always
+  # seeds from this column.
+  #
+  # Runs are installation-wide: an upgrade step converts every store's data,
+  # so a run belongs to no store.
+  class MaintenanceTaskRun < Spree.base_class
+    has_prefix_id :mtr
+
+    include Spree::HasStatus
+
+    publishes_lifecycle_events
+    publishes_events :started, :succeeded, :cancelled, :interrupted, :errored
+
+    # Terminal statuses end a run for good; a failed run is started again
+    # rather than resumed. `cancelling` is the operator's request, written by
+    # the Cancel service and observed by the runner at its next checkpoint —
+    # the runner alone moves a running run into `cancelled`, so a stopped
+    # worker can never leave a lie in the column.
+    has_status :enqueued, :running, :interrupted, :cancelling, :cancelled,
+               :succeeded, :errored,
+               default: :enqueued
+
+    ACTIVE_STATUSES = %w[enqueued running interrupted cancelling].freeze
+    INITIATED_VIA = %w[dashboard api cli].freeze
+
+    belongs_to :admin_user, class_name: Spree.admin_user_class.to_s, optional: true
+    belongs_to :api_key, class_name: 'Spree::ApiKey', optional: true
+
+    validates :task_name, presence: true
+    validates :initiated_via, presence: true, inclusion: { in: INITIATED_VIA }
+
+    scope :active, -> { where(status: ACTIVE_STATUSES) }
+
+    self.whitelisted_ransackable_attributes = %w[task_name status created_at]
+
+    # Filtered by the task's short name, which is what responses carry; the
+    # column holds its class name. A partial value (`task_name_cont=capture`)
+    # is camelized so a search still matches part of the stored name.
+    ransacker :task_name, formatter: ->(value) {
+      Spree::MaintenanceTask.find_by_api_type(value)&.name || value.to_s.camelize
+    } do |parent|
+      parent.table[:task_name]
+    end
+
+    # @return [Class, nil] the registered task class, or nil when the task has
+    #   been removed from the registry since the run was created
+    def task_class
+      Spree::MaintenanceTask.find_registered(task_name)
+    end
+
+    # The task's short name, as the API and the dashboard identify it.
+    #
+    # @return [String]
+    def task_api_type
+      Spree::MaintenanceTask.api_type_for(task_name)
+    end
+
+    def active?
+      ACTIVE_STATUSES.include?(status)
+    end
+
+    # Seconds of work. Time since the last checkpoint counts only while a
+    # worker holds the run — a queued run is not working.
+    def duration
+      return time_running unless status.in?(%w[running cancelling]) && started_at.present?
+
+      time_running + (Time.current - (updated_at || started_at))
+    end
+  end
+end

data/app/models/spree/upgrade_record.rb

@@ -0,0 +1,62 @@
+module Spree
+  # A release boundary whose data steps this installation has completed
+  # (docs/plans/6.0-maintenance-tasks.md).
+  #
+  # This exists because nothing else in the schema records where an
+  # installation upgraded *from*. `Spree.version` is only ever the gem that is
+  # installed now, so without a stamp the dashboard cannot tell a store that
+  # has been on 5.6 for months from one jumping straight from 5.4 — and would
+  # have to show both every step of every manifest, which grows with each
+  # release.
+  #
+  # Written from three places, none of which guesses:
+  #
+  # - a successful `spree:upgrade` walk stamps the boundary it reached
+  # - a fresh install stamps the current version, because a database created
+  #   by today's schema has no historical data to convert
+  # - an operator can stamp one by hand, for a store upgraded before this
+  #   record existed
+  class UpgradeRecord < Spree.base_class
+    has_prefix_id :upg
+
+    SOURCES = %w[walk install manual].freeze
+
+    validates :version, presence: true, uniqueness: true
+    validates :source, presence: true, inclusion: { in: SOURCES }
+    validates :completed_at, presence: true
+
+    # Whether this installation has ever been upgraded, as opposed to having
+    # been installed at its current version.
+    #
+    # A store installed fresh at 6.0 has no historical data to convert and no
+    # upgrade to perform — showing it a manifest of steps, current or past,
+    # describes work that does not exist for it.
+    #
+    # @return [Boolean]
+    def self.upgraded?
+      where.not(source: 'install').exists?
+    end
+
+    # The highest boundary recorded, or nil when this installation has never
+    # stamped one.
+    #
+    # @return [String, nil]
+    def self.current_version
+      all.map(&:version).max_by { |version| Spree::Upgrade.version_parts(version) }
+    end
+
+    # Records a completed boundary. Idempotent — re-running a walk that has
+    # already been stamped updates when it happened rather than failing.
+    #
+    # @param version [String] two-segment release, e.g. "6.0"
+    # @param source [String] one of SOURCES
+    # @return [Spree::UpgradeRecord]
+    def self.stamp!(version, source: 'walk')
+      record = find_or_initialize_by(version: version.to_s)
+      record.source = source.to_s
+      record.completed_at = Time.current
+      record.save!
+      record
+    end
+  end
+end

data/app/services/spree/maintenance_tasks/argument_parser.rb

@@ -0,0 +1,23 @@
+module Spree
+  module MaintenanceTasks
+    # Turns the CLI's `ARGS='market_id=mkt_1 batch_size=200'` into the hash the
+    # task's ActiveModel attributes expect.
+    #
+    # Values stay strings: attribute types cast them, so the parser never has
+    # to guess whether `200` is a number or a label.
+    module ArgumentParser
+      # Quoted values may contain spaces: ARGS='label="two words" limit=5'.
+      TOKEN = /(\w+)=("[^"]*"|'[^']*'|\S+)/
+
+      # @param raw [String, nil]
+      # @return [Hash{String => String}]
+      def self.parse(raw)
+        return {} if raw.blank?
+
+        raw.scan(TOKEN).to_h do |key, value|
+          [key, value.gsub(/\A["']|["']\z/, '')]
+        end
+      end
+    end
+  end
+end

data/app/services/spree/maintenance_tasks/cancel.rb

@@ -0,0 +1,51 @@
+module Spree
+  module MaintenanceTasks
+    # Stops a run for good. The service records the request and the runner
+    # records the outcome; a run that has not started yet is cancelled
+    # outright, since no execution will ever observe the request.
+    #
+    # Cancelling a run that is already `cancelling` also cancels it outright.
+    # That is the way out when the worker that should have observed the first
+    # request is gone: a run the runner never comes back to would otherwise
+    # stay active and block every new run of its task.
+    #
+    # Cancelling is not a rollback — work already committed stays committed.
+    # What a cancelled run keeps is its cursor, so an operator can see exactly
+    # how far it got.
+    class Cancel
+      prepend ::Spree::ServiceModule::Base
+
+      # @param run [Spree::MaintenanceTaskRun]
+      # @return [Spree::ServiceModule::Base::Result] the run
+      def call(run:)
+        # Locked so the status read here is still the status when it is
+        # written: the runner may finish the run in between, and a finished
+        # run overwritten with `cancelling` would stay active for good.
+        run.with_lock do
+          return failure(run, not_cancelable_error(run)) unless run.active?
+
+          # A running run has a worker mid-batch, so it, not this service,
+          # records that the run stopped.
+          if run.running?
+            run.update!(status: 'cancelling')
+          else
+            run.update!(status: 'cancelled', ended_at: Time.current)
+            run.publish_event('maintenance_task_run.cancelled')
+          end
+        end
+
+        success(run.reload)
+      end
+
+      private
+
+      def not_cancelable_error(run)
+        build_error("a run with status #{run.status} cannot be cancelled")
+      end
+
+      def build_error(message)
+        ActiveModel::Errors.new(Spree::MaintenanceTaskRun.new).tap { |errors| errors.add(:base, message) }
+      end
+    end
+  end
+end

data/app/services/spree/maintenance_tasks/start.rb

@@ -0,0 +1,127 @@
+module Spree
+  module MaintenanceTasks
+    # Creates a run for a registered task and hands it to the runner
+    # (docs/plans/6.0-maintenance-tasks.md).
+    #
+    # Everything that can be known before any work happens is checked here —
+    # the task exists, its parameters validate, and no run of the same task
+    # is already in flight — so an operator sees a 422
+    # rather than a run that dies on its first record.
+    class Start
+      prepend ::Spree::ServiceModule::Base
+
+      # @param task_name [String] a registered Spree::MaintenanceTask subclass name
+      # @param api_type [String] the task's short name, in place of `task_name`
+      #   — how an API caller names it, so a class name never has to cross
+      #   the API
+      # @param arguments [Hash] task parameters
+      # @param dry_run [Boolean] preview mode; only honored by tasks that declare
+      #   `supports_dry_run`
+      # @param initiated_via [String] dashboard / api / cli
+      # @param inline [Boolean] run synchronously (seeds, the CLI, the upgrade walk)
+      # @return [Spree::ServiceModule::Base::Result] the run
+      def call(task_name: nil, api_type: nil, arguments: {}, dry_run: false, admin_user: nil,
+               api_key: nil, initiated_via: 'api', inline: false)
+        task_class = if api_type.nil?
+                       Spree::MaintenanceTask.find_registered(task_name)
+                     else
+                       Spree::MaintenanceTask.find_by_api_type(api_type)
+                     end
+        return failure(nil, unknown_task_error(api_type || task_name)) if task_class.nil?
+
+        task_name = task_class.name
+
+        arguments = (arguments || {}).stringify_keys
+        unknown = arguments.keys - task_class.attribute_names
+        return failure(nil, unknown_arguments_error(unknown)) if unknown.any?
+
+        if initiated_via.to_s.in?(%w[api dashboard]) && superseded_step?(task_class, arguments)
+          return failure(nil, superseded_error(task_class))
+        end
+
+        task = task_class.new(arguments)
+        return failure(task, task.errors) unless task.valid?
+
+        active = active_run_for(task_name)
+        return failure(active, already_running_error(task_class)) if active
+
+        run = build_run(task_class, arguments, dry_run, admin_user, api_key, initiated_via)
+        return failure(run, run.errors) unless run.save
+
+        dispatch(run, inline)
+
+        success(run)
+      end
+
+      private
+
+      def build_run(task_class, arguments, dry_run, admin_user, api_key, initiated_via)
+        Spree::MaintenanceTaskRun.new(
+          task_name: task_class.name,
+          status: Spree::MaintenanceTaskRun.default_status,
+          arguments: arguments,
+          # A task that does not declare dry-run support would ignore the flag
+          # and write for real; recording it as a preview would be a lie.
+          dry_run: dry_run && task_class.dry_run_supported,
+          admin_user: admin_user,
+          api_key: api_key,
+          initiated_via: initiated_via.to_s
+        )
+      end
+
+      # The enqueue waits for the transaction so the worker cannot pick the
+      # job up before the row it names is visible.
+      def dispatch(run, inline)
+        if inline
+          ActiveRecord.after_all_transactions_commit { Spree::MaintenanceTasks::RunJob.perform_now(run.id, inline: true) }
+        else
+          Spree::MaintenanceTasks::RunJob.perform_later(run.id)
+        end
+      end
+
+      # Upgrade steps of a release this installation already completed. The
+      # dashboard never offers them; the command line still runs them, since
+      # that is where an operator deliberately repeats a step.
+      #
+      # Refused even when the completed release was assumed rather than
+      # recorded. The assumption is right for nearly every store, and for
+      # those a repeated conversion damages data; a store that really skipped
+      # a release is told to run its steps from the command line.
+      def superseded_step?(task_class, arguments)
+        Spree::Upgrade.superseded_steps.any? do |step|
+          step['task_class'] == task_class.name ||
+            (task_class <= Spree::MaintenanceTasks::UpgradeStep && step['id'] == arguments['step_id'])
+        end
+      end
+
+      # One run per task at a time. Checked rather than locked: two requests
+      # can both pass this check, and the runner then cancels the newer run
+      # before it does any work (RunJob#duplicate_run?).
+      def active_run_for(task_name)
+        Spree::MaintenanceTaskRun.active.find_by(task_name: task_name)
+      end
+
+      def unknown_task_error(task_name)
+        errors_for(:task_name, "#{task_name} is not a registered maintenance task")
+      end
+
+      def unknown_arguments_error(names)
+        errors_for(:arguments, "the task takes no parameter named #{names.to_sentence}")
+      end
+
+      def superseded_error(task_class)
+        errors_for(:base, "#{task_class.api_type} belongs to a release this store has already completed")
+      end
+
+      def already_running_error(task_class)
+        errors_for(:base, "#{task_class.api_type} is already running")
+      end
+
+      def errors_for(attribute, message)
+        ActiveModel::Errors.new(Spree::MaintenanceTaskRun.new).tap do |errors|
+          errors.add(attribute, message)
+        end
+      end
+    end
+  end
+end

data/app/services/spree/seeds/all.rb

@@ -10,6 +10,8 @@ module Spree
             # countries gem, and zones are migration-only, so none of them
             # are seeded.
 
+            fresh_database = Spree::Store.none?
+
             Stores.call
             Spree::Store.find_each { |store| StoreResources.call(store: store) }
             # The warehouse, delivery zones and pickup are not seeded: their
@@ -18,6 +20,26 @@ module Spree
             # them from the merchant's answer — at first-run setup, or here
             # when ADMIN_EMAIL/ADMIN_PASSWORD name an install that skips it.
             AdminUser.call
+
+            # A database created by today's schema has no historical data to
+            # convert, so every upgrade boundary up to this release is already
+            # satisfied. Recording that is what keeps a fresh install from
+            # being shown a backlog of steps it must never run. Only a database
+            # seeded for the first time qualifies: seeding is also a deploy
+            # step, and an upgraded store seeded before its upgrade ran still
+            # has every step to do.
+            stamp_upgrade_boundaries if fresh_database
+          end
+        end
+      end
+
+      private
+
+      def stamp_upgrade_boundaries
+        Spree::Upgrade.manifests.each do |manifest|
+          Spree::UpgradeRecord.find_or_create_by!(version: manifest['to']) do |record|
+            record.source = 'install'
+            record.completed_at = Time.current
           end
         end
       end

data/config/locales/en.yml

@@ -1032,6 +1032,7 @@ en:
     locale_not_supported_by_market: is not offered by the chosen market
     locale_not_supported_by_store: is not supported by this store
     locales_not_listed: 'includes locales Spree does not support: %{codes}'
+    maintenance_tasks_turned_off: Maintenance tasks are turned off for this installation. Run upgrade steps from the command line with `spree upgrade` (or `bin/rake spree:upgrade`).
     manual: Manual
     market: Market
     me_no_current_user: No admin user authenticated this request

data/db/migrate/20260813130001_add_capture_method_to_payment_methods.rb

@@ -10,7 +10,7 @@ class AddCaptureMethodToPaymentMethods < ActiveRecord::Migration[8.1]
   # from the provider configuration form.
   #
   # Existing auto_capture values are carried over by
-  # spree:migrate_capture_methods, never here.
+  # the capture_methods maintenance task, never here.
   def change
     add_column :spree_payment_methods, :capture_method, :string
   end

data/db/migrate/20260815000001_create_spree_maintenance_task_runs.rb

@@ -0,0 +1,40 @@
+class CreateSpreeMaintenanceTaskRuns < ActiveRecord::Migration[8.1]
+  def change
+    create_table :spree_maintenance_task_runs do |t|
+      t.string :task_name, null: false
+      t.string :status, null: false
+      t.boolean :dry_run, null: false, default: false
+
+      t.string :cursor
+      t.integer :tick_count, null: false, default: 0
+      t.integer :tick_total
+
+      t.decimal :time_running, null: false, default: 0.0, precision: 12, scale: 3
+      t.datetime :started_at
+      t.datetime :ended_at
+
+      t.string :error_class
+      t.text :error_message
+      t.text :error_backtrace
+
+      t.string :job_id
+      t.string :initiated_via, null: false
+
+      t.references :admin_user, null: true
+      t.references :api_key, null: true
+
+      if t.respond_to?(:jsonb)
+        t.jsonb :arguments
+        t.jsonb :tallies
+      else
+        t.json :arguments
+        t.json :tallies
+      end
+
+      t.timestamps
+    end
+
+    add_index :spree_maintenance_task_runs, [:task_name, :status]
+    add_index :spree_maintenance_task_runs, :created_at
+  end
+end

data/db/migrate/20260816000001_create_spree_upgrade_records.rb

@@ -0,0 +1,17 @@
+class CreateSpreeUpgradeRecords < ActiveRecord::Migration[8.1]
+  def change
+    create_table :spree_upgrade_records do |t|
+      # The release boundary this installation has completed the data steps
+      # for — "5.6" means every manifest up to and including 5.5 → 5.6 is done.
+      t.string :version, null: false
+      # How we know: `walk` (a successful upgrade walk), `install` (a fresh
+      # install, which needs no historical steps) or `manual`.
+      t.string :source, null: false
+      t.datetime :completed_at, null: false
+
+      t.timestamps
+    end
+
+    add_index :spree_upgrade_records, :version, unique: true
+  end
+end