ge-aerospace/shopdb-flask
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: stop typing versions the code already knows

Browse Source 
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.
This commit is contained in:
cproudlock
2026-08-14 15:41:27 -04:00
parent 4995456136
commit d1ba3a1a02
8 changed files with 153 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
docs/PLUGIN-EXTERNAL-REPO.md
View File

@@ -109,20 +109,22 @@ the contract, and this project uses that latitude (see the history in
[CONTRACT-STABILITY.md](CONTRACT-STABILITY.md)). So pin a TIGHT range that
admits only the contract minor you tested against, not the whole 0.x line.
The current contract version is declared in `shopdb/__init__.py`:
The current contract version is declared in `shopdb/__init__.py` as
`__contract_version__`, and is reported in
[PROJECT-MAP.md](PROJECT-MAP.md), which is generated from the code. Read it
there - a version typed into this page is wrong within a fortnight, and a
plugin pinned to a stale one is refused at startup.
```python
__contract_version__ = '0.13.0'
```
Recommended pin in your `manifest.json`, per ADR-002 (pip-style `>=,<` ranges):
Pin a tight range in your `manifest.json`, per ADR-002 (pip-style `>=,<`),
admitting only the contract minor you tested against. With the contract at
0.19.0 that would be:
```json
{
"name": "shipping",
"version": "1.0.0",
"description": "Tracks shipping-station scanners and label printers",
"core_version": ">=0.13.0,<0.14.0",
"core_version": ">=0.19.0,<0.20.0",
"dependencies": []
}
```