Files

cproudlock d6725c08e0 Phase 0: lock platform contract, naming convention, and style enforcement

Establishes the framework's foundation as a multi-site adoptable platform.

ADRs (migrations/adr/):
- ADR-001 (ACCEPTED): Asset is the platform contract; Machine retires.
  Three relationship types (partof, controls, connectedto) with free-text
  label, position-resolution chain (asset > related > location),
  hierarchical locations, sibling-bay propagation.
- ADR-002 (ACCEPTED): Plugin contract semver via __contract_version__.
- ADR-003 (ACCEPTED): Hybrid plugin distribution (in-tree bundled +
  filesystem-based external).
- ADR-004 (ACCEPTED): Per-site instances, not multi-tenant.
- ADR-005 (ACCEPTED): Equipment plugin (manufacturing) split from
  measuringtools plugin (metrology). Subtype-table pattern for protocol
  data (FOCAS, CLM, MTConnect).
- ADR-006 (ACCEPTED): Plugin collector contract via get_collector_schema
  hook with API-key auth and identity-based upsert.

Naming convention v1 (CONTRIBUTING.md):
- DB tables/columns: lowercase concatenated, no underscores or dashes
- DB-mirrored Python/JS variables match column names exactly; pure code
  follows host-language convention (PEP 8 / camelCase)
- Closed acronym allowlist (universal + shop-floor domain), banned
  shorthand list with suffix exception (printers_bp etc allowed)
- Plain ASCII everywhere: chat, docs, comments, string literals

Style enforcement (scripts/check-naming-and-style.sh):
- Pre-commit-runnable check script: non-ASCII, banned shorthand,
  snake_case DB names, snake_case API params in frontend
- Fixes 14 violations across 11 files (Unicode arrows, snake_case
  params, ctx -> canvasContext, res -> response, req -> request_obj)

Project state (CLAUDE.md, README.md, frontend/CLAUDE.md):
- De-staled CLAUDE.md to reflect actual current state
- README unifies DB story (MySQL canonical, SQLite test-only)
- frontend/CLAUDE.md points at root convention

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-05-08 14:47:30 -04:00

3.8 KiB

Raw Blame History

ADR-002: Plugin contract versioning

Status: ACCEPTED
Date: 2026-05-08
Deciders: cproudlock
Supersedes: none

Context

Once sister sites start writing their own plugins (or pulling community plugins), the framework's plugin contract becomes a public API. Without a versioning story, any change to BasePlugin or the core platform models can silently break installed plugins at remote sites.

The existing BasePlugin and PluginMeta already declare a core_version field (default ">=1.0.0"), but it is not enforced anywhere. The plugin loader does not check it before instantiation.

Decision

The framework adopts semantic versioning for the plugin contract, declared in two places:

Framework version (shopdb/__init__.py): a single __contract_version__ constant. This is the version of the platform contract as defined in ADR-001. Bumped according to semver:
- Major: breaking change to BasePlugin ABC, PluginMeta schema, or any model in the platform contract (Asset, AssetType, AssetStatus, AssetRelationship, Vendor, Location, BusinessUnit, Model, OperatingSystem).
- Minor: additive change (new optional hook, new field on a contract model with default).
- Patch: bug fix, no contract surface change.
Plugin requirement (plugins/<name>/manifest.json): the existing core_version field, expressed as a semver range (e.g., ">=1.0.0,<2.0.0").

The plugin loader (shopdb/plugins/loader.py) checks core_version against __contract_version__ at load time. Mismatch in dev = re-raise (fail loud). Mismatch in prod = log error, mark plugin as incompatible, exclude from registration.

The __contract_version__ starts at 1.0.0 when ADR-001 is accepted and the Machine retirement migration is complete (whichever comes later). Until then, the framework is pre-1.0; plugins should declare core_version: ">=0.1.0,<1.0.0".

Consequences

Positive

Sister sites can pin a known-good framework version. They will not be silently broken when the framework is upgraded.
Plugin authors know what counts as a breaking change because the contract surface is enumerated in ADR-001.
The loader fails predictably: a mismatched plugin is reported, not silently disabled.

Negative / cost

Discipline required: every change to the contract surface must be classified (major / minor / patch). Adding a version-bump skill (or a check in code review) reduces the chance of mis-classification.
__contract_version__ becomes a coupling point. Forgetting to bump it after a breaking change means downstream plugins crash silently at runtime instead of failing at install.

Neutral

Existing plugins (plugins/printers/, etc.) ship as part of the framework, so their core_version is always the current __contract_version__. The discipline matters mostly for external / sister-site plugins.

Alternatives considered

No versioning, just trust. Works for an in-tree-only world. Fails the moment a sister site ships its own plugin. Rejected.
Calendar versioning (e.g., 2026.05.0). Easier to bump, harder to communicate breaking changes. Rejected; semver is the industry standard for library-like contracts.
Per-hook versioning. Each hook has its own version. Too granular; plugins still couple to multiple hooks. Rejected.

Open questions

When does the framework declare 1.0.0? Tied to ADR-001 (Asset retirement of Machine) and the framework being deemed "ready for sister sites". Best-effort target: end of Phase 5 in the refactor plan.
Should core_version accept commercial-grade ranges (^1.0.0) or stick to PEP 440 / npm-style ranges? Recommend pip-style (>=,<) to match Python ecosystem.

References

shopdb/plugins/base.py (PluginMeta declaration)
shopdb/plugins/loader.py (where the version check belongs)
ADR-001 (defines what is in the contract)

3.8 KiB Raw Blame History