docs: document the update prompt, the bootstrap delivery gap, and the release scripts #11

Open
jaslopena wants to merge 1 commit from docs/consent-and-self-update into main
Member

Documentation for behaviour this runbook did not describe, plus one correction.

6.2 (new) - the bootstrap never updates itself. ZZZ_AutoSetup is not a manifest entry and run_updater_async lives inside it, so a bootstrap change reaches only users who install a new installer. Rebuilding does not help existing installs either: the installer writes {app}/Mod/ZZZ_AutoSetup and nothing re-reads that path afterwards.

This is now the TL;DR's biggest delivery gap, because it decides how bootstrap work should be planned - batch related changes into one installer rather than shipping them individually. The section records the mechanism that would fix it (publish the bootstrap as a manifest asset, so the updater installs it into the user tree and it self-updates from then on) and the four prerequisites. Three are not in place: no Init.py in the folder, no version.txt, and - the one that matters - FreeCAD has never been shown to discover a workbench in the user tree. Every staged workbench so far has landed in {app}/Mod, so that must be verified before anything relies on it.

6.1 - the update prompt. One dialog per batch, nothing pending means no UI, "don't ask again" writes SkipUpdatePrompt, restart offered after applying, and no-UI degrades to the previous silent behaviour. Also notes that a locked folder stops the replace rather than the run. This is documentation for PR #10.

6.5 - corrected. It said failure reporting was swallowed wholesale. A failed update is now surfaced in the status bar, and a locked folder is named with what to do about it. Only a failed manifest fetch is still report-view-only, which is the remaining half.

5.7 (new). The contents API needs POST to create and PUT to update; PUT on a new path returns 422 [SHA]: Required, and sha: "" does not satisfy it. That cost a publish attempt and reads like a permissions problem.

4.7 (new) - publish_release.py. The scripted stable release: what it enforces (verify before writing the manifest, which is the whole point), and the two options that matter - --reuse for a stale local build, and the refuse-rather-than-overwrite behaviour on re-run. Notes that neither release script is in this repo, so a second maintainer cannot cut a release without the installer folder.

4.1 no longer claims "there is no automation" for the stable channel.

Renumbered 6.3-6.6 to 6.4-6.7 and fixed the cross-references. Fences balanced, all §refs resolve except the 5.x ones, which are bold sub-sections rather than headings.

Documentation for behaviour this runbook did not describe, plus one correction. **6.2 (new) - the bootstrap never updates itself.** `ZZZ_AutoSetup` is not a manifest entry and `run_updater_async` lives inside it, so a bootstrap change reaches only users who install a new installer. Rebuilding does not help existing installs either: the installer writes `{app}/Mod/ZZZ_AutoSetup` and nothing re-reads that path afterwards. This is now the TL;DR's *biggest delivery gap*, because it decides how bootstrap work should be planned - batch related changes into one installer rather than shipping them individually. The section records the mechanism that would fix it (publish the bootstrap as a manifest asset, so the updater installs it into the user tree and it self-updates from then on) and the four prerequisites. Three are not in place: no `Init.py` in the folder, no `version.txt`, and - the one that matters - **FreeCAD has never been shown to discover a workbench in the user tree**. Every staged workbench so far has landed in `{app}/Mod`, so that must be verified before anything relies on it. **6.1 - the update prompt.** One dialog per batch, nothing pending means no UI, "don't ask again" writes `SkipUpdatePrompt`, restart offered after applying, and no-UI degrades to the previous silent behaviour. Also notes that a locked folder stops the replace rather than the run. This is documentation for PR #10. **6.5 - corrected.** It said failure reporting was swallowed wholesale. A failed update is now surfaced in the status bar, and a locked folder is named with what to do about it. Only a failed manifest fetch is still report-view-only, which is the remaining half. **5.7 (new).** The contents API needs `POST` to create and `PUT` to update; `PUT` on a new path returns `422 [SHA]: Required`, and `sha: ""` does not satisfy it. That cost a publish attempt and reads like a permissions problem. **4.7 (new) - `publish_release.py`.** The scripted stable release: what it enforces (verify before writing the manifest, which is the whole point), and the two options that matter - `--reuse` for a stale local build, and the refuse-rather-than-overwrite behaviour on re-run. Notes that neither release script is in this repo, so a second maintainer cannot cut a release without the installer folder. **4.1** no longer claims "there is no automation" for the stable channel. Renumbered 6.3-6.6 to 6.4-6.7 and fixed the cross-references. Fences balanced, all §refs resolve except the 5.x ones, which are bold sub-sections rather than headings.
Three things this runbook did not cover, all discovered while shipping v1.0.3
and the consent-dialog work.

6.2 (new) The bootstrap never updates itself. ZZZ_AutoSetup is not a manifest
entry and run_updater_async lives inside it, so a bootstrap change reaches only
users who install a new installer -- rebuilding does not help existing installs
either, because the installer writes {app}/Mod/ZZZ_AutoSetup and nothing re-reads
that path. Recorded as the biggest delivery gap in the TL;DR, with the mechanism
that would fix it (publish the bootstrap as a manifest asset) and the four
prerequisites, three of which are not in place today. The one that matters most
is unverified: FreeCAD has never been shown to discover a workbench in the user
tree, and every staged workbench so far has landed in {app}/Mod.

6.1 Documented the update prompt: one dialog per batch, nothing pending means no
UI, 'don't ask again' writes SkipUpdatePrompt, restart offered after applying,
and no-UI degrades to the old silent behaviour. Also notes that a locked folder
stops the replace rather than the run.

6.5 Corrected. Failure reporting was 'swallowed' wholesale; a failed update is
now surfaced in the status bar and a locked folder is named. Only a failed
manifest fetch is still report-view-only.

5.7 (new) The contents API needs POST to create and PUT to update; PUT on a new
path returns 422 [SHA]: Required and sha:'' does not satisfy it. That cost a
publish attempt, and reads like a permissions problem.

4.7 (new) publish_release.py: the scripted stable release, what it enforces
(verify before writing the manifest) and the two options that matter --reuse
and re-run behaviour. Notes that neither script is in this repo.

4.1 No longer claims 'there is no automation' for the stable channel.

Renumbered 6.3-6.6 to 6.4-6.7 and fixed the cross-references.
This pull request has changes conflicting with the target branch.
  • MAINTAINING.md
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u origin docs/consent-and-self-update:docs/consent-and-self-update
git switch docs/consent-and-self-update

Merge

Merge the changes and update on Forgejo.

Warning: The "Autodetect manual merge" setting is not enabled for this repository, you will have to mark this pull request as manually merged afterwards.

git switch main
git merge --no-ff docs/consent-and-self-update
git switch docs/consent-and-self-update
git rebase main
git switch main
git merge --ff-only docs/consent-and-self-update
git switch docs/consent-and-self-update
git rebase main
git switch main
git merge --no-ff docs/consent-and-self-update
git switch main
git merge --squash docs/consent-and-self-update
git switch main
git merge --ff-only docs/consent-and-self-update
git switch main
git merge docs/consent-and-self-update
git push origin main
Sign in to join this conversation.
No reviewers
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
comfac-dist/ComfacCAD!11
No description provided.