Files

cproudlock 534f179ee6 Make main the lean product a site receives

main was 16 days and 259 commits behind the line the product is actually built
on, at contract 0.30.0 against 0.35.0, with no per-PC credential code at all. It
was neither current nor curated - just stale. This brings it forward and, at the
same time, makes it mean something: main is what a receiving site installs, and
nothing else.

WHAT IT CARRIES. Twelve plugins - backups, computers, endpoints, guides,
knowledgebase, machines, network, notifications, printers, slides, tools,
warranty - plus applications, which is manifest-less core and always ships. The
only manifest dependency inside that set is endpoints on computers, and both are
in it, so the closure is self-contained.

WHAT IT DOES NOT. employees, geenforce, measuringtools, printedparts and usb
stay on the site line. So do the Windows installer tree, the VM rehearsal
helpers, the agent tooling config, one site's data loader, the internal audit
and findings records, and the planner spreadsheet. 1,135 tracked files against
1,438.

A REMOVAL THAT BREAKS THE APP IS NOT A REMOVAL, and two nearly shipped:

deploy/site-profile-universal.json still named all seventeen plugins. It is the
file docs/DEPLOY.md tells a site to provision from, so a fresh install would
have failed at `flask plugin apply-profile` with PluginError - the first thing a
receiving site does, broken by the branch meant to serve them. It now names the
twelve that exist, and its comment says the two must agree.

agent/ was never refreshed. Whoever populated this branch copied shopdb/,
plugins/, frontend/ and tests/ from the site line and left the agent tree at its
September state: 22 C# and PowerShell sources missing, including AgentCredentials,
EnrollmentService, AgentHttpFactory and the fleet-alert client, plus one file the
site line had deleted still present. The old tree is internally consistent, so it
compiles, and nothing in CI builds it - every gate was green over a server that
speaks enrollment and per-PC credentials to a bundled agent source that cannot.
Resynced whole.

DECISIONS THIS ENCODES, rather than defers:

- The plugin-authoring lab builds printedparts, whose manifest depends on
  employees, so it could not stay. The lab remains on the site line and main
  ships no build-along tutorial. That is a real loss for an adopting developer
  and is recorded here rather than discovered later.
- Recognition, Training and Recertification notifications are no longer seeded.
  Each splits one notification into a card per employee and renders a photo,
  which needs a plugin this branch does not bundle. Seeding them would offer an
  author a type that cannot resolve anybody. A site that installs employees gets
  them from that plugin's own seed.
- Windows/IIS is documented as the legacy path throughout, and the README leads
  with Docker, because that is what a receiving site gets.

The API description is regenerated for THIS branch - 347 paths and 483
operations, down from 415 and 573 - so the published contract describes what is
here rather than what the site line serves. docs/CONFIG.md lost the two
measuring-tool label keys the code no longer declares, which two lanes had
decided opposite ways.

Suite: 3124 passed, 6 skipped. Naming and style gates pass. The docs gates run
rather than skip, and every index line count is derived from the file it names.

2026-09-19 11:24:40 -04:00

4.9 KiB

Raw Blame History

ADR-007: Product versioning and releases

Status: ACCEPTED
Date: 2026-07-10
Deciders: ShopDB maintainers
Supersedes: none

Context

ADR-002 established semantic versioning for the plugin contract via __contract_version__ in shopdb/__init__.py. That number answers one question only: is a given plugin compatible with this platform build. It says nothing about the state of the product as a whole. A sister site standing up its own instance needs a different answer: which release am I running, and what changed since the last one.

Until now the product had no version, no tags, no changelog, and no CI. ADR-002's pinning model implicitly assumes that a downstream site can pin a known-good build, but there were no tags to pin to. Adopters had no release record to read before upgrading, and no automated gate confirming that a given commit builds and passes tests.

Decision

The product carries its own release version, separate from the plugin contract version.

Product version (shopdb/__init__.py): a single __version__ constant. This is the version of the shopdb-flask product as a whole. It follows semantic versioning of the product's user-visible and operator-visible behavior. It is deliberately NOT part of the shopdb.api contract surface, so it is never re-exported through shopdb.api; exporting it would itself be a contract change under ADR-002.
Plugin contract version (__contract_version__): unchanged from ADR-002. It moves only when the plugin contract surface changes, per the major/minor/patch rules in ADR-002.

The two are distinct series with independent bump rules. They happen to coincide at 0.5.0 for this release; that is a coincidence of timing, not a coupling. A product release that changes no contract surface bumps __version__ while leaving __contract_version__ fixed, and vice versa.

Release record (CHANGELOG.md, repo root): the canonical, human-readable record of what changed in each release, in Keep-a-Changelog format. Every release has an entry; work in flight accumulates under ## [Unreleased].
Git tags: each product release is tagged vX.Y.Z, where X.Y.Z matches __version__ at the tagged commit. Tags are what ADR-002's downstream-pinning model pins to.
Frontend version (frontend/package.json): kept in lock-step with __version__ so the shipped single-page app reports the same product version as the backend that serves it.

Release procedure

To cut release X.Y.Z:

Bump __version__ in shopdb/__init__.py to X.Y.Z.
Bump version in frontend/package.json to the same X.Y.Z.
Move the accumulated ## [Unreleased] notes in CHANGELOG.md into a new ## [X.Y.Z] - YYYY-MM-DD section, leaving a fresh empty ## [Unreleased] above it.
If the plugin contract surface changed this release, bump __contract_version__ per ADR-002 (independently of __version__).
Commit, then tag: git tag -a vX.Y.Z -m "shopdb-flask X.Y.Z".
Push the commit and the tag.

Consequences

Positive

Adopters have a real release to name in bug reports and a changelog to read before upgrading.
ADR-002's pinning story finally has tags to pin to.
Product and contract can evolve at their own pace without one dragging the other into a misleading bump.

Negative / cost

Two version numbers to keep straight. The comment in shopdb/__init__.py and this ADR exist to keep the distinction clear.
Release discipline: the changelog and both version constants must be updated together, or the tagged build misreports itself.

Neutral

The internal CI workflow runs the backend tests, the naming/style gate, and the frontend build on push and PR. It is best-effort: the internal CI Actions availability on the host is unverified, so the workflow is config-only until a runner is confirmed.

Alternatives considered

Reuse __contract_version__ as the product version. Conflates two independent concerns; a docs-only or UI-only release would either falsely bump the contract or leave the product looking unchanged. Rejected.
Calendar versioning for the product (e.g. 2026.07.0). Easy to bump but poor at signaling breaking operator-facing changes. Rejected for the same reasons ADR-002 rejected it for the contract.
No product version, rely on git SHAs. Opaque to adopters and unpinnable in any human-meaningful way. Rejected.

References

ADR-001 (defines the contract surface)
ADR-002 (plugin contract versioning; __contract_version__ bump rules)
shopdb/__init__.py (__version__, __contract_version__)
CHANGELOG.md (release record)
frontend/package.json (frontend version, kept in lock-step)
the internal CI workflow (CI gate)

4.9 KiB Raw Blame History