chore: add sethLabels deployment-fork scaffold
Adds Seth's homelab convention files on top of upstream glabels-qt master: CLAUDE.md (project instructions), IDEA.md (brief), DECISIONS.md (decision log, empty), and the kickoff handoff under .claude/handoffs/. Appends a clearly-marked sethLabels section to .gitignore for .backup/, the GITEA_API.md symlink, .env files, and handoff drafts. This is the only non-upstream commit on main. All preceding history is authored by the glabels.org team (Jaye Evins et al.) and untouched. Future upstream merges should fast-forward or rebase cleanly since the scaffold lives in distinct files at repo root. No source-code changes. License unchanged (GPL-3.0).
This commit is contained in:
@@ -0,0 +1,73 @@
|
||||
# Handoff: sethLabels scaffolded — no code yet
|
||||
|
||||
## Session Metadata
|
||||
|
||||
- Created: 2026-04-29 12:58:23 UTC
|
||||
- Project: /home/claude/bin/sethLabels
|
||||
- Branch: n/a (no git repo yet)
|
||||
- Session duration: ~5 min
|
||||
- Live URL: n/a
|
||||
|
||||
## Handoff Chain
|
||||
|
||||
- **Continues from:** None — this is the project's first handoff.
|
||||
- **Supersedes:** None.
|
||||
|
||||
## Current State Summary
|
||||
|
||||
Project directory scaffolded per `~/bin/CREATE_PROJECT.md` as a deployment fork of upstream [glabels-qt](https://github.com/j-evins/glabels-qt). No code has been pulled, no git repo initialized, no Gitea repo created. Only the `~/bin/`-convention files exist:
|
||||
|
||||
```
|
||||
sethLabels/
|
||||
├── CLAUDE.md durable project instructions
|
||||
├── DECISIONS.md empty decision log (template-derived, header set)
|
||||
├── GITEA_API.md symlink → ~/bin/GITEA_API.md
|
||||
├── IDEA.md plain-language brief
|
||||
└── .claude/handoffs/
|
||||
└── 2026-04-29-125823-scaffold-only.md (this file)
|
||||
```
|
||||
|
||||
Phase: **ideation**. Nothing is running anywhere. No upstream commit pinned. No build attempted.
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
This is a *deployment fork* — the discipline is to keep the diff against `j-evins/glabels-qt` master surgical so we can rebase periodically without pain. Anything we add should be additive (new files: deploy scripts, packaging recipes, Seth-specific templates) rather than invasive edits to upstream source. If we need to patch upstream code, prefer a thin patch series we can replay.
|
||||
|
||||
Stack is Qt + CMake + C++ (GPL-3.0). Target host is **steel141** (Debian 13). A future option is a headless print-server CT, but that's not part of this scaffold's scope.
|
||||
|
||||
## Critical Files
|
||||
|
||||
| File | Purpose | Relevance |
|
||||
|------|---------|-----------|
|
||||
| `~/bin/sethLabels/IDEA.md` | Plain-language brief — why this fork exists | Read first if upstream choice or scope feels unclear |
|
||||
| `~/bin/sethLabels/CLAUDE.md` | Durable project instructions | Loaded every session |
|
||||
| `~/bin/sethLabels/DECISIONS.md` | Empty — populate as architectural choices land | Write to when locking in upstream-pin strategy, Qt5-vs-Qt6, etc. |
|
||||
| `~/bin/CREATE_PROJECT.md` | Recipe used to scaffold this | Reference if future projects need the same shape |
|
||||
|
||||
## Suggested Next Steps (ordered)
|
||||
|
||||
The user said *just scaffold + handoff* — none of this was attempted. Pick up here next session:
|
||||
|
||||
1. **Decide upstream-tracking strategy.** Options:
|
||||
- (a) Clone `j-evins/glabels-qt` into this dir, push to Gitea as `sethLabels`, add upstream as a remote, merge from `upstream/master` periodically.
|
||||
- (b) Keep upstream as a git submodule and layer deployment glue around it.
|
||||
Record the choice in `DECISIONS.md` before pulling code.
|
||||
2. **Verify upstream is alive.** Check `j-evins/glabels-qt` for last commit date + open issues; this is a fork of mate-desktop's glabels lineage and forks-of-forks have a tendency to bitrot. If `j-evins` is stale, the real upstream might be elsewhere — re-evaluate before forking.
|
||||
3. **Confirm Qt version.** Upstream's `CMakeLists.txt` will say Qt5 or Qt6. Debian 13 ships both — pick whichever upstream targets.
|
||||
4. **Build it once on steel141** to establish the known-good build recipe. Capture exact `apt install` deps and CMake invocation in a `BUILD.md` (or in `CLAUDE.md` if short).
|
||||
5. **Initialize git + push to Gitea.** `gitea create sethLabels` → `gitea remote sethLabels` → `gitea push`. Use a descriptive commit message like `init: scaffold + import upstream glabels-qt @ <sha>`.
|
||||
6. **Only then** start any deployment-specific work (templates, packaging, install scripts).
|
||||
|
||||
## Open Questions
|
||||
|
||||
- Is `j-evins/glabels-qt` actually the right upstream, or should we be tracking a different fork? (See "verify upstream is alive" above.)
|
||||
- Does Seth want a `.deb` package, an AppImage, or just a built binary in `/usr/local/bin`?
|
||||
- Is there a printer model or label-stock library we should pre-load as default templates?
|
||||
|
||||
These don't block scaffolding — they block the *first real coding session*. Ask before implementing.
|
||||
|
||||
## Risks / Watch-outs
|
||||
|
||||
- Upstream is GPL-3.0. Any code we add that links against it must also be GPL-3.0-compatible. Don't accidentally relicense.
|
||||
- "Deployment fork" failure mode: scope creep into a real fork. If we find ourselves writing >100 lines of upstream-source patches, that's a signal to either upstream the change or rethink whether we actually want a fork.
|
||||
- glabels-qt is one of those projects with multiple competing forks (j-evins, jimevins-original, mate-desktop's glabels-3, etc.). Pin the upstream we choose explicitly in `DECISIONS.md` so we don't drift.
|
||||
+13
@@ -40,3 +40,16 @@ TEST-DATA
|
||||
SAV*
|
||||
OLD*
|
||||
|
||||
# === sethLabels (deployment fork) additions ===
|
||||
# Local backup snapshots (per ~/.claude/CLAUDE.md safety rule)
|
||||
.backup/
|
||||
|
||||
# Local-only symlink to ~/bin/GITEA_API.md (target is outside the repo)
|
||||
GITEA_API.md
|
||||
|
||||
# Secrets / env
|
||||
.env
|
||||
.env.*
|
||||
|
||||
# Handoff drafts (operator scratch — final handoffs ARE committed)
|
||||
.claude/handoffs/*.draft.md
|
||||
|
||||
@@ -0,0 +1,27 @@
|
||||
# sethLabels
|
||||
|
||||
> Deployment fork of glabels-qt — Qt label designer/printer, packaged for Seth's homelab.
|
||||
|
||||
## Start Here
|
||||
|
||||
**Read the latest handoff first:** `.claude/handoffs/` (most recent file).
|
||||
It has session state, in-progress work, and ordered next steps.
|
||||
|
||||
Then check `IDEA.md` for the project brief and `DECISIONS.md` for settled choices.
|
||||
|
||||
## Project Identity
|
||||
|
||||
sethLabels is a thin deployment fork of [glabels-qt](https://github.com/j-evins/glabels-qt). Upstream is the real project — this fork's job is to keep a known-good build recipe, any deployment glue (packaging, install paths, default templates), and any local patches in one place, while staying close enough to upstream `master` that periodic rebases stay cheap.
|
||||
|
||||
## Current State
|
||||
|
||||
- **Phase:** ideation (just scaffolded — no code, no upstream pull yet)
|
||||
- **Repo:** not yet (will live at `git.sethpc.xyz/Seth/sethLabels` once first commit lands)
|
||||
- **Deploy target:** steel141 (Debian 13) — primary; CT for headless print serving optional/later
|
||||
- **Upstream:** https://github.com/j-evins/glabels-qt (GPL-3.0, Qt + CMake + C++)
|
||||
|
||||
## Conventions
|
||||
|
||||
- This is a **fork**, not a from-scratch rewrite. Pull upstream first; only patch what we need to change. Keep diffs surgical.
|
||||
- Preserve upstream license (GPL-3.0) and copyright headers.
|
||||
- See `~/bin/CLAUDE.md` for global homelab conventions (gitea CLI, conventional commits, credentials handling).
|
||||
@@ -0,0 +1,12 @@
|
||||
# DECISIONS.md — sethLabels Decision Log
|
||||
|
||||
Project-specific decisions. For global/cross-cutting decisions, see `~/bin/DECISIONS.md`.
|
||||
|
||||
Format: `YYYY-MM-DD: <decision> — <why>`
|
||||
|
||||
## Architecture
|
||||
|
||||
## Implementation
|
||||
|
||||
## Deferred / Rejected
|
||||
<!-- Decisions NOT to do something are just as valuable -- prevents re-proposing rejected ideas -->
|
||||
@@ -0,0 +1,20 @@
|
||||
# IDEA.md — Project Idea
|
||||
|
||||
## What is this?
|
||||
|
||||
sethLabels is a deployment fork of [glabels-qt](https://github.com/j-evins/glabels-qt) — a Qt-based desktop application for designing and printing labels, business cards, and similar small-format documents (with CSV mail-merge and barcode support).
|
||||
|
||||
The fork exists to layer Seth's deployment-specific concerns (packaging, install paths, default templates, branding, any local patches) on top of upstream without forking the whole project lifecycle. Goal is to keep the diff small enough to rebase onto upstream `master` periodically.
|
||||
|
||||
## Problem it solves
|
||||
|
||||
Need a reliable, scriptable label designer/printer for homelab + household use (shipping labels, equipment tags, drive labels for the tank pool, cable labels, etc.). Upstream glabels-qt is solid but has no published Debian 13 / current-Ubuntu binaries and the build needs some hand-holding. This fork bakes a known-good build recipe + any local templates + deployment scripts into one repo.
|
||||
|
||||
## Constraints / preferences
|
||||
|
||||
- **Upstream:** https://github.com/j-evins/glabels-qt (track this, don't drift)
|
||||
- **Stack:** Qt (5 or 6 — TBD based on upstream's current state), CMake, C++
|
||||
- **Target hosts:** steel141 primarily (Debian 13). Maybe a CT for headless print serving later.
|
||||
- **Branding/customization:** minimal — this is for personal use, not a product
|
||||
- **License:** glabels-qt is GPL-3.0 — preserve it; any contributions stay GPL-3.0
|
||||
- **Repo:** Gitea at `git.sethpc.xyz/Seth/sethLabels` (TBD until first push)
|
||||
Reference in New Issue
Block a user