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.

Fix review findings on the delivery vocabulary rename

Damian Legawiec98807dcf9a35
diff --git a/docs/plans/6.0-fulfillment-and-delivery.md b/docs/plans/6.0-fulfillment-and-delivery.md
index 96a914497f..2732170493 100644
--- a/docs/plans/6.0-fulfillment-and-delivery.md
+++ b/docs/plans/6.0-fulfillment-and-delivery.md
@@ -27,7 +27,7 @@ Three changes in one:
**Ruby-level readers keep working through 6.0**, unlike the CSV column — the break there is justified because a CSV field is data a merchant re-exports, while a model reader is code an extension calls. `Product#shipping_category` and `#shipping_methods` stay as `deprecated: true` associations, and `Variant#shipping_category`/`#shipping_category_id` stay as explicit `Spree::Deprecation.warn` delegates (a plain `delegate` can't warn). `Variant` also gained `product_type`/`product_type_id` delegates alongside them. All four die with the table in 6.1.
-**Internal method vocabulary follows the models (2026-08-05).** Core code now calls the delivery/fulfillment names everywhere; the shipping-era names survive one release as `Spree::Deprecation.warn` bridges. Renamed: `Stock::Estimator#shipping_rates` → `#delivery_rates` (and its internals — `calculate_`/`choose_default_`/`sort_`, plus the `shipping_methods` filter seam → `#delivery_methods`, which host apps override), `Stock::Package#shipping_rates`/`#to_shipment` → `#delivery_rates`/`#to_fulfillment`, `Stock::Coordinator#shipments` → `#fulfillments`, `Order#line_items_without_shipping_rates` → `#line_items_without_delivery_rates`, `Order#ensure_available_shipping_rates` → `#ensure_available_delivery_rates` (private — no bridge), and `LineItem#shipping_cost`/`#display_shipping_cost` → `#delivery_cost`/`#display_delivery_cost`. **`Spree::Cart` gets no deprecation bridges at all** — it is new in 6.0, so no legacy caller can exist; its equivalent is simply `#ensure_available_delivery_rates`.
+**Internal method vocabulary follows the models (2026-08-05).** Core code now calls the delivery/fulfillment names everywhere; the shipping-era names survive one release as `Spree::Deprecation.warn` bridges. Renamed: `Stock::Estimator#shipping_rates` → `#delivery_rates` (and its internals — `calculate_`/`choose_default_`/`sort_`, plus the `shipping_methods` filter seam → `#delivery_methods`, which host apps override — `#delivery_methods` dispatches through the legacy name when a subclass or decorator has redefined it, so existing overrides keep filtering until 6.1 rather than being silently skipped), `Stock::Package#shipping_rates`/`#to_shipment` → `#delivery_rates`/`#to_fulfillment`, `Stock::Coordinator#shipments` → `#fulfillments`, `Order#line_items_without_shipping_rates` → `#line_items_without_delivery_rates`, `Order#refresh_shipment_rates` → `#refresh_delivery_rates`, `Order#ensure_available_shipping_rates` → `#ensure_available_delivery_rates` (private — no bridge), and `LineItem#shipping_cost`/`#display_shipping_cost` → `#delivery_cost`/`#display_delivery_cost`. **`Spree::Cart` gets no deprecation bridges at all** — it is new in 6.0, so no legacy caller can exist; its equivalent is simply `#ensure_available_delivery_rates`.
**Remaining for 6.0:** only the vendor axis (`belongs_to :vendor` replacing the `Spree::VendorConcern` decorator seam, `DeliveryMethodStockLocation` vendor-consistency validation, and refusing `pickup_stock_policy: 'any'` on vendor-owned locations). It is gated on `6.0-multi-vendor-marketplace.md` shipping the `vendor_id` column in its schema wave. Everything else outstanding is Phase 6 (6.1) cleanup.
@@ -310,12 +310,13 @@ Batched, idempotent, resumable — same guarantees as the split-adjustments migr
- API: switch `FulfillmentSerializer#fulfillment_type` from computed to column-backed; pickup endpoints (`/pickup_locations`, `/pickup_points`); `storefront_visible` exposure; regenerate the type pipeline. (Most serializer/route work already shipped — see "Already shipped".)
- **Emails gem** (20 files — never mentioned in the earlier draft): `shipment_mailer`, subscriber, templates → fulfillment vocabulary.
-- Dashboard (8 files still on `shipment` vocabulary) + CSV import/export contract (`shipping_category` is a documented public column — importers get a mapping + deprecation window) + user docs. The legacy Rails admin's 26 shipping files are **deleted with `spree/admin` at 6.0**, not renamed — admin fulfillment management lives in the dashboard via Admin API/SDK.
+- Dashboard (8 files still on `shipment` vocabulary) + CSV import/export contract + user docs. The legacy Rails admin's 26 shipping files are **deleted with `spree/admin` at 6.0**, not renamed — admin fulfillment management lives in the dashboard via Admin API/SDK.
+ - **CSV resolved 2026-08-05: `product_type` is required immediately, no mapping and no deprecation window.** This supersedes the earlier "importers get a mapping + deprecation window" intent — a compatibility mapping would translate onto a model that no longer decides anything (see the CSV note above). `shipping_category` is gone from both import and export.
### Phase 6 — cleanup (6.1)
- Drop deprecation aliases, `spree_shipping_categories` + `spree_shipping_method_categories`, `products.shipping_category_id`, dual-emitted `shipment.*` events, the dangling `admin_shipping_category_serializer` / v2 platform registrations.
-- Also added by the 2026-08-05 work: `DeliveryMethod#display_on` / `#display_on=` / `#available_to_display?` and the `DISPLAY_ON_FRONT_END`/`BACK_END` constants, the `deprecated: true` `shipping_method_categories` / `shipping_categories` associations on DeliveryMethod, the `deprecated: true` `shipping_category` / `shipping_methods` associations on Product, `Variant#shipping_category` / `#shipping_category_id`, and the `spree_delivery_methods.display_on` column. Plus the method bridges listed above: `Estimator#shipping_rates`/`#shipping_methods`, `Package#shipping_rates`/`#to_shipment`, `Coordinator#shipments`, `Order#line_items_without_shipping_rates`, and `LineItem#shipping_cost`/`#display_shipping_cost`. The CSV surface needs no cleanup — it was cut outright in 6.0.
+- Also added by the 2026-08-05 work: `DeliveryMethod#display_on` / `#display_on=` / `#available_to_display?`, the `DISPLAY_ON_FRONT_END`/`BACK_END` constants and the `DeliveryMethod.normalize_audience` shim that accepts them, the `deprecated: true` `shipping_method_categories` / `shipping_categories` associations on DeliveryMethod, the `deprecated: true` `shipping_category` / `shipping_methods` associations on Product, `Variant#shipping_category` / `#shipping_category_id`, and the `spree_delivery_methods.display_on` column. Plus the method bridges listed above: `Estimator#shipping_rates`/`#shipping_methods`, `Package#shipping_rates`/`#to_shipment`, `Coordinator#shipments`, `Order#line_items_without_shipping_rates`, `Order#refresh_shipment_rates`, and `LineItem#shipping_cost`/`#display_shipping_cost`. The CSV surface needs no cleanup — it was cut outright in 6.0.
- `FulfillmentSerializer#fulfillment_type` can drop its computed fallback once every install has run `spree:migrate_shipping_to_delivery`.
## Constraints on Current Work
diff --git a/spree/core/app/models/spree/delivery_method.rb b/spree/core/app/models/spree/delivery_method.rb
index ad7fce8f5d..eafc3c2dfa 100644
--- a/spree/core/app/models/spree/delivery_method.rb
+++ b/spree/core/app/models/spree/delivery_method.rb
@@ -195,13 +195,31 @@ module Spree
# An unrecognized audience raises rather than silently quoting storefront
# rates — a typo must not narrow the offer set unnoticed.
#
- # @param audience [Symbol] {STOREFRONT} or {BACKOFFICE}
+ # @param audience [Symbol, Integer] {STOREFRONT} or {BACKOFFICE}; the
+ # legacy DISPLAY_ON_* integers are accepted until 6.1
# @return [Boolean]
def available_to?(audience)
- case audience
+ case self.class.normalize_audience(audience)
when BACKOFFICE then true
- when STOREFRONT then storefront_visible?
- else raise ArgumentError, "unknown delivery audience #{audience.inspect} (expected #{STOREFRONT.inspect} or #{BACKOFFICE.inspect})"
+ else storefront_visible?
+ end
+ end
+
+ # Maps an audience onto {STOREFRONT}/{BACKOFFICE}, accepting the legacy
+ # DISPLAY_ON_* integers so callers holding the old constants keep working
+ # until 6.1. Anything else raises — a typo must not silently quote
+ # storefront-only rates.
+ #
+ # @param audience [Symbol, Integer]
+ # @return [Symbol]
+ def self.normalize_audience(audience)
+ case audience
+ when STOREFRONT, BACKOFFICE then audience
+ when DISPLAY_ON_FRONT_END, DISPLAY_ON_BACK_END
+ Spree::Deprecation.warn("Spree::DeliveryMethod::DISPLAY_ON_* audience filters are deprecated and will be removed in Spree 6.1. Use #{STOREFRONT.inspect} / #{BACKOFFICE.inspect} instead.")
+ audience == DISPLAY_ON_BACK_END ? BACKOFFICE : STOREFRONT
+ else
+ raise ArgumentError, "unknown delivery audience #{audience.inspect} (expected #{STOREFRONT.inspect} or #{BACKOFFICE.inspect})"
end
end
@@ -209,7 +227,7 @@ module Spree
# removed in 6.1.
def available_to_display?(display_filter)
Spree::Deprecation.warn('Spree::DeliveryMethod#available_to_display? is deprecated and will be removed in Spree 6.1. Use #available_to?(Spree::DeliveryMethod::STOREFRONT / BACKOFFICE) instead.')
- available_to?(display_filter == DISPLAY_ON_BACK_END ? BACKOFFICE : STOREFRONT)
+ available_to?(display_filter)
end
def delivery_range
diff --git a/spree/core/app/models/spree/order.rb b/spree/core/app/models/spree/order.rb
index 4016ebe2e7..9852cb7867 100644
--- a/spree/core/app/models/spree/order.rb
+++ b/spree/core/app/models/spree/order.rb
@@ -814,8 +814,19 @@ module Spree
ensure_updated_fulfillments
end
+ # Re-quotes every fulfillment for the given audience.
+ #
+ # @param audience [Symbol] {Spree::DeliveryMethod::STOREFRONT} (default)
+ # or {Spree::DeliveryMethod::BACKOFFICE}
+ # @return [Array<Array<Spree::DeliveryRate>>]
+ def refresh_delivery_rates(audience = DeliveryMethod::STOREFRONT)
+ fulfillments.map { |fulfillment| fulfillment.refresh_rates(audience) }
+ end
+
+ # @deprecated Use {#refresh_delivery_rates}; removed in 6.1.
def refresh_shipment_rates(audience = DeliveryMethod::STOREFRONT)
- fulfillments.map { |s| s.refresh_rates(audience) }
+ Spree::Deprecation.warn('Spree::Order#refresh_shipment_rates is deprecated and will be removed in Spree 6.1. Use #refresh_delivery_rates instead.')
+ refresh_delivery_rates(audience)
end
def set_shipments_cost
diff --git a/spree/core/app/models/spree/stock/estimator.rb b/spree/core/app/models/spree/stock/estimator.rb
index 7a1a8fb2b0..07dce36a62 100644
--- a/spree/core/app/models/spree/stock/estimator.rb
+++ b/spree/core/app/models/spree/stock/estimator.rb
@@ -69,8 +69,28 @@ module Spree
end
# The eligibility seam: every rate consumer (checkout, routing, cart
- # estimates) filters through here.
+ # estimates) filters through here, and host apps override it to add
+ # their own rules.
+ #
+ # Dispatches through the legacy +shipping_methods+ name so overrides
+ # written against it keep running until 6.1 — without this, a host
+ # override would be silently skipped and checkout could quote rates
+ # the host meant to filter out.
def delivery_methods(package, audience)
+ return shipping_methods(package, audience) if overrides_legacy_seam?
+
+ filter_delivery_methods(package, audience)
+ end
+
+ # @deprecated Call or override {#delivery_methods}; removed in 6.1.
+ # Only reached when a caller uses the old name directly — the override
+ # dispatch above goes straight to the override's own definition.
+ def shipping_methods(package, audience)
+ Spree::Deprecation.warn('Spree::Stock::Estimator#shipping_methods is deprecated and will be removed in Spree 6.1. Use #delivery_methods instead.')
+ filter_delivery_methods(package, audience)
+ end
+
+ def filter_delivery_methods(package, audience)
methods = package.eligible_delivery_methods
# Storeless orders exist only in specs; real orders always carry one.
methods = methods.merge(order.store.delivery_methods) if order.store
@@ -88,10 +108,13 @@ module Spree
end
end
- # @deprecated Use {#delivery_methods}; removed in 6.1.
- def shipping_methods(package, audience)
- Spree::Deprecation.warn('Spree::Stock::Estimator#shipping_methods is deprecated and will be removed in Spree 6.1. Use #delivery_methods instead.')
- delivery_methods(package, audience)
+ # True when a subclass or decorator redefined the legacy seam, so its
+ # filtering still applies.
+ def overrides_legacy_seam?
+ return @overrides_legacy_seam if defined?(@overrides_legacy_seam)
+
+ @overrides_legacy_seam =
+ method(:shipping_methods).owner != Spree::Stock::Estimator
end
end
end
diff --git a/spree/core/lib/spree/testing_support/factories/order_factory.rb b/spree/core/lib/spree/testing_support/factories/order_factory.rb
index 74f44854d3..d7b6715c74 100644
--- a/spree/core/lib/spree/testing_support/factories/order_factory.rb
+++ b/spree/core/lib/spree/testing_support/factories/order_factory.rb
@@ -89,7 +89,7 @@ FactoryBot.define do
# Set completed_at before refreshing shipment rates so order.completed? returns true
# This prevents the shipping rate selection from recalculating order totals
order.update_columns(completed_at: order.completed_at || Time.current, status: 'placed')
- order.refresh_shipment_rates(evaluator.shipping_method_filter)
+ order.refresh_delivery_rates(evaluator.shipping_method_filter)
end
factory :completed_order_with_pending_payment do
diff --git a/spree/core/spec/models/spree/delivery_method_spec.rb b/spree/core/spec/models/spree/delivery_method_spec.rb
index acd131dcbb..fac483313b 100644
--- a/spree/core/spec/models/spree/delivery_method_spec.rb
+++ b/spree/core/spec/models/spree/delivery_method_spec.rb
@@ -222,6 +222,13 @@ describe Spree::DeliveryMethod, type: :model do
expect(admin_only_delivery_method.available_to_display?(described_class::DISPLAY_ON_FRONT_END)).to be false
expect(admin_only_delivery_method.available_to_display?(described_class::DISPLAY_ON_BACK_END)).to be true
end
+
+ # A legacy caller holding the old constants must not crash mid-checkout.
+ it 'accepts the legacy integer filters in #available_to? as well' do
+ expect(admin_only_delivery_method.available_to?(described_class::DISPLAY_ON_FRONT_END)).to be false
+ expect(admin_only_delivery_method.available_to?(described_class::DISPLAY_ON_BACK_END)).to be true
+ expect(visible_delivery_method.available_to?(described_class::DISPLAY_ON_FRONT_END)).to be true
+ end
end
describe '#delivery_range' do
diff --git a/spree/core/spec/models/spree/stock/estimator_spec.rb b/spree/core/spec/models/spree/stock/estimator_spec.rb
index 529fc164d7..1e1f321709 100644
--- a/spree/core/spec/models/spree/stock/estimator_spec.rb
+++ b/spree/core/spec/models/spree/stock/estimator_spec.rb
@@ -238,6 +238,33 @@ module Spree
end
end
end
+
+ # Host apps override the eligibility seam to add their own rules. The
+ # 6.0 rename must not silently skip overrides written against the old
+ # name — that would quote rates the host meant to filter out.
+ describe 'eligibility seam overrides' do
+ let(:package) { build(:stock_package, contents: inventory_units.map { |_i| ContentItem.new(inventory_unit) }) }
+
+ it 'still invokes a legacy #shipping_methods override' do
+ called = false
+ estimator = Class.new(Estimator) do
+ define_method(:shipping_methods) { |_pkg, _audience| called = true; [] }
+ end.new(order)
+
+ estimator.delivery_rates(package)
+ expect(called).to be true
+ end
+
+ it 'invokes a modern #delivery_methods override' do
+ called = false
+ estimator = Class.new(Estimator) do
+ define_method(:delivery_methods) { |_pkg, _audience| called = true; [] }
+ end.new(order)
+
+ estimator.delivery_rates(package)
+ expect(called).to be true
+ end
+ end
end
end
end
diff --git a/spree/core/spec/models/spree/stock/package_spec.rb b/spree/core/spec/models/spree/stock/package_spec.rb
index 82e6c070df..2dde784c51 100644
--- a/spree/core/spec/models/spree/stock/package_spec.rb
+++ b/spree/core/spec/models/spree/stock/package_spec.rb
@@ -93,27 +93,27 @@ module Spree
end
end
- it 'can convert to a shipment' do
+ it 'can convert to a fulfillment' do
2.times { subject.add build_inventory_unit }
subject.add build_inventory_unit, :backordered
- shipping_method = build(:shipping_method)
- subject.delivery_rates = [Spree::DeliveryRate.new(delivery_method: shipping_method, cost: 10.00, selected: true)]
+ delivery_method = build(:delivery_method)
+ subject.delivery_rates = [Spree::DeliveryRate.new(delivery_method: delivery_method, cost: 10.00, selected: true)]
- shipment = subject.to_fulfillment
- expect(shipment.stock_location).to eq subject.stock_location
- expect(shipment.fulfillment_items.size).to eq 3
+ fulfillment = subject.to_fulfillment
+ expect(fulfillment.stock_location).to eq subject.stock_location
+ expect(fulfillment.fulfillment_items.size).to eq 3
- first_unit = shipment.fulfillment_items.first
+ first_unit = fulfillment.fulfillment_items.first
expect(first_unit.variant).to eq variant
expect(first_unit.state).to eq 'on_hand'
expect(first_unit).to be_pending
- last_unit = shipment.fulfillment_items.last
+ last_unit = fulfillment.fulfillment_items.last
expect(last_unit.variant).to eq variant
expect(last_unit.state).to eq 'backordered'
- expect(shipment.shipping_method).to eq shipping_method
+ expect(fulfillment.delivery_method).to eq delivery_method
end
describe '#add_multiple' do