spree_core 5.6.1 → 6.0.0.beta2

data/lib/spree/upgrades/5_6_to_6_0/manifest.yml

@@ -0,0 +1,683 @@
+# Spree 5.6 → 6.0 upgrade manifest.
+#
+# Lists ONLY the version-specific rake tasks that perform data backfills.
+# Universal upgrade steps (bundle update, db:migrate, scheduling cron jobs,
+# reviewing breaking changes) are NOT in this file:
+#
+#   - `bundle update` + `db:migrate` are handled by your deploy pipeline
+#     (Heroku release phase, K8s init container, Render auto-migrate,
+#     Capistrano deploy hook, etc.) and by the @spree/cli's `spree upgrade`
+#     wrapper for local development.
+#   - Cron scheduling, optional tunings, and human-readable behavior changes
+#     live in the upgrade doc at docs/developer/upgrades/5.6-to-6.0.mdx.
+#
+# This manifest is the machine-runnable shape — what `bin/rake spree:upgrade`
+# (in production) and `spree upgrade` (in dev) execute. Every step must be a
+# rake task and must be idempotent. Re-running the full manifest is safe.
+---
+from: "5.6"
+to: "6.0"
+docs: "https://spreecommerce.org/docs/developer/upgrades/5.6-to-6.0"
+
+steps:
+  - id: consolidate_metadata
+    name: "Check for leftover split metadata columns"
+    task: "spree:upgrade:consolidate_metadata"
+    notes: |
+      Spree 6.0 collapses the public_metadata / private_metadata column pair into a
+      single metadata column. The migration performs the merge itself, before it
+      drops public_metadata, so a normal db:migrate needs nothing from this step.
+
+      This is a safety net for installs whose schema was changed out of band — a
+      manually dropped column, a half-applied migration, or an extension table that
+      adopted the same pair and was skipped. It reports and merges anything still
+      carrying both columns.
+
+      Idempotent, and a no-op on an already-consolidated schema.
+
+  - id: migrate_media_class_names
+    name: "Rewrite stored Spree::Asset and Spree::Image class names"
+    task: "spree:migrate_media_class_names"
+    notes: |
+      Spree::Asset and Spree::Image became Spree::Media in 6.0. The table rename
+      (spree_assets to spree_media) travels with db:migrate, but the old class
+      names are also written into data — custom field resource types, and any
+      polymorphic type column an extension points at media rows.
+
+      Run immediately after db:migrate. Spree::Asset stays readable as a
+      deprecated alias until 6.1, so code referencing it keeps working either
+      way; this step is about the stored strings.
+
+      Idempotent — rows already saying Spree::Media are left alone.
+
+  - id: migrate_master_images_to_product_media
+    name: "Re-home variant-pinned media onto the product"
+    task: "spree:media:migrate_master_images_to_product_media"
+    notes: |
+      Moves images pinned to a variant onto the product's own gallery, linking
+      them back to the variants that had them. Enqueues one background job per
+      affected product, so let the queue drain before the next step.
+
+      Run this BEFORE spree:remove_master_variant — deleting a ghost master
+      variant that still owns media would take the media with it.
+
+      Idempotent — re-running skips products that are already migrated.
+
+  - id: backfill_media_store_ids
+    name: "Assign a store to media rows that predate the store binding"
+    task: "spree:upgrade:backfill_media_store_ids"
+    notes: |
+      Spree 6.0 gives every media row its own store_id so the media library can
+      list files that are not yet attached to anything. Media used to reach its
+      store through its viewable; a file uploaded before anyone has decided
+      where it goes has no viewable to ask.
+
+      Each row is matched to its product's store. Media whose viewable was
+      deleted out from under it goes to the default store — a row with no store
+      is invisible to every library query and would otherwise sit in storage
+      with no way to find or delete it.
+
+      Run this AFTER spree:media:migrate_master_images_to_product_media and let
+      its jobs drain: that step moves media between viewables, and a row
+      re-homed afterwards would keep the store stamped here.
+
+      Idempotent — rows that already carry a store_id are skipped, so an
+      interrupted run resumes for free.
+
+  - id: remove_master_variant
+    name: "Migrate products off the master variant"
+    task: "spree:remove_master_variant"
+    notes: |
+      Backfills spree_products.default_variant_id and retires the hidden master
+      variant: simple products' masters become regular variants, ghost masters
+      on products with variants are deleted (or kept as regular variants when
+      they still carry line items), and variant_count is recomputed to the real
+      count. Until this runs, products have a NULL default_variant_id.
+
+      Run spree:media:migrate_master_images_to_product_media first and let its
+      jobs finish, so no master-pinned media is lost when ghost masters are
+      deleted.
+
+  - id: migrate_taxons_to_categories_and_collections
+    name: "Migrate taxons to categories and collections"
+    task: "spree:migrate_taxons_to_categories_and_collections"
+    notes: |
+      Migrates rule-based (automatic) taxons into Spree::Collection — copying
+      their rules, product membership and translations, and moving the ActionText
+      description, images, custom fields and slugs onto the new collection — then
+      deletes the migrated automatic taxon. Manual taxons stay as categories.
+
+      Severs the taxonomy structure: backfills store_id from the taxonomy, drops
+      taxonomy roots left childless, and nulls taxonomy_id on the survivors
+      (categories are store-owned in 6.0). Finally backfills the renamed
+      class-name strings ('Spree::Taxon*' -> 'Spree::Category*') across the
+      custom-field, attachment, ActionText, friendly_id slug and promotion-rule
+      columns.
+
+      Idempotent. Multi-tenant installs run the per-tenant override shipped by
+      spree_multi_tenant.
+
+  - id: backfill_library_media_placements
+    name: "Place existing category and collection images in the media library"
+    task: "spree:upgrade:backfill_library_media_placements"
+    notes: |
+      Category and collection images used to exist only as attachments —
+      in storage but invisible to the media library. New uploads create their
+      library placement on save; this walks the records that predate that.
+
+      Runs after backfill_media_store_ids so the library the placements land
+      in is already store-scoped, and after
+      migrate_taxons_to_categories_and_collections, which moves image
+      attachments onto collections with a callback-bypassing write — a
+      placement created before that step would be left behind on the category.
+
+      Idempotent — slots that already have their placement are skipped.
+
+  - id: migrate_users_to_customers
+    name: "Move users onto the gem-owned Customer/AdminUser models"
+    task: "spree:upgrade:migrate_users_to_customers"
+    notes: |
+      Copies the legacy Devise user table (default spree_users) into
+      spree_customers, preserving ids so the renamed customer_id foreign keys
+      still resolve and mapping encrypted_password -> password_digest, then
+      re-points every polymorphic reference that named the old customer class
+      (default Spree::User) to Spree::Customer — the user_type columns plus
+      customer_type on customer-group memberships — and backfills password_digest
+      on spree_admin_users.
+
+      Precondition: NO Devise pepper. encrypted_password is a plain bcrypt digest
+      that has_secure_password reads directly only when unpeppered; the task
+      aborts if Devise.pepper is set. Because Devise is gone in 6.0 a former
+      pepper can't be introspected, so when Devise is absent the task aborts until
+      you confirm none was used with CONFIRM_NO_PEPPER=true. Peppered / SSO /
+      non-bcrypt installs keep a custom customer_class instead (see the 5.6-to-6.0
+      upgrade guide) and skip this step.
+
+      Source rows with a blank email, or whose email is already owned by a
+      different customer, abort the task with their ids — reconcile them or pass
+      SKIP_INVALID_ROWS=true to skip and continue.
+
+      Idempotent. The source table is left in place as a safety net — drop it
+      manually once the migration is verified. Override the source with
+      SOURCE_USER_TABLE / SOURCE_USER_TYPE and batch size with BATCH_SIZE.
+
+  - id: migrate_rich_text_to_columns
+    name: "Move rich text out of Action Text into its own columns"
+    task: "spree:migrate_rich_text_to_columns"
+    notes: |
+      Copies category and collection descriptions, policy bodies, and the order
+      and customer internal notes out of action_text_rich_texts into the text
+      columns that own them in 6.0. Content is sanitized on the way in and
+      per-locale rows land in the model's translation table.
+
+      Ordering is load-bearing in both directions. Run AFTER
+      migrate_taxons_to_categories_and_collections, which retypes the Action Text
+      rows from 'Spree::Taxon' to 'Spree::Category' so they stay findable. Run
+      AFTER migrate_users_to_customers too: a note is copied onto the customer
+      row it belongs to, and those rows do not exist until that step populates
+      spree_customers — running earlier would count every legacy customer note as
+      orphaned and skip it for good.
+
+      Only copies where an Action Text row exists, so content already in the
+      column is never overwritten. Source rows are left in place as the rollback
+      path and are dropped with the Action Text tables in 6.1. Idempotent.
+
+  - id: migrate_shipping_to_delivery
+    name: "Backfill fulfillment & delivery naming"
+    task: "spree:migrate_shipping_to_delivery"
+    notes: |
+      Rewrites stored 'Spree::Shipment' class-name strings (state changes,
+      stock movements, legacy adjustments), renames the terminal fulfillment
+      status 'shipped' -> 'fulfilled', backfills the fulfillment provider on
+      delivery methods (DigitalDelivery calculators become the Digital
+      provider) and copies the provider-derived type onto existing
+      fulfillments, and converts display_on into the storefront_visible
+      boolean. Idempotent — the visibility conversion clears display_on as it
+      goes, so re-running never overwrites a visibility change made in the
+      admin after the upgrade. Digital shipping categories are handled by
+      migrate_delivery_profiles.
+
+      BREAKING — product CSV: the 'shipping_category' column is gone from both
+      import and export, replaced by 'product_type'. Update saved import
+      templates and any integration reading the export. A stale file is
+      ignored rather than rejected, so it imports without delivery
+      eligibility. This task assigns types to existing digital products;
+      new imports must carry 'product_type' themselves.
+
+  - id: migrate_delivery_profiles
+    name: "Promote shipping categories to delivery profiles"
+    task: "spree:migrate_delivery_profiles"
+    notes: |
+      The schema migration renames spree_shipping_categories to
+      spree_delivery_profiles in place, so 5.x product assignments carry
+      over without copying. This task makes the judgement calls: assigns each
+      legacy row its store (duplicating rows shared across stores), detects
+      digital categories (linked only to Digital-provider methods) as
+      Digital-kind profiles, folds categories that don't narrow the store's
+      method set into the store default profile, and moves each solely-linked
+      delivery method into its category's profile. A method linked to several
+      categories stays in the default profile with a loud warning — the
+      single-parent model cannot express the old m:n; recreate the method
+      inside the other profile if both links were intended. Run after
+      migrate_shipping_to_delivery (it reads the backfilled fulfillment
+      providers). Idempotent — processed rows gain a store_id and drop out of
+      the work set. spree_shipping_method_categories survives to 6.1 as the
+      source and rollback reference.
+
+  - id: migrate_fulfillment_statuses
+    name: "Remap fulfillment statuses"
+    task: "spree:migrate_fulfillment_statuses"
+    notes: |
+      Moves fulfillments onto the unfulfilled/fulfilled/delivered vocabulary.
+      'pending' and 'ready' both become 'unfulfilled' — the difference between
+      them was the order's payment state, which is no longer a property of a
+      fulfillment. 'ready_for_pickup' becomes 'fulfilled', which is what
+      "waiting at the counter" means now. Pickup fulfillments already marked
+      fulfilled become 'delivered' with delivered_at copied from fulfilled_at:
+      under the old machine a pickup reached that status only when the customer
+      collected it, so it records confirmed receipt. Shipping fulfillments stay
+      'fulfilled' — whether they arrived was never tracked before 6.0. Order
+      rollups are recomputed rather than mapped. Run after
+      migrate_delivery_profiles (it reads delivery-method providers to tell
+      pickup methods apart). Idempotent.
+
+  - id: migrate_deliveries
+    name: "Move tracking numbers onto deliveries"
+    task: "spree:migrate_deliveries"
+    notes: |
+      Every fulfillment carrying a 5.6 tracking number gets one delivery row
+      with that number: the carrier axis (tracking number, carrier, carrier
+      status, estimate, arrival) lives on spree_deliveries in 6.0, and the
+      fulfillment only summarizes its primary delivery. A pasted tracking link
+      lands in the delivery's tracking_url; the carrier is detected from the
+      number's format. Run after migrate_fulfillment_statuses. Idempotent —
+      a fulfillment that already has a delivery is skipped. No labels are
+      backfilled: nothing before 6.0 recorded one.
+
+  - id: migrate_zones_to_delivery_zones
+    name: "Convert delivery zones"
+    task: "spree:migrate_zones_to_delivery_zones"
+    notes: |
+      Converts legacy Spree::Zone rows referenced by delivery methods into
+      Spree::DeliveryZone records with typed country/state members and
+      re-points the join rows. Run immediately after db:migrate, before
+      creating new delivery zones, so unmigrated ids stay unambiguous.
+      Tax-scoped zones are left for the tax-provider migration; unreferenced
+      shipping zones are logged and skipped. Idempotent via a
+      migrated_from_zone_id marker.
+
+      Members are written as ISO codes, resolved by reading spree_countries
+      and spree_states directly — countries and states are reference data in
+      6.0, so their models can no longer look the rows up.
+
+  - id: migrate_country_state_codes
+    name: "Name countries and states by ISO code"
+    task: "spree:upgrade:migrate_country_state_codes"
+    notes: |
+      Countries and states stop being database records in Spree 6. Addresses,
+      delivery zone members, market countries, stock locations and stores name
+      them by ISO code instead, and this fills those columns from the existing
+      foreign keys.
+
+      Delivery zone members that name a state also gain their country, which
+      the state row used to supply — a subdivision code is only unique within
+      its country, so the pair is what makes a member resolvable on its own.
+
+      Run after migrate_zones_to_delivery_zones so converted members are
+      present to be backfilled. Idempotent and resumable: each table is filled
+      with one statement scoped to the rows still missing a code, so an
+      interrupted run picks up where it stopped.
+
+  - id: migrate_promotion_option_value_rules
+    name: "Rewrite Option Value promotion rules to stable option value ids"
+    task: "spree:upgrade:migrate_promotion_option_value_rules"
+    notes: |
+      Spree 6.0 stores Option Value promotion rules against Spree::OptionValue
+      ids. Upgrades from 5.6 may still carry join-row ids from
+      spree_option_value_variants in the eligible_values preference — those
+      rows shift whenever variants are reconfigured, so a saved rule can start
+      matching different SKUs without warning.
+
+      Rewrites each rule's eligible_values array in place, mapping legacy
+      join-row ids to their option_value_id and leaving rows that already
+      name an option value untouched. Idempotent — re-running is a no-op once
+      every value resolves to an option value id.
+
+  - id: migrate_adjustments_to_typed_rows
+    name: "Convert adjustments to typed rows"
+    task: "spree:migrate_adjustments_to_typed_rows"
+    notes: |
+      Converts legacy spree_adjustments into TaxLine / Discount / Fee rows:
+      tax-rate rows become tax lines with rate snapshots, eligible promotion
+      rows become discounts (order-level amounts distributed across line items
+      largest-remainder), sourceless rows map by sign to manual discounts or
+      surcharges, and unknown sources become fees with provenance metadata.
+      Order totals are never modified; per-order reconciliation freezes and
+      logs any order whose typed sums don't match its stored totals.
+      ReturnAuthorization adjustments freeze the order for the returns
+      migration. spree_adjustments stays intact as the rollback source.
+      Idempotent — orders that already have typed rows are skipped.
+
+  - id: backfill_reason_store_ids
+    name: "Bind return and refund reasons to the default store"
+    task: "spree:upgrade:backfill_reason_store_ids"
+    notes: |
+      Return and refund reasons are store-owned in Spree 6. The rename
+      migration backfills them and enforces NOT NULL, so this is a safety net
+      for installs whose migration ran before any store existed.
+
+      Run before migrate_returns. Core looks three refund reasons up by name
+      scoped to a store, so a row without one is invisible to those lookups
+      and would mint a duplicate on the next refund. Idempotent — a no-op on
+      an already-migrated store.
+
+  - id: migrate_returns
+    name: "Move returns onto the new returns models"
+    task: "spree:upgrade:migrate_returns"
+    notes: |
+      Converts each ReturnAuthorization into a Spree::Return, or a
+      Spree::Exchange when any of its return items named an exchange variant,
+      copying line items with their received quantities and refundable
+      amounts. Refunds produced through a reimbursement are re-pointed at the
+      new record via the polymorphic originator, so the money history stays
+      visible in the admin.
+
+      Run AFTER migrate_adjustments_to_typed_rows, which freezes orders
+      carrying ReturnAuthorization adjustments for exactly this step.
+
+      Reads the legacy tables by name (the legacy models are gone in 6.0) and
+      writes history without validation, so rows referencing deleted variants
+      or stock locations still copy. The legacy tables stay in place as a
+      safety net and are dropped in 6.1.
+
+      Resumable by construction: the legacy number is copied onto the new
+      record and uniquely indexed there, so the task scopes itself to the
+      authorizations whose number isn't present yet. An interrupted run picks
+      up where it stopped and re-running when nothing is left is a no-op —
+      no cursor to track, no state to reset. Tune the load size with
+      BATCH_SIZE (default 500).
+
+      A row that can't be migrated is reported and skipped so one unconvertible
+      authorization doesn't stop the batch, but the task then aborts rather than
+      letting the upgrade proceed on top of incomplete returns history. Re-run
+      to retry those rows — the task only looks at what isn't migrated yet — or
+      pass SKIP_FAILED_ROWS=true to accept the gap and continue.
+
+  - id: migrate_stock_movements_to_typed_rows
+    name: "Type stock movements and reconcile open fulfillments"
+    task: "spree:migrate_stock_movements_to_typed_rows"
+    notes: |
+      Gives every pre-6.0 stock movement a kind and a concrete cause key
+      derived from its polymorphic originator: a fulfillment originator
+      becomes shipped or released by sign, a stock transfer becomes received
+      or shipped, a legacy return authorization becomes received against the
+      Return or Exchange it turned into, and a movement with no originator
+      becomes an adjustment reading "Legacy manual adjustment". A cause that
+      cannot be resolved is still typed by sign and simply carries no cause
+      key — a movement with no cause is still a true statement about stock.
+
+      Then reconciles the representation change. Stock leaves the shelf at
+      dispatch in 6.0, not at placement, so the units of every open
+      fulfillment on a placed order go back onto count_on_hand and are
+      allocated at the same time, with an allocated movement recording the
+      jump. Availability is unchanged by construction, since both sides of
+      "on hand minus allocated" move together, and backordered units need no
+      special case — the pair of increments cancels out the negative on-hand
+      that used to represent them.
+
+      Run AFTER migrate_shipping_to_delivery, which rewrites the
+      'Spree::Shipment' originator strings, and AFTER migrate_returns,
+      because a legacy authorization id says nothing about the new record:
+      the returns migrator preserves the number, not the id, and one
+      authorization can become either a Return or an Exchange.
+
+      Idempotent. Typing narrows to rows without a kind and reconciliation
+      skips fulfillments that already hold an allocation, so an interrupted
+      run resumes for free. That same predicate makes the deploy window safe:
+      a fulfillment shipped before the task runs never gets an allocation,
+      and dispatch only ships allocated units, so its stock is never
+      decremented twice. originator_type and originator_id stay in place as
+      the rollback path and are dropped in 6.1. Tune the load size with
+      BATCH_SIZE (default 5000).
+
+  - id: backfill_delivery_and_stock_store_ids
+    name: "Bind delivery methods and stock locations to the default store"
+    task: "spree:backfill_delivery_and_stock_store_ids"
+    notes: |
+      Delivery methods and stock locations carry a store_id in Spree 6.
+      Unassigned rows go to the default store; additional stores manage
+      their own records afterwards. The NOT NULL constraints land in 6.1.
+      Idempotent.
+
+  - id: migrate_tax_zones
+    name: "Convert tax zones to country and state references"
+    task: "spree:migrate_tax_zones"
+    notes: |
+      Tax rates name their jurisdiction directly in Spree 6 — merchants think
+      "Germany charges 19% VAT", and a tax line has to be able to report the
+      country that taxed it, which a zone spanning several countries cannot
+      say. Copies each rate's zone countries and states onto the rate, splitting
+      a multi-country zone into one rate per country. Zones with no members stay
+      as every-country rates.
+
+      Run immediately after db:migrate, BEFORE the migration that drops
+      spree_tax_rates.zone_id — that column is the only record of what a rate
+      was configured against. Spree::Zone itself is not dropped; shipping and
+      the browsing context still use it. Idempotent.
+
+  - id: backfill_tax_store_ids
+    name: "Bind tax rates and tax categories to the default store"
+    task: "spree:backfill_tax_store_ids"
+    notes: |
+      Tax rates and tax categories carry a store_id in Spree 6 — they are the
+      internal tax provider's configuration and belong to a store like every
+      other commerce setting. Unassigned rows, soft-deleted ones included, go
+      to the default store; additional stores manage their own records
+      afterwards. Category names become unique per store rather than globally,
+      so installs that relied on global names may need to reconcile duplicates
+      once several stores hold tax configuration. The NOT NULL constraints land
+      in 6.1. Idempotent.
+
+  - id: backfill_order_markets
+    name: "Backfill order markets"
+    task: "spree:backfill_order_markets"
+    notes: |
+      Market is mandatory in Spree 6. Assigns the store's default market to
+      orders that predate markets. Channel needs no step here — the 5.4→5.5
+      manifest's channels step already backfills channel_id on every upgrade
+      path. Run before the cart conversion so converted carts inherit
+      resolved values. The NOT NULL constraints on spree_orders land in 6.1.
+      Idempotent.
+
+  - id: migrate_incomplete_orders_to_carts
+    name: "Convert incomplete orders to carts"
+    task: "spree:migrate_incomplete_orders_to_carts"
+    notes: |
+      The final flip: every order that never completed nor canceled becomes a
+      Spree::Cart with the same token, binding, addresses and totals. Line
+      items, payments, payment sessions, reservations, coupon codes, applied
+      promotions and typed adjustment rows are re-owned onto the cart and the
+      hollow order row is deleted. Orders holding payment sessions convert
+      last. Completed and canceled orders are untouched. Run AFTER
+      migrate_adjustments_to_typed_rows so the typed rows exist to re-own.
+
+  - id: migrate_calculator_bounds_to_delivery_method_rules
+    name: "Convert calculator eligibility bounds to delivery method rules"
+    task: "spree:migrate_calculator_bounds_to_delivery_method_rules"
+    notes: |
+      Folds the FlatRate calculator's min/max item-total and weight
+      preferences into DeliveryMethodRule rows (eligibility separated from
+      pricing — see 6.0-delivery-method-rules.md) and clears the migrated
+      preferences so they aren't double-enforced. Run after
+      migrate_shipping_to_delivery. Idempotent.
+
+  - id: store_settings_backfill_from_config
+    name: "Copy moved commerce settings onto every store"
+    task: "spree:store_settings:backfill_from_config"
+    notes: |
+      Settings that describe how a shop sells moved from Spree::Config onto
+      Spree::Store in 6.0: track_inventory_levels, stock_reservations_enabled,
+      track_price_history, show_products_without_price, disable_sku_validation
+      and address_requires_phone. Two more were renamed on the way over —
+      company became company_field_enabled, and
+      default_stock_reservation_ttl_minutes became
+      stock_reservation_ttl_minutes.
+
+      The auto_capture and auto_capture_on_dispatch pair became a single
+      capture_method string, since the two booleans could contradict each
+      other. Both globals are read together: capturing at checkout wins when
+      both were set, which is what the old code did — money taken at checkout
+      left the dispatch capture with nothing to do.
+
+      Core reads the store with no fallback to the global, so an install that
+      set any of these in an initializer needs this step to keep its behavior.
+      A global left at its default is skipped, as is any store already carrying
+      a non-default value of its own.
+
+      Remove the settings from your initializer afterwards — the globals are
+      deprecated and are deleted in 6.1.
+
+      Idempotent: each store is visited at most once, recorded in its metadata,
+      so a later run never undoes a change made in the dashboard after the
+      upgrade.
+
+  - id: migrate_capture_methods
+    name: "Convert payment method auto_capture into capture_method"
+    task: "spree:migrate_capture_methods"
+    notes: |
+      Payment methods say when they charge with a capture_method string
+      (checkout, on_dispatch or manual) rather than an auto_capture boolean,
+      which could not express "charge this method on dispatch".
+
+      Methods that captured on authorization become 'checkout'. Methods with
+      auto_capture false are left empty on purpose: the old column only
+      recorded "not at checkout" and could not say whether dispatch or staff
+      was meant to take the money, so those rows keep inheriting the store's
+      own setting. Run after store_settings_backfill_from_config so the store
+      they inherit from already holds the right value.
+
+      The auto_capture column stays readable as a fallback for one release and
+      is dropped in 6.1. Idempotent — only rows without a capture_method are
+      written.
+
+  - id: product_types_backfill
+    name: "Backfill product type store ownership"
+    task: "spree:product_types:backfill"
+    notes: |
+      Assigns store-less product types to the default store, removes orphaned
+      option-type joins, and resets product counters. Idempotent.
+
+  - id: search_reindex
+    name: "Rebuild the search index"
+    task: "spree:search:reindex"
+    notes: |
+      Only affects installations running an indexing search provider —
+      Meilisearch, or any gem that declares indexing_required?. The database
+      provider queries live tables and needs nothing.
+
+      Documents gained a field describing which option values sit together on
+      the same variant, so "Blue and XL" means a product that sells a blue XL
+      rather than one selling a blue small beside a red XL. Existing documents
+      do not carry it, so a filter naming two or more option types matches
+      nothing until the index is rebuilt.
+
+      Safe to run at any time and safe to repeat; it re-enqueues every product.
+
+  - id: fold_store_credit_categories
+    name: "Fold store credit categories into the memo"
+    task: "spree:upgrade:fold_store_credit_categories"
+    notes: |
+      Store credits no longer carry a category in Spree 6. Their reason is the
+      originator (return, exchange, claim, gift card) plus the memo, so this
+      copies each legacy category name into the memo of credits that have
+      none. Admin-written memos are never overwritten. Idempotent, and a
+      no-op once the legacy tables are dropped in 6.1.
+
+  - id: migrate_stripe_webhook_keys
+    name: "Move Stripe webhook signing secrets onto the gateway"
+    task: "spree:upgrade:migrate_stripe_webhook_keys"
+    optional: true
+    notes: |
+      Only runs when spree_stripe is installed; skipped otherwise.
+
+      Signing secrets used to live in spree_stripe_webhook_keys, joined to
+      payment methods many-to-many because a payment method could be shared
+      across stores. A payment method belongs to exactly one store in 6.0, so
+      there is a single endpoint per gateway and the secret moves onto the
+      gateway's own preferences.
+
+      Until this runs, a gateway carrying a pre-6.0 endpoint has no signing
+      secret and rejects incoming webhooks. Idempotent — gateways that already
+      hold a secret are skipped, and the legacy tables stay in place as a
+      rollback path until they are dropped in 6.1.
+
+  - id: backfill_import_export_tenancy
+    name: "Place every import in a store, and a seller where one ran it"
+    task: "spree:upgrade:backfill_import_export_tenancy"
+    notes: |
+      An import used to carry a polymorphic owner that was either a Store or a
+      Seller, never both, so a seller-owned import had no store on it at all.
+      Spree 6.0 gives imports the same tenancy pair exports already had — an
+      always-present store_id, plus a seller_id that is null for the operator's
+      own — which is what lets a marketplace's list include the imports its
+      sellers ran.
+
+      Until this runs, imports created before the upgrade carry no store and
+      are invisible to every scoped query, including the admin list.
+
+      The owner_type/owner_id columns stay in place as this step's source and
+      its rollback path; they are dropped in 6.1, along with the deprecated
+      Import#owner reader. Exports need no data step — they have always had a
+      store, and their seller_id column is new for everyone.
+
+      Idempotent — imports that already carry a store are skipped.
+
+  - id: backfill_custom_field_definition_stores
+    name: "Bind custom field definitions to the default store"
+    task: "spree:upgrade:backfill_custom_field_definition_stores"
+    notes: |
+      Custom field definitions are store-owned in Spree 6.0, and their
+      sort/filter identifier is now a real column rather than a value computed
+      on every read. The migration backfills both and enforces NOT NULL, so
+      this is a safety net for installs whose migration ran before any store
+      existed.
+
+      Until this runs, a definition without a store is invisible to every
+      scoped query — the admin list, the CSV export's header row, and the
+      product listing's custom-field sorts and filters all read through the
+      store.
+
+      A multi-store install ends up with every definition on the default
+      store. Fields wanted on another store are re-created there; nothing is
+      copied automatically, because the values still point at the originals
+      and the copies would render blank either way.
+
+      Reports and skips any definition whose namespace/key pair flattens to a
+      filter_key another row in the same store already owns — only one of them
+      can be addressed as a sort or filter param. Rename one and re-run.
+      Idempotent.
+
+  - id: package_types
+    name: "Turn the store's default package into a package type row"
+    task: "spree:upgrade:package_types"
+    notes: |
+      The box a store ships parcels in used to be four loose preferences on
+      the store. It is now a row in the store's packaging vocabulary, beside
+      the cartons, pallets and containers a wholesale order leaves on, so the
+      same geometry can be named, reused, and referenced by the products
+      packed into it.
+
+      Until this runs, quotes for stores that had configured a box lose their
+      packaging tare and dimensions — carrier rates then under-price bulky
+      light items, which is what the dimensions were there to prevent. Stores
+      still on the seeded zeros are unaffected either way.
+
+      Idempotent — a store that already has a default package type is left
+      alone, so a box edited since the upgrade is never overwritten.
+
+  - id: migrate_external_receives_to_purchase_orders
+    name: "Turn 5.x supplier receives into purchase orders, and give every transfer a store"
+    task: "spree:upgrade:migrate_external_receives_to_purchase_orders"
+    notes: |
+      A 5.x supplier receive was recorded as a stock transfer with no source
+      location. Spree 6.0 has a purchase order for that — with a supplier, a
+      unit cost and an expected date — and a transfer now moves stock between
+      two of the merchant's own warehouses only.
+
+      Each source-less transfer becomes a received purchase order against a
+      "Migrated receives" supplier, its existing stock movements are re-pointed
+      at that order, and the transfer is soft-deleted so its T-… number stays
+      findable for historical reporting without the same receive appearing
+      twice in the admin. Historical unit costs are unknowable and recorded as
+      zero.
+
+      Until this runs, every pre-existing transfer has no store and no status.
+      A transfer without a store is invisible to the admin list, which reads
+      through the current store, and one without a status cannot be saved
+      through the app at all — so this is the step that makes existing
+      transfers usable again, not only the one that converts receives.
+
+      Stock is never touched: those movements already moved it, at the time.
+
+      Idempotent. A transfer whose movements no longer resolve to a variant is
+      reported and skipped rather than guessed at, and one bad row does not
+      stop the run. Purge the soft-deleted rows later with
+      spree:upgrade:purge_migrated_external_receives.
+
+  - id: recount_stock_levels
+    name: "Fill in the reserved and incoming counters on every stock level"
+    task: "spree:stock:recount_levels"
+    notes: |
+      Spree 6.0 keeps two more figures on each stock level beside on hand and
+      committed: reserved (units held by checkouts in progress) and incoming
+      (units on their way on an open purchase order or a transfer in transit).
+      Both are counters kept by the workflows that change them, and both start
+      at zero on an existing install.
+
+      This recomputes them from their sources — active reservations, open
+      purchase order lines and in-flight transfer lines — and rewrites any
+      level whose stored figure differs, printing each correction. Until it
+      runs, the Inventory page shows zero reserved and incoming for stock that
+      predates the upgrade.
+
+      Idempotent, and safe to re-run at any time to repair drift.