Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

37.1 KB
Raw Blame

Maintenance Tasks — reviewed, deployed, resumable data work run from the dashboard

Status: Complete — all six phases shipped 2026-08-15 Target: Spree 6.0 Depends on: 6.0-service-workflows.md (Durability = plain Rails / ActiveJob::Continuable), 6.0-admin-rbac.md (permission catalog), 6.0-admin-api.md, 6.0-admin-spa.md, 5.6-solid-queue-single-container.md (default job backend), 6.0-opentelemetry.md (notification surface) Author: Damian Legawiec (design driven with Claude, 2026-08-15) Last updated: 2026-10-25

Narrowed 2026-10-25 (decisions.md): upgrade steps only. Nothing outside the upgrade manifests registers a task, so the general-purpose surface was removed before release: the dashboard's Tasks tab and run form, the GET /maintenance_tasks endpoints and SDK methods, CSV input, throttling, error reporting, masked arguments, preconditions, task descriptions, the run-time limit setting, unused lifecycle hooks, parent runs, and pause and resume. The runner, run history, cancel, dry run and step parameters stay. The sections below describe the original, wider design; re-adding any of it is a new decision.

Summary

Spree has no sanctioned way to run one-off data work — backfills, reindexes, bulk corrections, the fix after a bad import — other than a rake task typed at a shell or code pasted into a production console. That is the wrong shape for three audiences at once: developers (a console session records what was typed, not what it did), merchants on the cloud offering (nobody wants to hand out shell access to run a backfill), and Spree itself (the 5.6→6.0 upgrade manifest is twenty-two data migrations that every live store must run, and today the instruction is "run this rake task and wait").

This plan adds a first-class maintenance task primitive to spree_core, modeled on Shopify's maintenance_tasks engine but built natively on Rails 8.1's ActiveJob::Continuable (already the 6.0 durability doctrine, reference Spree::Imports::ProcessJob): a task is a reviewed, deployed Ruby class with a collection and a process(item); running it creates a persistent run row that carries the cursor, progress, arguments, outcome and who fired it; the runner is a Continuable job that checkpoints per batch, survives deploys, pauses, resumes and cancels; the Admin API exposes task discovery and run control; the dashboard shows a task list, a generated parameter form, a progress bar and the run history. Plugin gems ship tasks the same way core does. Schema migrations stay where they are (deploy pipeline, strong_migrations); this is only for data work.

Shipping it in 6.0 rather than 6.1 is deliberate: the 6.0 upgrade is the largest data migration in Spree's history, and the runner turns it into a list of tasks with progress bars and resume buttons instead of a rake walk that dies at row 400k and starts over. We build it for our own migration path and get the cloud capability as a side effect. It lives in BSD-3 core — infrastructure, not money or compliance; self-hosted merchants need it exactly as much.

