3c43c8d5c8
Records the approved domain rename (equipment plugin/tables/API -> machines) and the lossless retyping of the models catalog (legacy machinetypes -> modeltypes), with migration placement per ADR-008. Implementation lands in the following commits. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
68 lines
3.7 KiB
Markdown
68 lines
3.7 KiB
Markdown
# ADR-011: Rename the equipment domain to machines; retype the models catalog with modeltypes
|
|
|
|
- **Status:** ACCEPTED
|
|
- **Date:** 2026-07-11
|
|
- **Deciders:** cproudlock
|
|
- **Relates to:** ADR-005 (equipment vs measuringtools scope), ADR-008 (plugin migration ownership)
|
|
|
|
## Context
|
|
|
|
ADR-005 split the old "equipment" concept: gage-lab instruments moved to the
|
|
measuringtools plugin, leaving the equipment plugin holding exactly one thing -
|
|
shop-floor machines (lathes, mills, CMMs, grinders, furnaces). The UI, the
|
|
routes (`/machines`), the frontend view folder (`views/machines/`), and even
|
|
the data vocabulary (asset numbers headed "MACHINE #") already said machines.
|
|
Only the code identity still said equipment: the plugin name, the API prefix,
|
|
the `equipment`/`equipmenttypes` tables, and the `assettype='equipment'` data
|
|
value. Every future contributor would pay a small permanent translation tax.
|
|
|
|
A display-label-only swap was shipped first (2026-07-11) and immediately showed
|
|
the dissonance: UI Machines over code equipment forever.
|
|
|
|
Separately, the legacy `machinetypes` table survived the Machine-model
|
|
retirement for one real reason: it types the vendor **models catalog**
|
|
(`models.machinetypeid`, 95 of 127 models) with fine-grained, cross-category
|
|
types (Lathe, Switch, Laser Printer). Its name was a misnomer - it never typed
|
|
machines specifically - and it squatted on the name the machines plugin's
|
|
subtype table wants.
|
|
|
|
The economics favor doing this now and never again: the plugin contract is
|
|
pre-1.0 (breaking changes are cheap per ADR-002), no sister site has adopted
|
|
yet, there is no production instance, and the test suite plus CI give the
|
|
strongest safety net the project has had.
|
|
|
|
## Decision
|
|
|
|
Rename the domain in one coordinated pass:
|
|
|
|
| Current | New | Rationale |
|
|
|---|---|---|
|
|
| `plugins/equipment/`, `/api/equipment`, `equipment.*` perms | `plugins/machines/`, `/api/machines`, `machines.*` | plugin identity matches the domain |
|
|
| `equipment` table, `equipmentid` | `machines`, `machineid` | main entity |
|
|
| `equipmenttypes`, `equipmenttypeid`, `equipmenttype` | `machinetypes`, `machinetypeid`, `machinetype` | subtypes take the freed name |
|
|
| legacy `machinetypes`, `models.machinetypeid` | `modeltypes`, `models.modeltypeid` | role-accurate: it types the models catalog, losslessly (no collapse to the 4 asset types) |
|
|
| `assettypes.assettype = 'equipment'` (data) | `'machine'` | the string compare sites flip with it |
|
|
|
|
Migration placement follows ADR-008: the modeltypes rename and the data flips
|
|
land in the core chain (core tables, core data); the plugin table renames land
|
|
in the machines plugin's own chain, idempotently guarded so fresh installs
|
|
(whose core chain still creates the old names at `7c04`) rename on first
|
|
`flask plugin upgrade-all`. The `alembic_version_equipment` version table is
|
|
renamed to `alembic_version_machines` by the core migration so the plugin chain
|
|
resumes seamlessly on existing installs. The plugin registry auto-migrates an
|
|
`equipment` key to `machines` on load.
|
|
|
|
Historical migrations and accepted ADRs are not rewritten; old ids and ADR-005
|
|
wording remain as history.
|
|
|
|
## Consequences
|
|
|
|
- Upgrading instances run `flask db upgrade` then `flask plugin upgrade-all`,
|
|
same as every deploy; both migrations are idempotent.
|
|
- `/api/equipment` and `equipmentApi` cease to exist - a breaking change made
|
|
while there is nobody to break. After contract 1.0 this class of rename
|
|
would be a major-version event; this is the last cheap moment.
|
|
- The "Machine Types" settings card becomes "Model Types" and finally says
|
|
what it does; the machines plugin's subtype card owns the machine-types name.
|
|
- Contributors stop translating between UI vocabulary and code vocabulary.
|