From 891cc7c1c84f76cffcbb697faeac34f0b305f69f Mon Sep 17 00:00:00 2001 From: Seth Freiberg Date: Wed, 29 Apr 2026 11:56:47 -0400 Subject: [PATCH] docs: add session handoff (first-release) --- .../2026-04-29-155439-first-release.md | 76 +++++++++++++++++++ 1 file changed, 76 insertions(+) create mode 100644 .claude/handoffs/2026-04-29-155439-first-release.md diff --git a/.claude/handoffs/2026-04-29-155439-first-release.md b/.claude/handoffs/2026-04-29-155439-first-release.md new file mode 100644 index 0000000..420b4e6 --- /dev/null +++ b/.claude/handoffs/2026-04-29-155439-first-release.md @@ -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 `-seth` versioning means the next release on the same upstream commit will be `-seth2`. If upstream tags a new release first, it'll be `-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.