f9d6b57f0f
The docs lived on one lineage and the fleet code on another. That is why six pages described a shared fleet key as how an agent authenticates, why COLLECTOR-AUTH had to warn that the per-PC credential code was not in the repository it sat in, and why ADR-019 recorded a decision whose implementation was somewhere else. Documentation that cannot see the code it documents goes stale by construction, and no amount of editing fixes that. So the corpus moves here: 84 files, 56 pages, 20 ADRs, the proposals, INDEX.md, llms.txt and both gates. Filenames are unchanged, because a wiki page name is derived from the filename and a rename breaks every link anybody saved. THE POINT OF THE MOVE IS THE CORRECTION IT ENABLES. Every caveat that said "not in this tree" was false the moment the files landed beside the code, so each was rewritten from what is actually here: - COLLECTOR-AUTH gained the real enroll request body, the two bounds on the unauthenticated route (per-IP rate limit, pending cap with stale rows dropped before a real PC is refused), and the rejected pending reason that binds to the endpoint identity rather than the nonce. - ADR-019 now describes an implementation that is present, including its tests, and says plainly that what remains is the FLEET migration, not the code. - proposals/device-identity claimed phase 1 was unbuilt. plugins/computers declares deviceid on the collector schema and prefers it over the older fallbacks. Corrected in the page, its summary and the index. WINDOWS/IIS IS NOW DOCUMENTED AS THE LEGACY PATH, per the product decision, and carefully: it is what production runs today. Every Windows page opens by saying it is supported, not for a new site, and where a new site should go instead. No procedure was cut - an operator on an IIS box at 2am needs these pages to work exactly as well tomorrow. MIGRATE-TOPOLOGY stops being a footnote and becomes the off-ramp, which is why it nearly doubled: what was there did not match how the Docker stack really works here. The Docker material that already lived on this line was kept and given ownership rather than buried under the ported Windows-centric prose: DEPLOY now describes the four services, the migrate service that runs the upgrade chain before api starts, TLS terminated by nginx, and the plugin count corrected from thirteen to seventeen - a number both lineages had wrong. ROADMAP is rewritten from evidence rather than memory: what has shipped, read out of the changelog, the ADRs and the manifests, and ahead of it exactly two items - finalize a distributed release and polish the setup wizard. PROJECT-MAP is generated and was stale; the GENERATOR was what was wrong. --check passes now. API-REFERENCE is retired to a pointer. /api/docs serves 573 operations with derived auth, query parameters and harvested examples, and a hand-written page competing with that is a liability. The file stays so its wiki page and its inbound links survive. AND THE MOVE TURNED ON A SCRUB THAT HAD NEVER RUN HERE. test_docs_publishable keys on docs/*.md, which this line did not have, so it skipped - its own comment predicted what would surface. Porting the corpus activated it and it found 48 lines that must not reach a published wiki: branch names abbreviating the site, assistant-tooling paths, the site name in two deployment pages, and an employee ID in a Windows path that the scrub does not even look for.
124 lines
4.9 KiB
Markdown
124 lines
4.9 KiB
Markdown
<!-- docmeta
|
|
purpose: explanation
|
|
audience: developer, adopter
|
|
status: current
|
|
summary: How the product is versioned and released, separately from the plugin contract version.
|
|
loadwith: none
|
|
-->
|
|
|
|
# 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.
|
|
|
|
1. **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.
|
|
|
|
2. **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.
|
|
|
|
3. **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]`.
|
|
|
|
4. **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.
|
|
|
|
5. **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`:
|
|
|
|
1. Bump `__version__` in `shopdb/__init__.py` to `X.Y.Z`.
|
|
2. Bump `version` in `frontend/package.json` to the same `X.Y.Z`.
|
|
3. 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.
|
|
4. If the plugin contract surface changed this release, bump
|
|
`__contract_version__` per ADR-002 (independently of `__version__`).
|
|
5. Commit, then tag: `git tag -a vX.Y.Z -m "shopdb-flask X.Y.Z"`.
|
|
6. 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
|
|
|
|
1. **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.
|
|
2. **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.
|
|
3. **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)
|