From ae1531835d73053969656e54daee004d546e37c3 Mon Sep 17 00:00:00 2001 From: didericis Date: Thu, 28 May 2026 22:53:53 -0400 Subject: [PATCH] docs: drop "forge" jargon for concrete Gitea wording We use Gitea, not an abstract forge. Reword the docs added in this branch: "forge thread" -> "Gitea thread", and the research note's generic "forge" -> "Gitea" / "hosting provider" as context demands, keeping its portability argument coherent. Co-Authored-By: Claude Opus 4.8 --- docs/decisions/README.md | 6 ++-- docs/prds/README.md | 4 +-- docs/research/README.md | 2 +- ...ue-tracking-vs-in-repo-decision-history.md | 30 +++++++++---------- 4 files changed, 21 insertions(+), 21 deletions(-) diff --git a/docs/decisions/README.md b/docs/decisions/README.md index 8bd9246..5db1730 100644 --- a/docs/decisions/README.md +++ b/docs/decisions/README.md @@ -3,8 +3,8 @@ Short, durable records of decisions — one file per decision. This is a lightweight [Architecture Decision Record](https://adr.github.io/) practice: capture *what was decided and why* in a versioned file so the -reasoning lives in the clone, not in a forge issue thread or a chat log -that disappears when the provider does. +reasoning lives in the clone, not in a Gitea issue thread or a chat log +that disappears when the host does. See `docs/research/issue-tracking-vs-in-repo-decision-history.md` for the rationale behind keeping decision history in-repo, and @@ -34,7 +34,7 @@ What we decided, stated plainly. What follows — the good, and the costs/trade-offs accepted. ## Links -PRDs, research notes, issues/PRs. Forge links are convenience +PRDs, research notes, issues/PRs. Gitea links are convenience pointers; the reasoning above must stand without them. ``` diff --git a/docs/prds/README.md b/docs/prds/README.md index bd8ec7f..a947199 100644 --- a/docs/prds/README.md +++ b/docs/prds/README.md @@ -1,7 +1,7 @@ # Product requirement docs One PRD per feature: what to build, why, and how it's scoped. The PRD -is the durable spec — it should stand on its own without a forge issue +is the durable spec — it should stand on its own without a Gitea issue thread (see [`../README.md`](../README.md) for when a PRD is the right document vs. a research note or a decision record). @@ -60,4 +60,4 @@ doesn't need (a small change rarely needs Scope or Implementation chunks) and add others where they help (e.g. Testing strategy, Alternatives considered, References). Keep the rationale self-contained — inline the reasoning rather than linking out to an issue thread, so -the PRD survives a forge migration. +the PRD survives a move off Gitea. diff --git a/docs/research/README.md b/docs/research/README.md index aaa6968..6e38e86 100644 --- a/docs/research/README.md +++ b/docs/research/README.md @@ -37,6 +37,6 @@ In practice most notes share a loose shape: Keep the reasoning self-contained and grounded: cite sources, link files and PRDs, and prefer concrete evidence from this repo over generic claims — a note should stand on its own without a chat log or a -forge thread. When a note's recommendation gets acted on, capture the +Gitea thread. When a note's recommendation gets acted on, capture the resulting decision in a PRD or a decision record; the note stays as the "why we looked into it," not the system of record for the choice. diff --git a/docs/research/issue-tracking-vs-in-repo-decision-history.md b/docs/research/issue-tracking-vs-in-repo-decision-history.md index fb3f4a6..72a5803 100644 --- a/docs/research/issue-tracking-vs-in-repo-decision-history.md +++ b/docs/research/issue-tracking-vs-in-repo-decision-history.md @@ -5,12 +5,12 @@ decision-making around them) as Gitea issues, given that the project already records specs in-repo as PRDs (`docs/prds/`) and rationale as research notes (`docs/research/`). The stated constraint is that the *history of why we decided things* should be durable and portable — -not locked into a single forge (Gitea today, conceivably GitHub or -something else tomorrow). +not locked into a single hosting provider (Gitea today, conceivably +GitHub or something else tomorrow). ## Summary -Keep using issues, but demote them. The repository — not the forge — is +Keep using issues, but demote them. The repository — not Gitea — is the system of record for any decision you would be unhappy to lose. Issues are an excellent **inbox and coordination surface** (cheap capture, triage, async discussion, notifications, auto-linking) and a @@ -25,8 +25,8 @@ it is closed.** PRDs already do this for features; the gap is (a) small requests that never merit a PRD and (b) decisions that aren't features at all (e.g. "we merge with rebase," "author identity is claimed-not- vouched"). Close that gap with a lightweight in-repo decision log. Then -issues can be as disposable as the forge makes them, and migrating -forges costs you triage state, not history. +issues can be as disposable as Gitea makes them, and migrating off +Gitea costs you triage state, not history. ## Why this even comes up here @@ -46,9 +46,9 @@ But the issue layer has quietly become load-bearing in places: - PR #89's description links `…/didericis/claude-bottle/issues/88` — the **pre-rename** repo path (the project was Codex-bottle/claude- bottle before the bot-bottle rebrand). That link is already - half-dead: a concrete demonstration that forge URLs rot under the + half-dead: a concrete demonstration that Gitea URLs rot under the most routine event imaginable, a rename. -- Issue/PR numbers (`#88`, `#90`, `#94`, `#95`) are **forge-assigned +- Issue/PR numbers (`#88`, `#90`, `#94`, `#95`) are **Gitea-assigned from a shared sequence**. They cannot be reconstructed from a clone, and they collide/renumber on import into a different tracker. @@ -65,10 +65,10 @@ producing references that don't survive a rename, let alone a migration. | Auto-linking (`Closes #N`, PR↔issue, commit↔issue) | Native | Manual cross-reference | | Version control of the content | None — lives in Gitea's DB | Full — diff, blame, branch, revert | | Travels with `git clone` | No | Yes | -| Survives forge migration | Degrades (export/import; threads, authors, timestamps, refs lossy) | Unaffected | -| Survives forge outage | Inaccessible | Local clone has it | +| Survives a move off Gitea | Degrades (export/import; threads, authors, timestamps, refs lossy) | Unaffected | +| Survives a Gitea outage | Inaccessible | Local clone has it | | Greppable offline / by tooling | Only via API | `grep docs/` | -| Reproducible identifiers | Forge-assigned numbers | Filenames you control (`0027-…`) | +| Reproducible identifiers | Gitea-assigned numbers | Filenames you control (`0027-…`) | The split is clean: **issues win on the live, social, coordination axes; the repo wins on every durability and portability axis.** Nothing about @@ -82,7 +82,7 @@ don't let the durable thing depend on the ephemeral one." emerges in a thread and dies there unless someone copies it into the spec. PRD 0025 is already in this state. 2. **Reference rot.** `Closes #88` / "see issue #90" are meaningful only - against one forge instance at one point in time. A rename already + against one Gitea instance at one point in time. A rename already broke one such link; a migration would break all of them and silently renumber the survivors. 3. **Two sources of truth.** A PRD carries `Status: Draft`; the issue @@ -162,7 +162,7 @@ Options, cheapest first: 3. **Periodic issue export.** Belt-and-suspenders: a scheduled job hits the Gitea API and dumps open/closed issues + comments to JSON under `docs/issues-archive/`, committed. Preserves the raw thread against - forge loss without changing daily workflow. Mechanical, not a + losing Gitea without changing daily workflow. Mechanical, not a substitute for reifying rationale (a JSON dump of a thread is evidence, not a decision). @@ -172,7 +172,7 @@ These compose: ADRs/journal for the *decision*, optional export for the ## Recommendation 1. **Keep Gitea issues for intake, triage, and discussion.** Don't fight - the forge on the things it's good at. + Gitea on the things it's good at. 2. **Make the repo the system of record.** Adopt the rule: no decision is "done" until its rationale exists in a versioned file (PRD, research note, or decision log). The issue is a pointer, never the @@ -182,7 +182,7 @@ These compose: ADRs/journal for the *decision*, optional export for the back-filling the few decisions already made only in threads or chat (rebase-merge policy; the agent-identity trust call from PRD 0027). 4. **Retrofit PRD 0025** to inline its #88 rationale, removing the one - existing hard dependency on a forge thread. + existing hard dependency on a Gitea thread. 5. **Treat issue numbers as disposable.** When a PRD/commit cites an issue, ensure the cited content is mirrored in-repo so the citation degrades to a dead-but-harmless link, not lost information. (The @@ -192,5 +192,5 @@ These compose: ADRs/journal for the *decision*, optional export for the Net: issues stay, because the alternative to issues is chat, which is worse. But the project's durable memory must live where the project -already lives — in the clone — so that switching forges, or losing one, +already lives — in the clone — so that moving off Gitea, or losing it, costs you a backlog you can rebuild, never a history you can't.