# 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).

## Deferred / Rejected
<!-- Decisions NOT to do something are just as valuable -- prevents re-proposing rejected ideas -->

- **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.