docs: add session handoff (first-release)

2026-04-29 11:56:47 -04:00
parent 2d049437ff
commit 891cc7c1c8
1 changed files with 76 additions and 0 deletions
@@ -0,0 +1,76 @@
+# Handoff: sethLabels packaging pipeline live — first release published
+
+## Session Metadata
+- Created: 2026-04-29 15:54:39 UTC
+- Project: /home/claude/bin/sethLabels
+- Branch: main
+- Live URL: https://git.sethpc.xyz/Seth/sethLabels
+- First release: https://git.sethpc.xyz/Seth/sethLabels/releases/tag/3.99-master618-seth1
+
+### Recent Commits (for context)
+```
+2d04943 docs: refresh CLAUDE.md to post-first-release phase
+2108e2c docs: changelog for 3.99-master618-seth1
+8290870 docs: add README.sethlabels.md (fork entry point)
+9b97080 docs: add scripts/README.md (operator run guide)
+2a789e3 fix: guard batch AppImage icon path with pre-flight check
+e619699 chore: add xvfb to deps-debian.sh (required by build-appimages smoke tests)
+f7e3565 fix: prune unused binary from each AppDir before linuxdeploy bundling
+d5fb872 feat: add build-appimages.sh with inline smoke tests T3, T4
+13d4047 fix: guard rm -rf in build-deb.sh against empty BUILD_DIR
+4f2de8a feat: add build-deb.sh with inline smoke tests T1, T2
+```
+
+## Handoff Chain
+
+- **Continues from**: [2026-04-29-095534-spec-approved-pre-implementation.md](./2026-04-29-095534-spec-approved-pre-implementation.md)
+
+## Current State Summary
+
+The sethLabels packaging pipeline is fully implemented and the first tag (3.99-master618-seth1) is published to Gitea with three artifacts (1 .deb + 2 AppImages). The Homebrew tap at `git.sethpc.xyz/Seth/homebrew-tap` is bumped to point at the new tag. CLAUDE.md is refreshed. Ready for periodic releases via the spec §6 flow.
+
+## Tasks Finished
+
+- [x] All 12 tasks of the implementation plan executed end-to-end
+- [x] First .deb built and attached: glabels-qt_3.99-master618-seth1_amd64.deb (42M / 43,640,116 bytes)
+- [x] First AppImages built and attached: sethlabels-gui-3.99-master618-seth1-x86_64.AppImage (34M / 34,781,688 bytes) and sethlabels-batch-3.99-master618-seth1-x86_64.AppImage (33M / 34,404,856 bytes)
+- [x] Gitea release published at https://git.sethpc.xyz/Seth/sethLabels/releases/tag/3.99-master618-seth1 (release ID 24)
+- [x] Homebrew tap bumped to 3.99-master618-seth1 (commit 3f0451c on git.sethpc.xyz/Seth/homebrew-tap)
+- [x] CLAUDE.md refreshed for post-first-release phase (commit 2d04943)
+- [x] Three smoke tests pass: T1 (.deb info), T2 (.deb contents), T3 (batch --version), T4 (gui --help under Xvfb)
+
+## Deferred / Skipped
+
+- T5 (fresh Debian 13 VM install test) — skipped on this dry run; required before public-flip on GitHub.
+- macOS install validation — needs a Mac with brew. Formula syntax was not pre-checked because steel141 has no ruby installed. Run `brew install seth/tap/glabels-qt` on a Mac to verify.
+
+## Suggested Next Steps
+
+1. Periodic upstream rebase + new release: when upstream tags a new master version, follow the spec §6 release flow to publish a new sethLabels-N tag.
+2. T5 fresh-VM smoke test: spin up a clean Debian 13 VM, download the .deb from the release page, install with `apt install ./...`, run `glabels-qt --version`. If anything fails, the `dpkg-shlibdeps` calculation was wrong (spec §F8) — override via `CPACK_DEBIAN_PACKAGE_DEPENDS` and rebuild as -seth2.
+3. macOS validation on a real Mac — first-install path validates the formula end-to-end.
+4. Public-flip planning: when the pipeline has been battle-tested with a few releases, mirror to GitHub and add a `.github/workflows/release.yml` that calls the same scripts unmodified.
+
+## Important Context
+
+- Strict-zero (I1) is the project's defining discipline. The guardrail at `scripts/check-no-upstream-edits.sh` (with the upstream/master ref existence check added in commit 0631c55) enforces this on every build.
+- The `<upstream-tag>-seth<N>` versioning means the next release on the same upstream commit will be `<upstream-tag>-seth2`. If upstream tags a new release first, it'll be `<new-tag>-seth1`.
+- Spec discrepancy fixes applied during implementation (documented in plan header):
+  1. Added `-D CPACK_PACKAGE_NAME=glabels-qt` to build-deb.sh (spec §5.2 omitted it)
+  2. Pinned linuxdeploy/plugin-qt to dated tags (spec §F9 mandate; specific tags discovered at impl time)
+  3. Pruned each AppImage to contain only its own binary (size optimization not in spec, found via review)
+- One unanticipated detail at release time: the homebrew-tap repo's pre-commit `detect-secrets` hook flagged the git revision SHA in `Formula/glabels-qt.rb` as a high-entropy string. Resolved with an inline `# pragma: allowlist secret` comment on that line — NOT with `--no-verify`. Future tap bumps need to keep that pragma comment when replacing the SHA.
+
+## Tags now live in sethLabels
+
+```
+3.99-master618-seth1   ← first sethLabels release
+3.99-master618         ← upstream-side checkpoints (pushed during this session as a side
+3.99-master602           effect of `git push origin main --tags`; harmless, pre-existing
+3.99-master601           local tags from upstream's history)
+3.99-master598
+```
+
+---
+
+**Security Reminder**: No secrets present. Validated post-write.