diff --git a/CLAUDE.md b/CLAUDE.md index c32a9c0..bfd358d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -166,6 +166,17 @@ Key invariants in the code: until it settles. The ADR-0000 index-upkeep rule applies: every ADR change updates `docs/adr/README.md` in the same edit. +- **Issue tracking.** Bugs and enhancements are filed as Gitea + issues (see *Issue tracking — Gitea via `tea`* below). + `docs/requirements.md` and the ADRs remain the source of truth + for **scope and decisions**; issues are the lightweight tracker + for **discrete work items**, cross-referenced from commits and + handoffs (e.g. `fix: … (#12)`). The project is near completion + of its initial requirements, so no heavyweight planning workflow + is run — the document-based requirements are augmented with + issue references as work proceeds. A change that touches a + *decided* area still earns an ADR; the issue references the ADR, + it does not replace it. - **Testing.** Per the user's global standards, tests are established before changes, bugs are reproduced with failing tests before being fixed, and "all green, no skips" is the @@ -190,6 +201,64 @@ Key invariants in the code: `git commit` is preceded by an explicit message proposal and user approval. No AI attribution in commit messages. +## Issue tracking — Gitea via `tea` + +Extends (does not replace) the generic Gitea/`tea` safety rules in +the global `CLAUDE.md`. Use `tea` to manage Gitea issues; `tea +--help`, `tea issues --help`, etc. for command reference. + +**Repo coordinates.** This repo lives on the self-hosted Gitea at +`git.lazyeval.net` as `oli/rdbms-playground`. `tea` **auto-detects +it correctly off the git remote** — verified — so plain `tea issues` +works here even though the machine's *default* `tea` login is a +different host (`git.oliversturm.com`). Pass `--login +git.lazyeval.net --repo oli/rdbms-playground` only as a fallback if +auto-detection ever slips. **Never** fall back to raw API calls +(`curl`/`fetch`) when `tea` misbehaves — tokens leak into shell +history; fix `tea` instead (usually `--login`/`--repo`). + +**Labels.** Preconfigured (`bug`, `enhancement` are in use). +**Ask the user before creating new labels.** Create with `tea +labels create --name --color --description `. + +### Critical gotchas + +- **`tea` blocks on stdin in a non-TTY → hangs.** `tea comment`, + `tea issue … --comments`, and similar **wait on stdin** when not + attached to a terminal, so they hang silently. **Always append + `< /dev/null`**, and wrap in `timeout 30` as a safety net: + `timeout 30 tea comment "$body" < /dev/null`. Verify the + write landed afterwards (re-fetch); don't trust a clean exit alone. +- **Multi-line comment / description bodies**: heredocs do **not** + work with `--description` / the comment-body arg. Write the + markdown to a temp file and pass it via shell substitution: `tea + comment "$(cat /tmp/body.md)" < /dev/null` (same for `tea + issues edit --description "$(cat …)"`). +- **Read an issue's RAW body** (for editing): the default/`--output + yaml` view is a lossy rendered box. Use JSON: `tea issue + --fields body --output json < /dev/null | jq -r '.body'`. **`tea + issues edit --description` replaces the WHOLE body** — splice + surgically and keep the raw backup before applying. +- **Reopen**: use `tea issues reopen `, NOT `tea issues edit + --state open`. +- **Milestones** (not currently used here, but if introduced): set + with `tea issues edit --milestone "" ` (empty string + clears it). **Options MUST precede the ``** — flag-after-index + silently no-ops. The `tea issues create --milestone …` flag is + **unreliable** — set the milestone with a follow-up `edit` and + verify. +- **Display blind-spot — don't loop on this.** `tea issue + --fields milestone` and `--fields comments` render `None`/`0` + **even when set** — they are NOT a source of truth. Confirm a + **milestone** via the filtered list (`tea issues list --milestones + "" --limit 100 | grep `; presence = set); confirm a + **posted comment** via `tea issue --comments` (NOT the + `comments` count field). Labels/state/title DO render correctly on + the single-issue fetch; only milestone + comments don't. +- **Pagination**: default ~50 issues. Use `--limit 100` (or more) + for full lists; `--state all` to include closed; `--output + tsv`/`json` for parseable output. + ## Build hygiene `target/` is git-ignored and 100% regenerable, but it grows diff --git a/Cargo.toml b/Cargo.toml index b11af84..f3b74d9 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -4,7 +4,7 @@ version = "0.1.0" edition = "2024" description = "A cross-platform TUI playground for learning relational databases." license = "MIT OR Apache-2.0" -repository = "https://github.com/sturm/rdbms-playground" +repository = "https://git.lazyeval.net/oli/rdbms-playground" readme = "README.md" publish = false diff --git a/docs/adr/0001-language-and-tui-framework.md b/docs/adr/0001-language-and-tui-framework.md index 3832f08..69f66a9 100644 --- a/docs/adr/0001-language-and-tui-framework.md +++ b/docs/adr/0001-language-and-tui-framework.md @@ -45,3 +45,25 @@ package managers (`cargo binstall`, Homebrew, Scoop, `winget`). - TUI styling will require explicit work to match the polish that Bubble Tea / Lipgloss give for free; budget for it in the design pass. + +## Amendment 1 — Distribution channel is open after the Gitea migration (2026-06-09) + +The *Decision* block above assumed prebuilt binaries would ship "via +GitHub releases plus package managers." Since then the repository has +been migrated off GitHub to a self-hosted Gitea instance +(`git.lazyeval.net/oli/rdbms-playground`), and `tea` is the forge CLI +in use. The "GitHub releases" half of that sentence is therefore no +longer a settled assumption. + +This amendment does **not** pick a replacement. Binary distribution is +not built yet (no release pipeline, no CI — `requirements.md` TT5/E* +remain open), so the channel for prebuilt binaries is an **open +choice** — Gitea releases, a GitHub mirror's releases, or both — to be +settled by a dedicated ADR when distribution is actually implemented. +The package-manager channels named in the Decision (`cargo binstall`, +Homebrew, Scoop, `winget`) are independent of the forge and are +unaffected. + +(For the same supersede-don't-rewrite reason, the Decision block also +still names `sqlparser-rs`, which ADRs 0030–0036 replaced with a +hand-rolled grammar; that is recorded there, not by editing this ADR.) diff --git a/docs/adr/README.md b/docs/adr/README.md index 15b4537..055f0d6 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -6,7 +6,7 @@ This directory contains the project's ADRs, recorded per ## Index - [ADR-0000 — Record architecture decisions](0000-record-architecture-decisions.md) -- [ADR-0001 — Language and TUI framework](0001-language-and-tui-framework.md) +- [ADR-0001 — Language and TUI framework](0001-language-and-tui-framework.md) — **Amendment 1 (2026-06-09)**: after the GitHub→Gitea migration (`git.lazyeval.net`), the prebuilt-binary distribution channel named in the Decision ("GitHub releases") is reopened as an undecided choice, to be settled by a future distribution ADR; package-manager channels unaffected - [ADR-0002 — Database engine](0002-database-engine.md) - [ADR-0003 — Input modes and command dispatch](0003-input-modes-and-command-dispatch.md) — the persistent `Simple`/`Advanced` mode and the `:` one-shot escape. The **startup mode is no longer always `simple`**: it is restored from the project's stored mode and overridable with `--mode` (see **ADR-0015 Amendment 1**, issue #14). The app-command registry gains **`copy`** (ADR-0041, issue #11) - [ADR-0004 — Project file format](0004-project-file-format.md) diff --git a/docs/requirements.md b/docs/requirements.md index ed3fb29..0cac2a5 100644 --- a/docs/requirements.md +++ b/docs/requirements.md @@ -13,8 +13,7 @@ is a process failure. **Scope.** The list is intentionally coarse — each item is a unit of "satisfied / not satisfied" judgement. When an item is taken up for implementation, it is decomposed further in a -backlog (initially in this repo, later in GitHub issues once the -repo is pushed). +backlog (initially in this repo, now tracked as Gitea issues). ## Status legend