[#5] Add MAINTAINING.md - public distribution runbook for maintainers #6

Open
justin wants to merge 1 commit from docs/5-public-distribution-runbook into main
Owner

Closes #5

What this adds

MAINTAINING.md — the maintainer runbook for the public workbench distribution.

Documentation only; no behaviour change.

Why it is needed

Nothing about this setup is self-evident from the code or the Forgejo UI. In particular:

  • internal visibility is derived, not a setting — the settings page shows a Private
    checkbox that was already unchecked while the repo was unreachable. Anyone who looks at
    the UI will conclude nothing is wrong.
  • A PATCH that returns HTTP 200 can change nothing at all.
  • Moving this repo back to cgg silently breaks public access with no error visible
    anywhere in the UI.
  • releases/latest/download/... does not work on this instance.

Each of those cost real time to establish. Without a written record they get re-derived.

Contents

Section
§1 Why the repo is at comfac-dist and must not move back
§2 Current state
§3 End-to-end flow
§4 Routine jobs: ship an update, add/remove a workbench, manage access, roll back
§5 Traps, each verified against this instance
§6 Known gaps
§7 Verification commands

Reviewer note

§6.1 is the one to read even if nothing else: the updater installs missing workbenches
only and never updates existing installs
— the version field in manifest.json is
never read. Publishing a new release therefore reaches new users only. That is the
highest-value follow-up work and is deliberately flagged rather than quietly fixed here.

Deliberately free of internal filesystem paths and credential locations, since this
repository is public.

Closes #5 ## What this adds `MAINTAINING.md` — the maintainer runbook for the public workbench distribution. Documentation only; no behaviour change. ## Why it is needed Nothing about this setup is self-evident from the code or the Forgejo UI. In particular: - **`internal` visibility is derived**, not a setting — the settings page shows a *Private* checkbox that was already unchecked while the repo was unreachable. Anyone who looks at the UI will conclude nothing is wrong. - A `PATCH` that returns **HTTP 200** can change nothing at all. - **Moving this repo back to `cgg` silently breaks public access** with no error visible anywhere in the UI. - `releases/latest/download/...` **does not work** on this instance. Each of those cost real time to establish. Without a written record they get re-derived. ## Contents | Section | | |---|---| | §1 | Why the repo is at `comfac-dist` and must not move back | | §2 | Current state | | §3 | End-to-end flow | | §4 | Routine jobs: ship an update, add/remove a workbench, manage access, roll back | | §5 | Traps, each verified against this instance | | §6 | Known gaps | | §7 | Verification commands | ## Reviewer note §6.1 is the one to read even if nothing else: **the updater installs missing workbenches only and never updates existing installs** — the `version` field in `manifest.json` is never read. Publishing a new release therefore reaches new users only. That is the highest-value follow-up work and is deliberately flagged rather than quietly fixed here. Deliberately free of internal filesystem paths and credential locations, since this repository is public.
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/5-public-distribution-runbook:docs/5-public-distribution-runbook
git switch docs/5-public-distribution-runbook

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/5-public-distribution-runbook
git switch docs/5-public-distribution-runbook
git rebase main
git switch main
git merge --ff-only docs/5-public-distribution-runbook
git switch docs/5-public-distribution-runbook
git rebase main
git switch main
git merge --no-ff docs/5-public-distribution-runbook
git switch main
git merge --squash docs/5-public-distribution-runbook
git switch main
git merge --ff-only docs/5-public-distribution-runbook
git switch main
git merge docs/5-public-distribution-runbook
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!6
No description provided.