Key Decisions (do not deviate without discussion)

  • Named Spree::MaintenanceTask (2026-08-15). Shopify parity — the term developers already search for and can port from — over OpsTask (the branch name) or DataTask (excludes reindex/cache work by name). Table spree_maintenance_task_runs, registry Spree.maintenance_tasks, keys read_/write_maintenance_tasks, routes /maintenance_tasks + /maintenance_task_runs, dashboard /settings/maintenance-tasks, rake spree:maintenance_tasks:*. Accepted trade-off: "maintenance" can read as downtime to merchants — the dashboard copy says what a task does, never "maintenance mode".
  • Native on ActiveJob::Continuable, not a dependency on the maintenance_tasks gem (2026-08-15). The gem's runner rides job-iteration (a second interruption/cursor mechanism beside Continuable, which 6.0 already standardized on), and its UI is a server-rendered Rails engine on ActionController::Base + views — a surface Spree 6.0 removed. We would use neither half. What we DO copy is the authoring contract, nearly verbatim (collection / process / count, no_collection, csv_collection, ActiveModel attributes as parameters, throttle_on, report_on, lifecycle callbacks), so anyone who knows the Shopify gem knows how to write a Spree task, and a task can be ported between the two by changing the superclass.
  • Task authoring lives in the core gem; discovery through an explicit registry (Spree.maintenance_tasks), the same Rails.application.config.spree.* array every other class family uses (Spree.integrations, Spree.adjusters, Spree.export_types, …). Core, provider gems, extensions and host apps append class names from an initializer. Explicit registration keeps "a task class exists somewhere under app/" from meaning "operators can fire it", and it is what the Admin API lists. Subclass autodiscovery (Shopify's model) was rejected (2026-08-15): it makes eager loading load-bearing in every gem that ships tasks and offers no way to say "not for operators".
  • The run row IS the audit. Spree::MaintenanceTaskRun records the task name, serialized arguments, who initiated it (staff member or API key), through which surface (dashboard / api / cli), the store context, timestamps, cursor, tick counts, error, and task-reported tallies. Runs are never deleted through the API (no destroy action — cancel instead, same as returns/claims). Lifecycle events (maintenance_task_run.started / .succeeded / .errored / .canceled / .paused) fire through publishes_lifecycle_events so webhooks and the event log see them — consistent with decisions.md 2026-08-07 ("lifecycle events are the only audit"). No separate audit-log model.
  • RBAC: one catalog resource, maintenance_tasks, in the access group — admins only by default, nothing per task (2026-08-15). read_maintenance_tasks lists tasks and runs; write_maintenance_tasks fires, pauses, resumes and cancels any registered task. It sits beside staff and api_keys — the sensitive group — so out of the box only the immutable admin role holds it, and secret keys need write_maintenance_tasks or write_all. A merchant who wants a narrower "release engineer" role grants the key explicitly. A per-task declared permission (requires_permission :write_orders beside the runner key) was considered and dropped as over-engineering; a hard "admin role only" controller check was also rejected because it would be the first gate in the v3 API outside the catalog (6.0-admin-rbac.md: the catalog plus a class swap is the whole authorization surface). Accepted trade-off: a role granted the write key can run every task, including ones that touch orders — the run row's audit trail, not the grant, is what makes that reviewable.
  • Installation-wide resource, store-aware execution (2026-08-15). Tasks and runs are not store-owned data (a backfill walks every store; roles are global). But every run records the store_id the operator was acting in when it was fired from the dashboard/API (nullable — CLI runs may have none), and the runner sets Spree::Current.store from it for the whole execution, because 6.0-store-scoped-configuration.md requires jobs that validate addresses or query the catalog to carry a store. A task that must be run per store takes the store as an explicit argument; the context store is a default, not a filter.
  • Dry-run is a task capability, not a runner trick (2026-08-15). A task opts in with supports_dry_run; the run row carries dry_run: true; the task reads dry_run? and reports what it would change through the tally channel (tally(:would_update)). The runner never wraps batches in rolled-back transactions to fake it — that breaks external I/O tasks and cursor semantics silently. The dashboard shows the toggle only for tasks that declare support.
  • One active run per task. A task with a run in enqueued / running / pausing / paused / interrupted / cancelling cannot be started again (422). Re-running is explicit: cancel or wait, then fire anew.
  • Interruption has three sources and one cursor. (1) Worker shutdown — Continuable's checkpoint sees queue_adapter.stopping? and re-enqueues with the cursor in the job data (status interrupted → back to running). (2) Time slicing — the runner interrupts itself after max_run_time (task-declared, default 5 minutes) so one task cannot hog a worker; same mechanism. (3) Operator pause/cancel — the run row's status is re-read at every checkpoint (default every batch, at most once a second); pausing stops the job and leaves paused + cursor, cancelling stops it and leaves cancelled. Resume enqueues a fresh job seeded from the run row's cursor. The run row's cursor is the durable truth; Continuable's serialized progress is a fast path for case (1) and must never disagree with it — the runner writes both in the same checkpoint.
  • CSV input reuses the import upload flow. csv_collection tasks take an Active Storage blob created through the same signed direct-upload endpoint the dashboard CSV import uses; the run row holds the attachment. Phase 2, not first cut.
  • The CLI entry is spree:maintenance_tasks:perform and it writes a run row too. Shell runs are audited like dashboard runs (initiated_via: cli, staff nil). Inline (perform_now) execution for seeds/tests.
  • Every 5.6→6.0 upgrade step is a task class and the manifest names classes (2026-08-15). All 22 steps are rewritten as Spree::MaintenanceTasks::Upgrade::*; older, already-released manifests keep rake steps and the walker runs both kinds inside run rows. The cheaper cuts (a generic wrapper only, or wrapper + the four heavy steps) were rejected: the 6.0 upgrade is the reason this ships in 6.0, and a progress bar on four steps with twenty-two rows of "indeterminate" is not the experience the plan is for. Accepted cost: 22 rewrites + spec ports before 6.0 GA. Sequencing lives in Upgrade::Walk, an orchestrating task whose steps are child runs (parent_run_id). Superseded 2026-10-25 (decisions.md): a one-pass step names its rake task and runs through UpgradeStep; only steps that walk rows or take parameters are task classes, and a step is never both.
  • Schema migrations are out of scope, permanently. No task ever runs db:migrate or alters schema; the deploy pipeline owns that. A task that needs a column the migration has not added yet is a task with a precondition (precondition { column_exists? }) that fails fast with a message.

Design Details

Task class contract

module Spree
  module MaintenanceTasks
    # A backfill written the way every task is written: a stable-ordered
    # relation, a per-record body, a permission, and an optional dry-run.
    class BackfillOrderMarkets < Spree::MaintenanceTask
      description 'Assign a market to orders placed before markets existed'
      supports_dry_run
      max_run_time 5.minutes
      collection_batch_size 500

      attribute :market_id, :string
      validates :market_id, presence: true

      def collection
        Spree::Order.where(market_id: nil).order(:id)
      end

      def process(order)
        if dry_run?
          tally(:would_update)
        else
          order.update_columns(market_id: market_id)
          tally(:updated)
        end
      end
    end
  end
end

Vocabulary (all class-level unless noted):

Declaration Meaning
description(text) Shown in the task list; localizable through Spree.t when a key is given
supports_dry_run Exposes the dry-run toggle; task must honor dry_run?
no_collection Task has no iteration; process runs once
csv_collection(in_batches: n) Rows come from an uploaded CSV (phase 2)
collection_batch_size(n) Records per checkpoint (default 100)
max_run_time(duration) Time slice before self-interruption (default 5 min)
throttle_on(backoff:) { } Skip work and back off while the block is true (replica lag, queue depth)
report_on(ErrorClass, severity:) Rescue per-item errors, report to Rails.error, continue
precondition(message) { } Checked before enqueue; failing → 422
after_start / after_pause / after_interrupt / after_cancel / after_complete / after_error Instance callbacks
attribute + validates ActiveModel parameters; inclusion validators become selects; mask_attribute hides values in run history

Instance surface: collection (an ActiveRecord::Relation with an explicit order, an Array, an ActiveRecord::Batches::BatchEnumerator from in_batches, or nil for no_collection), process(item_or_batch), count (defaults to collection.count; nil = unknown, progress shows ticks only), dry_run?, tally(key, by = 1), store (context store, may be nil), run (the run row, read-only), cursor_for(item) (defaults to primary key; tasks whose relation is ordered by something else override it).

Cursors: an ActiveRecord::Relation is walked as where(pk > cursor).order(pk).limit(batch) — the same pattern as ProductTypes::ApplyToProductsJob; that is why the relation must be ordered by a stable unique column and why the cursor is a string (UUID-safe). Arrays cursor by index. no_collection has no cursor.

The run row — Spree::MaintenanceTaskRun

spree_maintenance_task_runs (installation-wide, no store_id ownership; store_id is context):

Column Type Notes
task_name string, null: false, indexed Registered class name
status string, null: false HasStatus — see below
arguments JSON Serialized attribute values (masked ones stored encrypted-at-rest via encrypts)
dry_run boolean, default false
cursor string Last processed cursor
tick_count / tick_total integer, default 0 / nullable Progress
tallies JSON Task-reported counters
time_running decimal seconds, default 0 Summed across executions
started_at / ended_at datetime
error_class / error_message / error_backtrace string / text / text Cleaned with Rails.backtrace_cleaner
job_id string Current/last ActiveJob id
parent_run_id reference, nullable Set on child runs of an orchestrating task (the upgrade walk)
store_id reference, nullable Context store
admin_user_id reference, nullable Staff who fired it
api_key_id reference, nullable Secret key that fired it
initiated_via string, null: false dashboard / api / cli / inline
csv_file Active Storage attachment Phase 2
metadata JSON Spree::Metadata
timestamps

No optimistic locking (2026-08-15, found in implementation). A lock_version column was in the original design and was removed: writers here are already disjoint — the control services only ever write a request (pausing, cancelling) and the runner alone writes the resulting state — so it guarded nothing, while breaking the runner's own per-batch progress writes against its in-memory copy. Silently, at that: update_columns puts lock_version in the WHERE clause and reports no error when it matches no row, so a run would have resumed from a cursor it never saved. The runner reloads before each status write instead.

Statuses (has_status, additive, no transition graph — transitions live in the runner and the three control services): enqueued → running → succeeded | errored | cancelled, with pausing, paused, interrupted, cancelling as the operator/worker-driven detours. Predicates: active? (anything not terminal), resumable? (paused or errored with a cursor).

publishes_lifecycle_events + Spree::Api::V3::Events::MaintenanceTaskRunSerializer.

Runner — Spree::MaintenanceTasks::RunJob

A Spree::BaseJob including ActiveJob::Continuable, queue Spree.queues.maintenance_tasks (new key, defaults to :default like all others). Shape follows Imports::ProcessJob:

def perform(run_id)
  @run = Spree::MaintenanceTaskRun.find(run_id)     # every execution, resumes included
  return unless @run.status.in?(%w[enqueued running interrupted])
  Spree::Current.store = @run.store

  step :start do ... status running, started_at, after_start
  step :process_collection, start: @run.cursor       # cursor seeded from the ROW
  step :complete do ... status succeeded, ended_at, after_complete
end

process_collection loops batches; after each batch it (a) increments ticks

  • merges tallies + writes the cursor on the row, (b) step.set!(cursor) — Continuable's checkpoint, which raises Interrupt if the adapter is stopping — and (c) runs the runner's own checkpoint: re-read the row's status; on pausing → mark paused, return; on cancelling → mark cancelled, after_cancel, return; if elapsed > max_run_time → interrupt! (re-enqueue). The status re-read happens every batch, not on a timer (2026-08-15, found in implementation): a primary-key read costs nothing beside the batch of writes it follows, and a time-based throttle made a fast task ignore a pause altogether, since all its batches landed inside one interval. Errors after progress: Continuable resumes them (resume_errors_after_advancing), so the runner rescues StandardError inside the step, records the error on the row (errored, after_error) and returns — never discard_on, for the same reason Imports::ProcessJob rescues inside the step. Interrupt inherits Exception and is never rescued.

throttle_on blocks are evaluated before each batch; when one is true the runner sleeps up to backoff (bounded, then re-checks) — it does not re-enqueue, because Solid Queue's minimum polling granularity would make sub-minute backoffs coarse.

Notifications (6.0-opentelemetry.md catalog, additive): run.spree_maintenance_task (payload: task_name, run_id prefixed, status, tick_count, dry_run), batch.spree_maintenance_task (task_name, run_id, size, cursor). No arguments in payloads (they can carry PII).

Control services

Plain services (Spree::MaintenanceTasks::Start, Pause, Resume, Cancel), tier 1 per 6.0-service-workflows.md — no hooks needed. Start validates the task's attributes and preconditions, enforces the one-active-run rule (row lookup + with_lock on a per-task advisory row is overkill; a uniqueness validation over the active statuses plus the enqueue happening inside after_commit keeps the race window sub-millisecond and the worst case is a second run that the runner refuses on load — logged, not silent), creates the row and enqueues RunJob. Resume re-enqueues from the row's cursor. Pause/Cancel flip status under lock_version.

Registry

# core engine initializer
Rails.application.config.spree.maintenance_tasks = ['Spree::MaintenanceTasks::BackfillOrderMarkets', ...]

# an extension / host app initializer — class-name strings, like Spree.integrations
Spree.maintenance_tasks << 'SpreeReviews::MaintenanceTasks::RecountRatings'

Spree::MaintenanceTask.registered_classes            # constantized, sorted
Spree::MaintenanceTask.find_registered('Spree::MaintenanceTasks::BackfillOrderMarkets')

Only registered classes appear in the API and can be run; a run row naming an unregistered class is refused on load. Task classes live in app/maintenance_tasks/ inside each gem (Rails autoloads any app/* directory), namespaced under the gem's own module (Spree::MaintenanceTasks::* in core, SpreeEasyPost::MaintenanceTasks::* in a provider). Class-name strings keep registration initializer-safe and reload-safe, the same reason Spree.hooks stores handler names. Registry resolution is a small Spree::RegisteredSubclasses concern — the extraction PreferenceSchema's header already asks for ("a family that needs the registry without preferences") — rather than a fourth idiom.

Admin API v3

Scope maintenance_tasks (read/write). All installation-wide — the X-Spree-Store-Id header only sets the run's context store.

GET    /api/v3/admin/maintenance_tasks                 # registered tasks: name, description, parameters schema,
                                                       # supports_dry_run, csv?, active_run, last_run
GET    /api/v3/admin/maintenance_tasks/:name           # one task, by short name (`capture_methods`)
GET    /api/v3/admin/maintenance_task_runs             # Ransack: task_name, status, admin_user_id, created_at
GET    /api/v3/admin/maintenance_task_runs/:id         # `expand=admin_user` embeds who started it
POST   /api/v3/admin/maintenance_task_runs             # { task_name, arguments: {}, dry_run:, csv_file: }  → 201 enqueued / 422
POST   /api/v3/admin/maintenance_task_runs/:id/pause
POST   /api/v3/admin/maintenance_task_runs/:id/resumption
POST   /api/v3/admin/maintenance_task_runs/:id/cancellation

A task is named on the wire by its short name (Spree::ApiTyped: the demodulized, underscored class), never its class name; the run row keeps storing the class name. Pause, resumption and cancellation are nested singular resources rather than member actions (2026-10-16).

No destroy. The parameters schema reuses the shape the integrations types endpoint emits from PreferenceSchema (name, type, required, options, masked, label, help) — one form renderer in the dashboard. Run serializer: admin-only (there is no store counterpart), prefixed ids, progress (0..1 | null), admin_user_id plus an expandable admin_user (the Admin user serializer), tallies, error fields, resumable, cancelable. error_backtrace is served only to callers holding write_maintenance_tasks.

Dashboard

/settings/maintenance-tasks in the audit settings-nav group beside Imports, gated on Subject.MaintenanceTask read.

  • Task list — name, description, last run (status + when + who), Run button (<Can>-gated on write_maintenance_tasks; disabled with a tooltip while a run is active).
  • Run dialog — generated from the parameters schema; dry-run switch when supported; CSV drop zone for CSV tasks (phase 2, reusing the import upload sheet); confirm copy states the task's effect and — for non-dry runs — "This starts immediately and cannot be undone by the runner".
  • Run page — status, progress bar (tick_count / tick_total, or an indeterminate bar with the count), tallies, elapsed, initiated by, store, arguments (masked where declared), error class/message with an expandable backtrace, and Pause / Resume / Cancel (destructive confirm on cancel). Status by polling while active (same as imports — no ActionCable in the SPA), 2s while running, stopped when terminal.
  • History — paginated table across all tasks with filters (task, status, who, date), linking to run pages.

Translations in all six locales; per-task description is server-provided so plugin authors localize with Spree.t.

CLI and inline

  • bin/rails "spree:maintenance_tasks:perform[Spree::MaintenanceTasks::BackfillOrderMarkets]" ARGS='market_id=mkt_x' DRY_RUN=1 — runs synchronously (perform_now), prints progress lines, exits non-zero on error, writes a run row (initiated_via: cli).
  • bin/rails spree:maintenance_tasks:list.
  • Spree::MaintenanceTasks::Start.call(task_name:, arguments:, inline: true) for seeds/tests.

Upgrade manifest integration — every 6.0 step is a task class

Amended 2026-10-25 (decisions.md): one-pass steps run their rake task through UpgradeStep; only row walks and steps with parameters are task classes.

Today's shape: spree:upgrade (spree/core/lib/tasks/upgrade.rake) walks lib/spree/upgrades/<from>_to_<to>/manifest.yml after db:migrate; every step is a standalone rake task with puts progress, abort as the failure signal, ENV knobs (BATCH_SIZE, SKIP_FAILED_ROWS, CONFIRM_NO_PEPPER, …) and no shared base class, cursor or status row. Idempotency is a contract, and the row-by-row migrators (Spree::ReturnsMigrator, Spree::CountryStateCodeMigrator, defined inside their rake files) are "resumable by construction" — what is left is a query, never tracked state. That property carries straight over: such a query IS a collection.

Doctrine that stays: decisions.md 2026-08-07 — the data tasks are manifest steps that run at deploy; "code deployed, task not yet run" is not a state Spree designs for. This plan does not move the steps out of the deploy window; it gives the same steps an audited, resumable, progress-reporting entry point that also works where there is no shell.

Decision (2026-08-15): all 22 steps of the 5.6→6.0 manifest are rewritten as Spree::MaintenanceTask subclasses under Spree::MaintenanceTasks::Upgrade::*, and the manifest names classes, not rake tasks. The 5.6→6.0 tasks have never shipped in a release, so nobody has scripted their rake names — there is nothing to bridge. Older manifests (5.4→5.5, 5.5→5.6) are already released and keep their task: rake steps; the walker understands both step kinds.

# lib/spree/upgrades/5_6_to_6_0/manifest.yml
steps:
  - id: migrate_returns
    task_class: Spree::MaintenanceTasks::Upgrade::MigrateReturns
    notes: |
      ...operator prose stays here and is shown on the run page...
module Spree::MaintenanceTasks::Upgrade
  class MigrateReturns < Spree::MaintenanceTask
    description 'Move return authorizations onto the 6.0 Return/Exchange models'
    supports_dry_run
    attribute :batch_size, :integer, default: 500
    attribute :skip_failed_rows, :boolean, default: false

    def collection = legacy_authorizations.where.not(number: Spree::Return.select(:number)).order(:id)
    def process(legacy_authorization) = ...   # migrate_one, tally(:returns)/(:exchanges)/(:failed)
  end
end

What changes per step:

  • The rake body becomes collection + process (row-by-row steps) or a no_collection process (set-based SQL steps — still one run row, tallies from update_all counts). Migrator classes defined inside rake files move into the task class; anonymous-AR readers stay as they are.
  • ENV knobs become validated attributes with defaults; abort becomes a raised error (run errored, message on the row) or, for the reconcile-then-continue cases, skip_failed_rows-style attributes plus report_on.
  • puts progress becomes ticks + tallies; DRY_RUN=1 on the walker stays a plan printer, and steps that can preview declare supports_dry_run.
  • Ordering constraints (run X after Y) are expressed as precondition blocks that check the upstream step's last successful run — the manifest order remains the source of truth, the precondition is the guard.
  • spec/lib/tasks/six_zero_data_migrations_spec.rb and the per-task specs port to task specs run through Start.call(inline: true); the idempotency examples (re-run, assert no change) carry over unchanged.

The walk. spree:upgrade keeps its interface (TO, STEP, DRY_RUN) and the spree upgrade CLI keeps sequencing bundle update → db:migrate → bin/rake spree:upgrade. Internally the walker runs each task_class step through Start.call(inline: true) — so a shell walk writes run rows too — and each legacy task: step through Rake::Task#invoke wrapped in a run row of the generic Spree::MaintenanceTasks::UpgradeStep task (audit parity for old manifests). From the dashboard the same walk is Spree::MaintenanceTasks::Upgrade::Walk: a task whose collection is the eligible steps in manifest order and whose process(step) runs the step task inline as a child run (parent_run_id on the run row). Each child keeps its own cursor and progress bar; the walk's cursor is the step index. Interruption inside a child propagates up (Continuable's Interrupt is an Exception), the walk re-enqueues at step N, and on resume step N's task resumes from its own row — one mechanism, nested once. A step that errors stops the walk (errored, pointing at the child); the operator fixes the data, resumes the child or re-runs the walk, which skips steps whose last run succeeded.

Dashboard. Settings → Maintenance tasks gets an Upgrade panel when a manifest ahead of the recorded installed version exists: the steps in order with the status of each step's last run, the notes, per-step Run and a Run all remaining that fires the walk. Elsewhere the upgrade tasks are ordinary tasks in the list.

Migration Path

  1. Core primitive — ✅ shipped 2026-08-15: Spree::MaintenanceTask, MaintenanceTaskRun + migration, RunJob, Start/Pause/Resume/Cancel, registry (Spree.maintenance_tasks), Spree.queues.maintenance_tasks, spree:maintenance_tasks:{list,perform}, the maintenance_tasks catalog resource, Upgrade::BackfillOrderMarkets as the reference task, and the spec battery (55 examples: interruption + resume via ActiveJob::Continuation::TestHelper, pause, cancel, dry-run, report_on, preconditions, one-active-run, unregistered task, masked arguments).

  2. RBAC + API — catalog resource maintenance_tasks (group access, subjects MaintenanceTaskRun + :maintenance_task), controllers, serializers, typelizer → admin-sdk client.maintenanceTasks / client.maintenanceTaskRuns, rswag docs.

  3. Dashboard — ✅ shipped 2026-08-15: /settings/maintenance-tasks in the audit nav group, task cards with live progress, a run dialog whose fields are generated from the server's parameter schema (dry-run defaults ON for tasks that support it), a run detail sheet with progress, tallies, arguments, error + backtrace and Pause/Resume/Cancel, and the paginated run history table; translations in all six locales. Verified against a live store: preview run reported would_update: 3 and wrote nothing, the subsequent real run wrote all three. Pending: an e2e spec.

  4. Upgrade integration — ✅ shipped 2026-08-15: Spree::Upgrade extracted from the rake file so app code can read the manifests; the walker runs both step kinds through MaintenanceTasks::Start so a shell walk records the same rows a dashboard run does; all 22 steps of the 5.6→6.0 manifest are Spree::MaintenanceTasks::Upgrade::* classes named by task_class:; UpgradeStep wraps rake-backed steps of released manifests. Verified by walking all 31 steps of all three manifests against a real database.

    Refinement (2026-08-15, found in implementation): the set-based steps keep their rake body as the implementation rather than being rewritten as row walks. Their bodies are covered by a spec suite that invokes them by task name — 193 examples — and reimplementing set-based SQL as a row walk would trade tested code for a progress bar on work that reports no rows. Each is still a task class with its own run row, parameters (the ENV knobs became attributes via passes_to_environment) and preconditions; what it is not is a collection. Steps that genuinely walk rows — CaptureMethods and the reference BackfillOrderMarkets — are real collection tasks with cursors.

  5. CSV tasks — ✅ shipped 2026-08-15: csv_collection on the task contract, the uploaded blob attached to the run (private storage, so the file stays the record of what was applied), a row-number cursor so an interrupted run re-reads the file but re-applies nothing, the imports direct-upload endpoint reused for the upload, a file field on the run dialog, and UpdateVariantPrices as the reference CSV task.

  6. Docs — ✅ shipped 2026-08-15: docs/developer/how-to/maintenance-tasks.mdx (authoring, the ordered-collection rule, parameters from validators, dry-run, long-running work, CSV tasks, running from dashboard/CLI/code, permissions, shipping tasks from an extension, what tasks are not for) + nav entry + the 5.6→6.0 upgrade guide gaining the dashboard path, the STEP= re-run form and the preview note.

Constraints on Current Work

  • New bulk/backfill work is a maintenance task, not a bare rake task or a README console snippet. A rake entry may exist for scripting but its body is Spree::MaintenanceTasks::Start.call(inline: true).
  • New 5.6→6.0 upgrade steps are born as Spree::MaintenanceTasks::Upgrade::* classes referenced by task_class: in the manifest — no new spree:migrate_* rake tasks. Until the primitive lands, a step written today must keep its body in a plain class with a collection-shaped "what's left" query and a per-row process, so the port is mechanical.
  • Nothing gates on the admin role by name. Authorization is the maintenance_tasks catalog key; the dashboard uses <Can> on it, secret keys use the scope. Sensitivity is expressed by which group the key sits in, not by a bespoke check.
  • Long-running background jobs still use ActiveJob::Continuable directly when they are system-triggered (imports, product-type apply); the task primitive is for operator-triggered work. Do not convert Imports::ProcessJob into a task.
  • Task classes must be idempotent per batch (re-running the batch in flight at interruption changes nothing) — the same rule the upgrade manifest already imposes on its steps.
  • Never store secrets or PII in arguments unmasked; use mask_attribute for anything sensitive, and never put arguments in notification payloads or event payloads beyond the masked serializer.
  • A task never runs schema changes.

Open Questions

None open. All seven design questions were resolved on 2026-08-15 and are recorded in Key Decisions; the upgrade panel and its step filtering shipped 2026-08-16.

Fresh installs see no upgrade at all (2026-08-16). Spree::UpgradeRecord records how a boundary was reached (walk / install / manual), so a store installed at its current release — every stamp an install — has the whole panel hidden rather than being shown a manifest of work that does not exist for it. Upgrade steps are also marked upgrade_step on the tasks endpoint, so they stay out of the loose task list on such an installation, where the upgrade endpoint returns nothing to filter by.

Panel shape (2026-08-16). One card per release: the current boundary open with runnable steps, past boundaries below as collapsed "Completed" cards, newest first, with no Run buttons — re-running a conversion the store already applied is how an upgrade does damage. The page is three tabs (Upgrade / Tasks / History) on a new Tabs primitive in dashboard-ui, the first in the design system.

No sample tasks ship in core (2026-08-16). The reference CSV task written during Phase 5 was deleted: it was example code, and registering it put a task nobody asked for in every merchant's dashboard. The CSV machinery is covered by a spec-local task, and the authoring guide keeps a worked example.

Superseded steps (2026-08-16). The panel first shipped listing every step of every manifest — 31 on a 6.0 install, nine of which a store already on 5.6 must never re-run, and growing with each release. Fixed by recording the boundary rather than inferring it: Spree::UpgradeRecord is stamped by a completed walk and by a fresh install, pending_steps starts from it, and steps are grouped by release boundary. Where no stamp exists the boundary is assumed (one release back) and reported as assumed, so a store that skipped releases is pointed at the earlier steps rather than having them silently disappear — the failure mode of a plain auto-mark.

One deferred item, with what unblocks it:

  • Per-task permission scoping (requires_permission :write_orders beside the runner key) — revisit only if a merchant asks for a role that may run some tasks but not others; the run audit is expected to make that unnecessary.

References

  • Shopify maintenance_tasks — https://github.com/Shopify/maintenance_tasks (authoring contract, run statuses, throttle_on/report_on, CLI)
  • Rails 8.1 ActiveJob::Continuable / ActiveJob::Continuation
  • spree/core/app/jobs/spree/imports/process_job.rb, spree/core/app/jobs/spree/product_types/apply_to_products_job.rb — Continuable references in core
  • spree/core/lib/tasks/upgrade.rake, spree/core/lib/spree/upgrades/5_6_to_6_0/manifest.yml
  • docs/plans/6.0-service-workflows.md — "Durability = plain Rails"
  • docs/plans/6.0-admin-rbac.md — permission catalog registration
  • docs/plans/5.6-admin-spa-csv-import.md — direct-upload flow, polling
  • docs/plans/decisions.md 2026-08-07 — lifecycle events are the only audit; same date — "the data tasks are steps in the upgrade manifest, 'code deployed, task not yet run' is not a state Spree supports"
  • spree/core/lib/spree/core/permission_configuration.rb (register_resource), spree/core/app/models/spree/setup_tasks.rb (a registry object precedent), spree/core/app/models/concerns/spree/preference_schema.rb (the RegisteredSubclasses extraction note)
  • packages/dashboard/src/hooks/use-imports.ts (2s polling while active), packages/dashboard/src/routes/_authenticated/$storeId/settings/integrations.tsx (gallery of registered classes — closest existing page shape)