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.

docs(plans): reconcile Phase 2 and reorder taxons plan phases

Łukasz Adamczyk904e6c560cd9
diff --git a/docs/plans/6.0-replace-taxons-with-categories.md b/docs/plans/6.0-replace-taxons-with-categories.md
index 6cce70544a..e2d6a813bc 100644
--- a/docs/plans/6.0-replace-taxons-with-categories.md
+++ b/docs/plans/6.0-replace-taxons-with-categories.md
@@ -167,7 +167,7 @@ class Spree::Category < Spree.base_class
end
```
-> **Interim state:** today `Spree::Category < Spree::Taxon` (shares `spree_taxons`, no `type` column). The rename **flips** this — Category becomes the base class on `spree_categories` and `Spree::Taxon` becomes a deprecation alias (see Migration Phase 4). The design above is the post-rename target.
+> **Interim state:** today `Spree::Category < Spree::Taxon` (shares `spree_taxons`, no `type` column). The rename **flips** this — Category becomes the base class on `spree_categories` and `Spree::Taxon` becomes a deprecation alias (see Migration Phase 3). The design above is the post-rename target.
### Collection model
@@ -322,7 +322,7 @@ A scheduled job closes that gap for **time-based** rules:
- **Job** — `Spree::Collections::RegenerateTimeBasedJob < Spree::BaseJob` (`queue_as Spree.queues.collections`): selects automatic collections that have a rule whose `type` is registered as time-based and calls `Spree::Collections::RegenerateProducts` on each.
- **Cadence** — not hardcoded in the gem; wired by the host app's scheduler (sidekiq-cron / solid_queue recurring), the same pattern as `Spree::StockReservations::ExpireJob`. Hourly/daily is enough (`AvailableOn` windows are day-granular).
-> **`AvailableOn` ships fully now, but its implementation is interim.** The STI class ships in Phase 1 (registered in `collection_rules` alongside `Tag`/`Sale`) so the Phase 3 rake migrates `TaxonRules::AvailableOn` → `CollectionRules::AvailableOn` **1:1** (value + match_policy preserved) rather than dropping the data. Its `apply` is the **same legacy `spree_products.available_on` query the taxon rule already runs** — a faithful, zero-behavior-change carry-over (the taxon rule was equally channel-unaware), which keeps migrated automatic collections computing correct membership and lets the scheduled job above refresh them. One caveat holds until the reimplementation (Migration Phase 5):
+> **`AvailableOn` ships fully now, but its implementation is interim.** The STI class ships in Phase 1 (registered in `collection_rules` alongside `Tag`/`Sale`) so the Phase 4 rake migrates `TaxonRules::AvailableOn` → `CollectionRules::AvailableOn` **1:1** (value + match_policy preserved) rather than dropping the data. Its `apply` is the **same legacy `spree_products.available_on` query the taxon rule already runs** — a faithful, zero-behavior-change carry-over (the taxon rule was equally channel-unaware), which keeps migrated automatic collections computing correct membership and lets the scheduled job above refresh them. One caveat holds until the reimplementation (Migration Phase 5):
> - **Channel-unaware + on a doomed column.** The `available_on` column is superseded by the channel-scoped `ProductPublication#published_at` and is **removed** by `6.0-channels-catalogs-b2b.md` (its Phase 3 — "6.0 cleanup"). So `AvailableOn` is a **new reader of a column another 6.0 plan drops**. **Migration Phase 5** reimplements `apply` against `published_at` and — as a hard cross-plan ordering constraint — must land **before** the channels plan drops the column.
### Product changes
@@ -478,8 +478,8 @@ class CreateSpreeCollections < ActiveRecord::Migration[7.2]
end
add_index :spree_product_collections, [:collection_id, :product_id], unique: true
- # NEW table — NOT a rename of spree_taxon_rules (that stays live for automatic
- # taxons until Phase 4). STI type: Spree::CollectionRules::{Tag,Sale,AvailableOn}
+ # NEW table — NOT a rename of spree_taxon_rules (kept data-only for the Phase 4
+ # migration, dropped in 6.1). STI type: Spree::CollectionRules::{Tag,Sale,AvailableOn}
# (AvailableOn ships with an interim apply — see Automatic collection regeneration;
# no schema change when its Phase 5 channel-aware reimplementation lands).
create_table :spree_collection_rules do |t|
@@ -549,7 +549,7 @@ class RenameTaxonsToCategories < ActiveRecord::Migration[7.2]
end
```
-**Transitional tweak.** The tables are renamed here but the classes aren't renamed until Phase 4, so point the existing models at the renamed tables — otherwise the app and the Phase 3 rake task break in the middle state:
+**Transitional tweak.** The tables are renamed here but the classes aren't renamed until Phase 3, so point the existing models at the renamed tables — otherwise the app and the Phase 4 rake task break in the middle state:
```ruby
class Spree::Taxon < Spree.base_class
@@ -562,17 +562,38 @@ class Spree::Classification < Spree.base_class
end
```
-`spree_taxon_rules` is **not** renamed — the new `spree_collection_rules` already exists (Phase 1); the old table is migrated in Phase 3 and dropped in Phase 4.
+`spree_taxon_rules` is **not** renamed — the new `spree_collection_rules` already exists (Phase 1); the old table is migrated in Phase 4 and **dropped in 6.1 (Phase 6), not 6.0** (see Phase 3 for why).
-### Phase 3: Data migration (rake task)
+**Additional Phase 2 decisions (implemented):**
-Runs after the Phase 2 rename, so it reads the automatic rows from `spree_categories`. Classify by **structure, not taxonomy name.** Taxonomy names are Mobility-translated/localized and freely renamed, and default taxonomies are no longer auto-seeded (removed in 5.5, PR #14020) — so name matching is unreliable across upgraded and new stores alike. The real Category/Collection signal is already in the data: whether a taxon is rule-based.
+- **`classification_count` is dropped now** (not deferred). The direct taxon-side Rails counter was only read by the legacy `spree/admin` engine; the descendant-inclusive `products_count` is kept. The product-side counter is renamed `classification_count` → `categories_count`. `Classification`'s counter_cache follows to `categories_count`; the three taxon bulk services recompute `products_count` via `recalculate_products_count` instead of the removed counter. Legacy `spree/admin` views that read `taxon.classification_count` are **not** fixed (that engine is being replaced by the SPA) — the specs they break are marked `pending`.
+- **Mobility translation table is pinned transitionally.** Setting `Spree::Taxon.table_name = 'spree_categories'` makes Mobility derive `spree_category_translations` / `spree_category_id`, but that table is still `spree_taxon_translations` (renamed in 6.1). So the `translates` call pins `table_name: 'spree_taxon_translations', foreign_key: 'spree_taxon_id'` until the 6.1 sweep.
+- **Automatic-taxon matching code is removed here** (see Phase 3 rationale). Because 6.0 is single-delivery, the taxon auto-match path doesn't need to survive the rename: deleted `Products::AutoMatchTaxons` (+ job), `Taxons::RegenerateProducts`, `Product#auto_match_taxons` + `after_commit`, `Product.bulk_auto_match_taxons`, `Taxon#regenerate_taxon_products` + `after_commit`, and the `TaxonRule` regeneration callback. Rule-based membership now lives on `Collection`. `Price` re-match + the bulk-tags API endpoint now trigger `auto_match_collections` / `Product.bulk_auto_match_collections`; the bulk-category endpoints no longer re-match (category membership never affected rule matching).
+- **`eligible_for_taxon_matching?` → `eligible_for_collection_matching?`** (the `Product` predicate + the `Price` attribute).
+
+### Phase 3: Class renames + deprecation aliases
+
+Now that Collections exist (Phase 1) and the tables are renamed (Phase 2), rename the remaining classes and drop the transitional `self.table_name` tweaks from Phase 2. **This runs before the data migration (Phase 4)** so the migration script is written against the final model names (`Spree::Category`, `Spree::ProductCategory`, `Spree::Collection`) rather than the transitional ones. The inheritance is inverted today — `Spree::Category < Spree::Taxon`; the rename **flips it**: `Spree::Category` becomes the base class on `spree_categories`, and `Spree::Taxon` becomes the deprecation alias (removed in 6.1).
+
+- `Spree::Taxon` → `Spree::Category` (keep `Spree::Taxon` as a deprecation alias of `Spree::Category` for one release)
+- `Spree::Taxonomy` → deprecated, no replacement
+- `Spree::Classification` → `Spree::ProductCategory` (alias for one release)
+- `Spree::PromotionRuleTaxon` → `Spree::PromotionRuleCategory`; `Spree::Promotion::Rules::Taxon` → `Spree::Promotion::Rules::Category` (wire format is already `category` — `api_type` / `category_ids` — so the API contract is unchanged)
+- **Automatic-taxon matching code was removed in Phase 2, not here** — since 6.0 ships all phases at once (no released intermediate state), the taxon auto-match services + triggers were deleted in Phase 2 and rule-based membership moved to `Collection`. `Spree::TaxonRule` / `TaxonRules::*` remain as **data-only** models.
+- **Dropping `spree_taxon_rules` + `Spree::TaxonRule` / `TaxonRules::*` + the `config.spree.taxon_rules` registry is deferred to 6.1 (Phase 6), NOT 6.0.** The Phase 4 data migration *reads* `spree_taxon_rules` to build `CollectionRules`, but schema migrations (`db:migrate`) run automatically at deploy while the data migration is a manual rake task run afterward — a same-release `drop_table` would wipe the source before the data task runs. So the table + models are retained through 6.0 and dropped in 6.1.
+- The Mobility translation-table pin from Phase 2 carries over to `Spree::Category`; the actual table rename (`spree_taxon_translations` → `spree_category_translations` + FK) and dropping the pin are 6.1 (Phase 6).
+- Downstream shim: `alias_attribute :classification_count, :categories_count` on Product for the deprecation window (any app reading the old column keeps working)
+- Update all serializers, controllers, services, factories, specs for the rename
+
+### Phase 4: Data migration (rake task)
+
+Runs after the Phase 2 rename **and the Phase 3 class rename** — so the script reads via the final models (`Spree::Category`, `Spree::ProductCategory`) and writes the final Collection classes, with everything in place. Classify by **structure, not taxonomy name.** Taxonomy names are Mobility-translated/localized and freely renamed, and default taxonomies are no longer auto-seeded (removed in 5.5, PR #14020) — so name matching is unreliable across upgraded and new stores alike. The real Category/Collection signal is already in the data: whether a category is rule-based.
```ruby
# rake spree:migrate_taxons_to_categories_and_collections
#
# For every store, using store_id (backfill first — spree:taxons:backfill_store_id):
-# 1. Automatic taxons (automatic: true OR any taxon_rules) -> Spree::Collection
+# 1. Automatic categories (automatic: true OR any taxon_rules) -> Spree::Collection
# - copy their TaxonRules -> new CollectionRules (remap collection_id, rewrite STI type)
# Maps ALL types 1:1 — Tag, Sale, AND AvailableOn. AvailableOn's CollectionRule
# model ships in Phase 1 (interim legacy-column apply), so its rows migrate cleanly
@@ -580,8 +601,8 @@ Runs after the Phase 2 rename, so it reads the automatic rows from `spree_catego
# - copy their ProductCategories -> ProductCollections
# (regardless of which taxonomy / name they lived under)
# then delete the automatic rows from spree_categories
-# 2. Manual taxons -> Spree::Category (the nested-set tree, owned via store_id)
-# - manual taxons that happened to live under a "Collections" tree stay as
+# 2. Manual categories stay as Spree::Category (the nested-set tree, owned via store_id)
+# - manual categories that happened to live under a "Collections" tree stay as
# categories; merchants re-file them as collections via the new UI
# (safe, reversible — no name-based guessing)
# 3. Drop the now-empty taxonomy roots and the taxonomy_id references
@@ -590,24 +611,12 @@ Runs after the Phase 2 rename, so it reads the automatic rows from `spree_catego
# new 5.5+ stores (arbitrary or zero taxonomies).
```
-### Phase 4: Class renames + deprecation aliases
-
-Now that Collections exist (Phase 1), the tables are renamed (Phase 2), and the automatic data is migrated (Phase 3), rename the remaining classes and drop the transitional `self.table_name` tweaks from Phase 2. The inheritance is inverted today — `Spree::Category < Spree::Taxon`; the rename **flips it**: `Spree::Category` becomes the base class on `spree_categories`, and `Spree::Taxon` becomes the deprecation alias (removed in 6.1).
-
-- `Spree::Taxon` → `Spree::Category` (keep `Spree::Taxon` as a deprecation alias of `Spree::Category` for one release)
-- `Spree::Taxonomy` → deprecated, no replacement
-- `Spree::Classification` → `Spree::ProductCategory` (alias for one release)
-- `Spree::PromotionRuleTaxon` → `Spree::PromotionRuleCategory`; `Spree::Promotion::Rules::Taxon` → `Spree::Promotion::Rules::Category` (wire format is already `category` — `api_type` / `category_ids` — so the API contract is unchanged)
-- **Drop `spree_taxon_rules` + `Spree::TaxonRule` / `TaxonRules::*`** (in 6.0, not the 6.1 cleanup) — rows were copied to `spree_collection_rules` in Phase 3, and `CollectionRule` is net-new (not a rename), so there's no deprecation alias to keep.
-- Downstream shim: `alias_attribute :classification_count, :categories_count` on Product for the deprecation window (any app reading the old column keeps working)
-- Update all serializers, controllers, services, factories, specs for the rename
-
### Phase 5: Reintroduce channel-aware `AvailableOn` (after `6.0-channels-catalogs-b2b.md`)
Gated on the channels plan finishing the `available_on` → `ProductPublication#published_at` migration. Until then, `CollectionRules::AvailableOn` runs the interim legacy-column query shipped in Phase 1.
- **Reimplement `CollectionRules::AvailableOn#apply`** against `spree_product_publications.published_at` (join), replacing the raw `spree_products.available_on` query. Decide which channel a store-owned collection's availability rule evaluates against — the store's **default channel**, or any publication with `published_at` in the window — and document it (a collection has no channel of its own).
-- **No data migration, no registry change** — `AvailableOn` is already registered (Phase 1) and its `CollectionRule` rows already carry the right `value`/`match_policy` from Phase 3; only `apply` changes.
+- **No data migration, no registry change** — `AvailableOn` is already registered (Phase 1) and its `CollectionRule` rows already carry the right `value`/`match_policy` from Phase 4; only `apply` changes.
- **Cross-plan ordering constraint (hard).** `CollectionRules::AvailableOn` is a reader of `spree_products.available_on`, which `6.0-channels-catalogs-b2b.md` Phase 3 ("6.0 cleanup") drops. This phase **must land before** that column drop — the channels plan's cleanup is blocked on this reimplementation.
### Phase 6: Cleanup (6.1)
@@ -616,15 +625,17 @@ Gated on the channels plan finishing the `available_on` → `ProductPublication#
- Remove `taxonomy_id` column from categories
- Remove `spree_taxonomies` table, plus `Product#brand_taxon` / `#brand_name` and the `taxonomy_brands_name` locale key (brands out of scope — no replacement)
- Remove `automatic`, `rules_match_policy`, `sort_order` columns from categories (moved to collections)
+- **Drop `spree_taxon_rules` + `Spree::TaxonRule` / `TaxonRules::*` + the `config.spree.taxon_rules` registry** (retained data-only through 6.0 so the Phase 4 data migration can read them; rows were copied to `spree_collection_rules`, and `CollectionRule` is net-new so there's no alias to keep)
+- Rename the Mobility translation table `spree_taxon_translations` → `spree_category_translations` (+ FK `spree_taxon_id` → `spree_category_id`) and drop the transitional `table_name`/`foreign_key` pin on `translates`
## Constraints on Current Work
- **Use `categories` in all new API code.** The Store API already does this. Don't introduce new `taxon` references in API v3.
- **Use `Spree::Category` alias in new code where possible.** It exists today as `< Taxon`.
-- **Don't add new TaxonRule subtypes.** New rule types should be designed for the Collection model.
+- **Don't add new TaxonRule subtypes.** `TaxonRule` is data-only from 6.0 (matching removed); new rule types go on `CollectionRule`.
- **Don't add new Taxonomy-dependent features.** Taxonomy is going away.
- **Keep the `ctg_` prefix.** Already in use, will carry over.
-- **New "collection-like" features go on Taxon's automatic path for now** — they'll migrate cleanly to Collection.
+- **New "collection-like" (rule-based) features go on `Spree::Collection`** — the taxon automatic-match path was removed in Phase 2.
- **`ProductTypeCategory` join table** (from 6.0-product-types.md) should be named anticipating the Category rename — use `category_id` column, not `taxon_id`. (Already satisfied: `6.0-product-types.md` specifies `category_id`.)
- **Counter reads use the new names.** New code reads `products_count` (inclusive) on Category / `categories_count` on Product — not `classification_count` (being dropped/renamed).
- **No brand-specific features.** Brands are out of scope for 6.0 (see Key Decisions → Brands). Don't add a `Spree::Brand`, a brand column, a `:brands` tag context, or a category `kind` column; model brand grouping as a Category or Collection.