Seth/sethLabels
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 1 Wiki Activity
Files
4f2de8a92cc5d0d112fb8a358b35b9b9de0f6e25
sethLabels/DECISIONS.md
T
Seth 8e272c0bd8 docs: add packaging design spec + decision log 
Captures the brainstormed design for sethLabels' packaging pipeline:
- Strict-zero source patches; all sethLabels content in NEW top-level dirs
- Linux artifacts: .deb (CPack-driven) + AppImage (linuxdeploy + Qt plugin),
  both built from upstream's existing install() rules
- macOS: Homebrew tap, build-from-source — no macOS CI, no signing,
  no Apple Developer ID
- Build infra: manual local builds during battle-test phase; shell
  scripts under scripts/ are the canonical recipe (CI YAML at the
  eventual public-flip on GitHub will call them verbatim)
- Versioning: <upstream-tag>-seth<N> for clear lineage + rebuild counter
- Package name: glabels-qt (matches binary, brew formula, command)

Spec at sethlabels-docs/specs/2026-04-29-packaging-design.md.
Decision log at DECISIONS.md.

No code introduced — design only. Plan-writing follows.
2026-04-29 09:37:56 -04:00

41 lines
6.0 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.
Reference in New Issue View Git Blame Copy Permalink