sethLabels/DECISIONS.md

DECISIONS.md — sethLabels Decision Log

Project-specific decisions. For global/cross-cutting decisions, see ~/bin/DECISIONS.md.

Format: YYYY-MM-DD: <decision> — <why>

Architecture

• 2026-04-29: Strict-zero source patches. Never edit any upstream-tracked file. All sethLabels content lives in new files in new top-level directories at the repo root. — Makes git pull upstream master --ff-only succeed forever; rebase friction = 0. Allowlist exception: .gitignore (one-time scaffold-time touch). Enforced by scripts/check-no-upstream-edits.sh. See spec §I1, §D5.
• 2026-04-29: Eventual-public fork. sethLabels stays on Gitea during battle-test, then promotes to a formally public fork on GitHub once the build/release pipeline is solid. — Drives spec invariants: build host must be a clean Debian 13 / Ubuntu LTS box (not steel141-specific); brew tap source URL must be cleanly flippable Gitea→GitHub; CI is added at the flip, not before.
• 2026-04-29: Linux artifacts = .deb + AppImage; macOS via Homebrew tap (build from source). — .deb for Debian-family install ergonomics, AppImage for portability to non-Debian Linux. Brew tap eliminates macOS CI/signing/$99 Apple Dev ID entirely; users' Macs build from source. See spec §D1, §D2.
• 2026-04-29: Build infrastructure = manual local builds during battle-test. Shell scripts under scripts/ are the canonical build recipe; CI YAML at the public-flip will call those scripts unmodified. — Local feedback loop beats CI loop during iteration on packaging. Defers infra cost. See spec §I3, §D3.
• 2026-04-29: Versioning = <upstream-tag>-seth<N>. E.g., 3.99-master618-seth1. — Lineage-preserving; rebuild counter survives packaging-only fixes; sorts correctly under dpkg --compare-versions. See spec §D4.
• 2026-04-29: Package name = glabels-qt. Same name as upstream binary, brew formula, and the command users run. — sethLabels identity lives at repo level + version-string -seth<N> marker, not in the package name. Avoids confusing identity-split between package name and binary name. See spec §D6.

Implementation

• 2026-04-29: macOS = no CI required. Homebrew tap with build-from-source means no macOS runner, no Apple Developer ID, no notarization pipeline. Tap repo (git.sethpc.xyz/Seth/homebrew-tap) is one ~30-line Ruby file. — Major simplification; Mac users build locally on first install (~5–10 min), all subsequent installs are version pin bumps to the tap formula.
• 2026-04-29: Debian-family is the install target, not steel141. Build host happens to be steel141 (or any clean Debian/Ubuntu box); install target is generic Debian-family. — No homelab paths, hostnames, or assumptions in scripts. Reproducibility on a fresh VM is the bar.
• 2026-04-29: Spec, scripts, and packaging metadata live in NEW top-level dirs. sethlabels-docs/, scripts/, packaging/. NOT in upstream's docs/ directory. — Clear fork boundary; preserves strict-zero spirit (don't pollute upstream namespaces with our content).
• 2026-04-29: macOS Launchpad/Spotlight integration via stub .app wrapper generated in brew formula. Formula's def install synthesizes glabels-qt.app/Contents/{Info.plist, MacOS/launcher, Resources/glabels-qt.icns} after cmake --install. Launcher is a 2-line shell that execs the real CLI binary. Icon converted from upstream's SVG via sips. User runs a one-time cp -R "$(brew --prefix glabels-qt)/glabels-qt.app" /Applications/ (caveats block reminds them). — Upstream's add_executable(glabels-qt WIN32 ...) has no MACOSX_BUNDLE keyword, so cmake produces a CLI-only Mach-O on macOS. Strict-zero forbids patching upstream to fix this. The brew-formula-side stub is the cleanest sethLabels-side workaround; no Apple Developer ID, no signing pipeline, no .dmg. Tap commits ef4d6c7 (initial wrapper) + 3542762 (SVG glob fix).

Deferred / Rejected

• Rejected 2026-04-29: AppImage-only Linux distribution. — Loses native Debian package manager integration (apt remove, dependency tracking) on the primary target distros.
• Rejected 2026-04-29: .deb-only Linux distribution. — Loses portability to non-Debian Linux (RHEL/Fedora/Arch users couldn't install without recompiling).
• Rejected 2026-04-29: Flatpak. — Sandbox runtime requirement + manifest complexity overkill for a personal-use packaging fork.
• Rejected 2026-04-29: Signed + notarized macOS .dmg (Apple Developer ID). — $99/year recurring + notarization CI complexity not justified for a build-from-source Homebrew alternative.
• Rejected 2026-04-29: Unsigned macOS .dmg. — Gatekeeper friction (right-click → Open) is a poor first-run experience compared to brew install.
• Rejected 2026-04-29: Gitea Actions self-hosted runner during battle-test. — Homelab CT spin-up + workflow YAML setup not justified before public-flip; manual builds are faster to iterate on.
• Rejected 2026-04-29: Public GitHub Actions from day one. — Skips the "battle-test in private" intent; want to validate the pipeline before going public.
• Rejected 2026-04-29: Plain upstream-tag versioning (no -seth<N> marker). — No way to distinguish v1 of the .deb from v2 after a packaging fix; would have to lie about which upstream commit the package contains.
• Rejected 2026-04-29: Independent semver (0.1.0, 0.2.0). — Loses upstream-lineage info from the version string; users couldn't tell which glabels-qt commit they have without checking the changelog.
• Rejected 2026-04-29: Date-based versioning (2026.04.29). — Loses both upstream-lineage and rebuild-counter information.
• Rejected 2026-04-29: Permissive small-patches policy on upstream files. — Creates rebase friction on each git pull upstream master; even a one-file CMakeLists carve-out turned out to be unnecessary since CPack -D flags cover all needed metadata at build time.
• Rejected 2026-04-29: Package name sethlabels. — Strict-zero policy forbids renaming the executable, so apt install sethlabels then running glabels-qt would split package identity from binary identity. Confusing.
• Deferred: Windows packaging. — Per project brief. Upstream's NSIS support is intact; can be revisited later. Not blocking macOS+Linux delivery.
• Deferred: Custom default templates baked into the package. — Strict-zero forbids; user-specific templates can live in ~/.config/glabels-qt/templates/ or a separate repo if/when needed.
• Deferred: Branding, icon, splash, or string changes. — Strict-zero forbids. sethLabels is a packaging fork, not a rebrand.
• Deferred: Distribution to Debian backports / PPA / Ubuntu universe. — Requires Debian Developer mentorship + ongoing policy compliance work; not justified for current scope.