docs: add scripts/README.md (operator run guide)

2026-04-29 11:42:34 -04:00
parent 2a789e30f8
commit 9b970804fc
1 changed files with 90 additions and 0 deletions
@@ -0,0 +1,90 @@
+# sethLabels build scripts
+
+Canonical recipe for building sethLabels artifacts. CI YAML at the public-flip
+will call these scripts unmodified — no logic moves into YAML (spec §I3).
+
+## Quick reference
+
+```
+./scripts/lib/deps-debian.sh         # check / install build deps
+./scripts/check-no-upstream-edits.sh # enforce strict-zero (I1)
+./scripts/compute-version.sh         # emit <upstream-tag>-seth<N>
+./scripts/build-deb.sh               # → build/deb/glabels-qt_<VERSION>_amd64.deb
+./scripts/build-appimages.sh         # → sethlabels-{gui,batch}-<VERSION>-x86_64.AppImage
+```
+
+## Prerequisites
+
+Debian 13 (Trixie) or Ubuntu 24.04 LTS. Run:
+
+```
+./scripts/lib/deps-debian.sh
+```
+
+If anything is missing, the script prints the exact `sudo apt install ...`
+command to run.
+
+`bats` (bash test framework) is in the dep list — it's required for the
+implementation tests under `tests-impl/`.
+
+`linuxdeploy` and `linuxdeploy-plugin-qt` are NOT apt-installable; they're
+downloaded automatically by `scripts/lib/linuxdeploy.sh` to `scripts/.cache/`
+on first AppImage build.
+
+## Versioning
+
+`<upstream-tag>-seth<N>` (e.g., `3.99-master618-seth1`). The `<N>` counter is
+computed from existing git tags matching `<upstream-tag>-seth*`. See spec §D4.
+
+**Caller responsibility:** the local tag db must be fresh before running
+`compute-version.sh`. Run `git fetch origin --tags` first if you're not
+inside the release flow (which fetches tags as step 1).
+
+## Release flow
+
+See spec §6 for the canonical step-by-step. TL;DR:
+
+```
+git fetch --all --tags
+git rebase upstream/master
+./scripts/check-no-upstream-edits.sh
+./scripts/build-deb.sh                       # ~2 min
+./scripts/build-appimages.sh                 # ~5 min
+VERSION=$(./scripts/compute-version.sh)
+git tag "$VERSION"
+git push origin main --tags
+# Create Gitea release for $VERSION; attach the three artifacts.
+# Bump ../homebrew-tap/Formula/glabels-qt.rb (tag + revision); commit; push.
+# Smoke verify on a clean Debian 13 VM (T5).
+```
+
+## Layout
+
+```
+scripts/
+├── README.md                     ← this file
+├── compute-version.sh            ← pure logic; emits version string
+├── check-no-upstream-edits.sh    ← guardrail enforcing I1
+├── build-deb.sh                  ← end-to-end .deb pipeline
+├── build-appimages.sh            ← end-to-end AppImage pipeline (GUI + batch)
+├── lib/
+│   ├── deps-debian.sh            ← build-dep manifest + checker
+│   └── linuxdeploy.sh            ← linuxdeploy + plugin-qt bootstrapper
+└── .cache/                       ← gitignored; linuxdeploy AppImages cache
+```
+
+## Tests
+
+```
+./tests-impl/run-all.sh
+```
+
+Runs the bats suite for pure-logic scripts. Build-script smoke tests (T1–T4)
+are inline in `build-deb.sh` and `build-appimages.sh` — they fire automatically
+on each build.
+
+## Spec
+
+The design rationale, invariants, and failure modes live in
+[`../sethlabels-docs/specs/2026-04-29-packaging-design.md`](../sethlabels-docs/specs/2026-04-29-packaging-design.md).
+Read it before changing any script.