Skip to content

docs: stop telling readers that status.json fixes itself #1068

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
abrichr merged 1 commit into from
Jul 28, 2026
Merged

docs: stop telling readers that status.json fixes itself #1068

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 12 additions & 2 deletions docs/platform-manifest.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -116,8 +116,18 @@ Validated today:
An unreachable PyPI warns rather than fails — it is not evidence of drift —
unless `--require-network` is passed.
- Status skew: disagreement with `status.json` versions is a warning by
default (status.json regenerates on its own cadence in `openadapt-web`);
`--strict-status` escalates it to a failure.
default, because that file lives in another repository and a release here
must not be blocked by an edit nobody in this repo can make;
`--strict-status` escalates it to a failure. The warning is **not**
self-healing: `status.json` is hand-maintained in `openadapt-web` and
nothing generates it from PyPI or from this manifest. On 2026-07-28 it
advertised flow 1.24.0 and launcher 1.10.0 against PyPI's 1.25.1 and 1.10.1.
`openadapt-web` runs a daily guard
(`scripts/check_published_version_claims.mjs`) that fails on exactly this,
but that detects after the fact and still needs a person to open the
corrective pull request. Skew reported here means someone must edit
`public/status.json` and `data/published-version-claims.json` in
`openadapt-web`.

Not validated yet (planned):

Expand Down
20 changes: 16 additions & 4 deletions scripts/validate_platform_manifest.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,8 +29,18 @@
class of check (for example in an airgapped environment).
* Status-document agreement (network): version skew against
https://openadapt.ai/status.json is reported as a WARNING by default,
because status.json is regenerated on its own cadence in openadapt-web.
Pass --strict-status to escalate the skew to a failure.
because status.json lives in another repository and this manifest is not its
source of truth. It stays a warning so a release here cannot be blocked by an
edit nobody in this repo can make. Pass --strict-status to escalate the skew
to a failure.

Do NOT read that warning as self-healing. status.json is HAND-MAINTAINED in
openadapt-web; nothing generates it from PyPI or from this manifest. On
2026-07-28 it advertised flow 1.24.0 and launcher 1.10.0 while PyPI had
1.25.1 and 1.10.1. openadapt-web runs its own daily guard
(scripts/check_published_version_claims.mjs) that fails on exactly this, but
that is after-the-fact detection and still needs a person to open the
corrective PR. Skew reported here means someone must go and edit that file.

What it does NOT validate yet (planned, see docs/platform-manifest.md):

Expand Down Expand Up @@ -395,8 +405,10 @@ def check_against_status(manifest: dict, report: Report, strict: bool) -> None:
emit(
f"{role} skew vs {STATUS_URL}: manifest has "
f"{component.get('version')!r}, status.json has "
f"{status_version!r} (status.json regenerates on its own "
"cadence in openadapt-web)"
f"{status_version!r} (status.json is hand-maintained in "
"openadapt-web and will not correct itself -- edit "
"public/status.json and data/published-version-claims.json "
"there)"
)
lifecycle = (status.get("product_lifecycle") or "").lower()
if lifecycle and lifecycle != manifest.get("release_channel"):
Expand Down