Files

cproudlock d1ba3a1a02 docs: stop typing versions the code already knows

Nine documents carried a hand-typed contract version and every one was stale.
One was load-bearing: PLUGIN-EXTERNAL-REPO.md told an external author to pin
">=0.13.0,<0.14.0" while the contract is at 0.19.0, so a plugin built by
following that guide is refused by the loader at startup. The plugin count was
wrong in six more.

They now point at docs/PROJECT-MAP.md, which is generated. A test enforces it:
no document may declare a version literal, a stated current version must match
the code, and a stated plugin count must match the tree. ADRs are exempt from
the current-version rule, because an ADR states the version a decision was taken
AT - that is a record of the past, and rewriting it would falsify the record
ADRs exist to keep.

CONTRACT-STABILITY.md was missing 0.17.0, 0.18.0 and 0.19.0 - including the only
BREAKING change in the series - in the one document a site reads to choose its
pin. All three are recorded, with 0.19.0 called out: it took something away, and
it shipped before it was written down, which is the argument for pinning tight
rather than trusting that a minor bump is safe.

2026-08-14 15:41:27 -04:00

5.7 KiB

Raw Blame History

Roadmap

shopdb-flask is pre-1.0 on both series. Current contract and product versions are in PROJECT-MAP.md, which is generated from the code rather than typed here. This document captures what stands between today and a stable 1.0.0 release. Maintained as scope evolves; supersedes nothing in the ADRs.

Phase status

Phase	Status	Commit
0 - Lock platform contract, naming, style enforcement	DONE	`d6725c0`
1 - pytest baseline, production hardening, pinned requirements	DONE	`2d1bb83`
2 - Plugin contract surface and compliance tests	DONE	`5fefb53`
3 - Manifest-first loader, shopdb.api namespace, auto-register blueprints	DONE	`6f085a1`
4 - Plugin scaffolding (`flask plugin new`)	DONE	`8eb9362`
5 - Alembic baseline, per-site deploy, ADRs to docs/adr	DONE	`d4e3ac9`
6 - Multi-site distribution readiness (settings-driven branding/ServiceNow/floor plan, security closeout, docs + Docker frontend build, release engineering)	DONE	v0.5.0-v0.7.0

The last big milestone before 1.0 is the legacy-ASP data import plus a production pilot deployment; the framework work below is what remains after that.

What's left before tagging 1.0.0

Must-have

Asset model fully wired. Asset.mapx, Asset.mapy columns, AssetRelationship.inheritsposition column, and the relationshiptypepropagations M:N table (RelationshipTypePropagation model; propagation lives on RelationshipType, not AssetRelationship). Models match the locked ADR-001 surface that resolve_asset_position already targets.
Equipment data migration script for facilities migrating from legacy ASP shopdb. One-shot script under scripts/migration/. Per ADR-001, only category='Equipment' AND machinenumber IS NOT NULL migrates.
Printers retirement. The printers plugin already runs on the asset architecture (blueprint printers_asset_bp); any remaining legacy printer-table cleanup is coordinated with the equipment migration.
External plugin UI packaging. The Vue-side hook contract ships (ADR-010: get_settings_cards / get_asset_panels / get_map_overlays / get_asset_presentation) and route gating is backend-driven (ADR-009), but plugin routes/views still live in core frontend/src. Let an external plugin ship its own Vue bundle so adopters can add UI without editing core.

Nice-to-have

Full palette theming. brand_primary_color and a few brand colors are settings-driven, but the rest of the CSS palette (surfaces, borders, accents) is still hardcoded in style.css. A complete theming pass would expose the palette as CSS variables a site can override, not just the brand colors.
Frontend scaffolding skill (the backend has flask plugin new; the frontend stub is currently manual copy-paste).
Marketplace listing site (PLUGINS.md is a one-pager; a proper listing with links to sister-site plugins becomes useful when there are more than three external plugins).
Plugin contract surface diff tooling. Today version bumps are manual judgment; a CI check that diffs the contract surface against the previous tag would catch missed bumps. See ADR-002.
Calibration cycles, maintenance windows, downtime tracking (domain extensions; would likely live in the machines and measuringtools plugins).

Deferred (out of scope for 1.0)

Multi-tenancy (rejected by ADR-004; revisit only if more than five sites adopt and operational overhead becomes painful).
Pip-installable plugins (deferred per ADR-003 v2). Filesystem distribution stays the v1 model.
Event bus on BasePlugin (removed per ADR-001; add via new ADR if a real use case appears).
Frontend rebuild beyond Vue 3 + Pinia + Vite (the existing stack is fine).

What 1.0.0 means

Tagging 1.0.0 is a commitment that the contract surface is stable for at least the next minor version cycle. Plugin authors at sister sites can pin core_version: ">=1.0.0,<2.0.0" and trust their plugin will not break on framework patches.

Concretely, 1.0.0 ships when:

ADR-001's full contract surface is implemented in code, not just documented (Asset.mapx, RelationshipType.propagatesthroughid, etc.)
The contract test suite covers every documented hook with both happy-path and a "broken plugin" failure-isolation test
At least one external plugin (likely measuringtools from the scaffold canary) has been built end-to-end with no contract changes required mid-build
The deploy runbook (DEPLOY.md) has been validated by an actual fresh-host deploy

Decision log pointers

When a roadmap item gets prioritized, document the why in a new ADR and link from this file. The ADRs are the canonical source for design decisions; this file is the prioritized backlog.

ADR-001 - Asset as platform contract
ADR-002 - Plugin contract versioning
ADR-003 - Plugin distribution model
ADR-004 - Deployment topology (per-site)
ADR-005 - Equipment vs measuringtools
ADR-006 - Collector contract pattern
ADR-007 - Product versioning and releases
ADR-008 - Plugin migration ownership (per-plugin chains)
ADR-009 - Frontend plugin route gating
ADR-010 - Frontend plugin hook contract
ADR-011 - Machines rename + modeltypes retyping
ADR-012 - GE-Enforce manifest ownership

5.7 KiB Raw Blame History