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.
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_tasksendpoints 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 — overOpsTask(the branch name) orDataTask(excludes reindex/cache work by name). Tablespree_maintenance_task_runs, registrySpree.maintenance_tasks, keysread_/write_maintenance_tasks, routes/maintenance_tasks+/maintenance_task_runs, dashboard/settings/maintenance-tasks, rakespree: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 themaintenance_tasksgem (2026-08-15). The gem's runner ridesjob-iteration(a second interruption/cursor mechanism beside Continuable, which 6.0 already standardized on), and its UI is a server-rendered Rails engine onActionController::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 sameRails.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 underapp/" 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::MaintenanceTaskRunrecords 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 (nodestroyaction — cancel instead, same as returns/claims). Lifecycle events (maintenance_task_run.started/.succeeded/.errored/.canceled/.paused) fire throughpublishes_lifecycle_eventsso 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 theaccessgroup — admins only by default, nothing per task (2026-08-15).read_maintenance_taskslists tasks and runs;write_maintenance_tasksfires, pauses, resumes and cancels any registered task. It sits besidestaffandapi_keys— the sensitive group — so out of the box only the immutableadminrole holds it, and secret keys needwrite_maintenance_tasksorwrite_all. A merchant who wants a narrower "release engineer" role grants the key explicitly. A per-task declared permission (requires_permission :write_ordersbeside 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_idthe operator was acting in when it was fired from the dashboard/API (nullable — CLI runs may have none), and the runner setsSpree::Current.storefrom it for the whole execution, because6.0-store-scoped-configuration.mdrequires 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 carriesdry_run: true; the task readsdry_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/cancellingcannot 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 (statusinterrupted→ back torunning). (2) Time slicing — the runner interrupts itself aftermax_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);pausingstops the job and leavespaused+ cursor,cancellingstops it and leavescancelled. 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_collectiontasks 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:performand 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 inUpgrade::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 throughUpgradeStep; 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:migrateor 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 raisesInterruptif the adapter is stopping — and (c) runs the runner's own checkpoint: re-read the row's status; onpausing→ markpaused, return; oncancelling→ markcancelled,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 rescuesStandardErrorinside the step, records the error on the row (errored,after_error) and returns — neverdiscard_on, for the same reasonImports::ProcessJobrescues inside the step.InterruptinheritsExceptionand 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 onwrite_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 ano_collectionprocess(set-based SQL steps — still one run row, tallies fromupdate_allcounts). 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;
abortbecomes a raised error (runerrored, message on the row) or, for the reconcile-then-continue cases,skip_failed_rows-style attributes plusreport_on. putsprogress becomes ticks + tallies;DRY_RUN=1on the walker stays a plan printer, and steps that can preview declaresupports_dry_run.- Ordering constraints (run X after Y) are expressed as
preconditionblocks 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.rband the per-task specs port to task specs run throughStart.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
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}, themaintenance_taskscatalog resource,Upgrade::BackfillOrderMarketsas the reference task, and the spec battery (55 examples: interruption + resume viaActiveJob::Continuation::TestHelper, pause, cancel, dry-run,report_on, preconditions, one-active-run, unregistered task, masked arguments).RBAC + API — catalog resource
maintenance_tasks(groupaccess, subjectsMaintenanceTaskRun+:maintenance_task), controllers, serializers, typelizer → admin-sdkclient.maintenanceTasks/client.maintenanceTaskRuns, rswag docs.Dashboard — ✅ shipped 2026-08-15:
/settings/maintenance-tasksin 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 reportedwould_update: 3and wrote nothing, the subsequent real run wrote all three. Pending: an e2e spec.Upgrade integration — ✅ shipped 2026-08-15:
Spree::Upgradeextracted from the rake file so app code can read the manifests; the walker runs both step kinds throughMaintenanceTasks::Startso a shell walk records the same rows a dashboard run does; all 22 steps of the 5.6→6.0 manifest areSpree::MaintenanceTasks::Upgrade::*classes named bytask_class:;UpgradeStepwraps 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 acollection. Steps that genuinely walk rows —CaptureMethodsand the referenceBackfillOrderMarkets— are real collection tasks with cursors.CSV tasks — ✅ shipped 2026-08-15:
csv_collectionon 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, andUpdateVariantPricesas the reference CSV task.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, theSTEP=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 bytask_class:in the manifest — no newspree:migrate_*rake tasks. Until the primitive lands, a step written today must keep its body in a plain class with acollection-shaped "what's left" query and a per-rowprocess, so the port is mechanical. - Nothing gates on the
adminrole by name. Authorization is themaintenance_taskscatalog 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::Continuabledirectly when they are system-triggered (imports, product-type apply); the task primitive is for operator-triggered work. Do not convertImports::ProcessJobinto 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
argumentsunmasked; usemask_attributefor 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_ordersbeside 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 corespree/core/lib/tasks/upgrade.rake,spree/core/lib/spree/upgrades/5_6_to_6_0/manifest.ymldocs/plans/6.0-service-workflows.md— "Durability = plain Rails"docs/plans/6.0-admin-rbac.md— permission catalog registrationdocs/plans/5.6-admin-spa-csv-import.md— direct-upload flow, pollingdocs/plans/decisions.md2026-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(theRegisteredSubclassesextraction 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)