Skip to content

Bring the docs back in line with what the checkout does - #17

Open
owenpkent wants to merge 2 commits into
sbom-and-licencesfrom
docs-sweep
Open

owenpkent wants to merge 2 commits into
sbom-and-licencesfrom
docs-sweep

Conversation

@owenpkent

Copy link
Copy Markdown
Owner

Summary

A sweep after the update client, the candidate workflow and the bill of materials. Every change is either a claim that had stopped being true, or something the checkout does that nothing documented. Docs only; no code touched.

Claims that were actively wrong

Both falsified by #16:

  • build-windows.md: the build inventories are "not a complete third-party license inventory or SBOM"
  • build-windows.md: "A release-ready third-party license inventory and SBOM remain separate work"

And in release-plan.md, the in-app check was still described as deferred after #15 shipped it.

One that needed splitting rather than deleting

The scope freeze listed "auto-update" flatly. That is now misleading in both directions, so it reads:

Updating is inside the freeze only as far as it goes today: the check is automatic, and installing never is. Nothing is downloaded, replaced or restarted without someone asking for it, and a silent background update stays out of scope.

More useful than either "deferred" or silence, and it holds the line that matters.

Gaps where the code had no documentation

  • README listed update in the commands table and explained it nowhere. It now has a section: what is verified before anything runs, and that an update never closes a running Offloader — the guarantee, not a limitation. docs/updates.md added to the documentation index.
  • The agent guide's code map listed none of the installation or update modules, so finding where maintenance lives meant grepping. It now names installation.py, installation_lock.py, update.py and gui/updates.py together with the rule binding them: neither may force-close a running transfer. Its start-here list points at build-windows.md and updates.md, and states that a build being implemented is not a release being possible — the distinction the plan keeps having to restate.
  • ROADMAP still listed "Windows installer and code signing" as future work when the packaging is implemented. Replaced with what is actually left, none of which is code: the hardware token, a clean machine, and the Qt LGPL/GPL redistribution decision the notices file flags on every build.

Validation record

Added a dated source-validation entry (855 passed, 12 skipped, lint clean, sdist checked), labelled as exactly that: nothing was frozen, signed or installed, so it establishes none of the gates it sits above. Per AGENTS.md, counts come from an actual run and a source run is not bundle qualification.

Scope note

shellicon.py, shellmenu.py and gui/file_list.py are not in the code map here, because they exist only on the other stack (#11, #12). Documenting them on this branch would describe modules the branch does not contain. They need their own sweep on that stack — happy to do it, but it has to be a separate PR or the two conflict.

Checked, not assumed

  • All 68 relative links across the markdown docs resolve
  • Every CLI subcommand (offload, report, verify, info, gui, update, resolve, control) appears in the commands table
  • Every --flag of offload is mentioned in the README
  • No remaining "deferred / separate work / not implemented" claims about anything now implemented; the two that remain (release qualification pending, destination coordination unimplemented) are both accurate
  • Diff is documentation only

A sweep after the update client, the candidate workflow and the bill of
materials landed. Every change here is either a claim that had stopped being
true or a thing the checkout does that nothing documented.

Two statements were actively wrong, both falsified by the SBOM work: that the
build inventories are "not a complete third-party license inventory or SBOM",
and that a release-ready inventory and SBOM "remain separate work". The
release plan still said the in-app check was deferred, and its scope freeze
still listed auto-update flatly. That one needed splitting rather than
deleting: the check is automatic, installing never is, and a silent
background update is still out of scope, which is a more useful sentence than
either "deferred" or nothing.

The README listed `update` in the commands table and explained it nowhere. It
now has a section covering what is verified before anything runs and, more
importantly, that an update never closes a running Offloader, which is the
guarantee rather than a limitation. The documentation index gains updates.md.

The agent guide's code map listed none of the installation or update modules,
so a reader looking for where maintenance lives had to grep. It now names
installation.py, installation_lock.py, update.py and gui/updates.py together
with the rule that binds them: neither may force-close a running transfer.
Its start-here list points at build-windows.md and updates.md, and says that
a build being implemented is not a release being possible, since that is the
distinction the plan keeps having to restate.

The roadmap still listed a Windows installer and code signing as future work
when the packaging is implemented. Replaced with what is actually left, none
of which is code: the hardware token, a clean machine, and the Qt LGPL/GPL
decision the notices file flags on every build.

Added a dated source-validation record, labelled as exactly that. Nothing was
frozen, signed or installed in it, so it establishes none of the gates it sits
above.

Checked rather than assumed: all 68 relative links across the markdown docs
resolve, every CLI subcommand appears in the commands table, and every
`offload` flag is mentioned in the README.

@owenpkent owenpkent left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed the five documentation changes against the implementation in this head, including Windows build/release status, updater behavior, profile/media-tool boundaries, and the stated safety limits.

No independent non-sensitive code defect is introduced by this documentation-only diff. One newly repeated updater-protection claim needs to wait for the underlying correction identified on #13; its exact claim and call-path evidence are included in the private updater/documentation notes under SECURITY.md.

Validation: static documentation/code consistency review and git diff --check, which passed. Recorded CI is green. No local test suite was rerun for this documentation-only review, and the review does not treat implemented packaging scripts as evidence that signing or clean-machine qualification has passed.

…ring

This branch exists to make the docs describe the checkout, and one of the
claims it added does not. README, the release plan and updates.md all present
"offloader update finds a release" as working, and the version ordering
section explains at length that prereleases are ordered rather than rejected.
The endpoint underneath is /releases/latest, which GitHub documents as
returning the newest published full release and excluding prereleases. The
first packaged release is planned as 0.1.0b1, so an installed beta cannot
discover its successor, and a repository holding only the betas the candidate
workflow publishes with --prerelease answers with nothing at all.

The ordering is right; the endpoint is wrong. All three places now say so and
point at the correction pending on #13, and the release plan no longer counts
discovery as a gate that can be signed off. Nothing here claims the fix: it
states the limit as the checkout currently has it, which is what this branch
is for.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant