didericis/bot-bottle
1
0
Fork 0
Code Issues 7 Pull Requests 15 Actions Packages Projects Releases Wiki Activity

docs: portable decision history — add ADR-lite log, make PRD 0025 self-contained #97

Merged
didericis merged 8 commits from docs/decision-log into main 2026-05-28 23:12:46 -04:00
Conversation 2 Commits 8 Files Changed 10
+499 -8
didericis commented 2026-05-28 21:53:19 -04:00
Owner
Copy Link
Copy Source

Summary

Make the project's decision history portable: keep durable rationale in the repo rather than in forge issue threads. Motivated by the research note in this PR — Gitea issues are a fine ephemeral inbox but a poor archive (provider-locked storage, brittle numeric refs, rationale stranded in comments).

Changes (3 commits)

  1. docs(research) — issue tracking vs in-repo decision history: recommends demoting issues to a coordination surface and reifying decisions into versioned files.
  2. docs(decisions) — new docs/decisions/ ADR-lite log (convention README + template), back-filling two decisions that had no in-repo home: ADR 0001 (merge PRs with rebase) and ADR 0002 (agent identity is claimed-not-vouched, from PRD 0027). docs/INDEX.md points at it.
  3. docs(prd) — retrofit PRD 0025 with an "Alternatives considered" section so its design rationale stands without issue #88's comment thread; repoint the two phrases that depended on the thread.

Notes

  • File links above are commit-pinned (/src/commit/598c96679ab7…/) so they survive the rebase-merge SHA rewrite and branch deletion — the practice ADR 0001 documents.
  • The research note still calls docs/decisions/ "proposed"; left as the point-in-time analysis that motivated the change.
## Summary Make the project's decision history portable: keep durable rationale in the repo rather than in forge issue threads. Motivated by the research note in this PR — Gitea issues are a fine ephemeral inbox but a poor archive (provider-locked storage, brittle numeric refs, rationale stranded in comments). ## Changes (3 commits) 1. **`docs(research)`** — [issue tracking vs in-repo decision history](https://gitea.dideric.is/didericis/bot-bottle/src/commit/598c96679ab7f1c1a50f83cca9a7bf2e081edf54/docs/research/issue-tracking-vs-in-repo-decision-history.md): recommends demoting issues to a coordination surface and reifying decisions into versioned files. 2. **`docs(decisions)`** — new [`docs/decisions/`](https://gitea.dideric.is/didericis/bot-bottle/src/commit/598c96679ab7f1c1a50f83cca9a7bf2e081edf54/docs/decisions/README.md) ADR-lite log (convention README + template), back-filling two decisions that had no in-repo home: ADR 0001 (merge PRs with rebase) and ADR 0002 (agent identity is claimed-not-vouched, from PRD 0027). `docs/INDEX.md` points at it. 3. **`docs(prd)`** — retrofit [PRD 0025](https://gitea.dideric.is/didericis/bot-bottle/src/commit/598c96679ab7f1c1a50f83cca9a7bf2e081edf54/docs/prds/0025-bottle-extends.md) with an "Alternatives considered" section so its design rationale stands without issue #88's comment thread; repoint the two phrases that depended on the thread. ## Notes - File links above are commit-pinned (`/src/commit/598c96679ab7…/`) so they survive the rebase-merge SHA rewrite and branch deletion — the practice ADR 0001 documents. - The research note still calls `docs/decisions/` "proposed"; left as the point-in-time analysis that motivated the change.
didericis reviewed 2026-05-28 21:56:12 -04:00
docs/decisions/README.md
@@ -0,0 +53,4 @@
## Index
- [ADR 0001](0001-merge-prs-with-rebase.md) — merge PRs with rebase, not merge commits.
- [ADR 0002](0002-agent-identity-claimed-not-vouched.md) — agent-set git identity is claimed, not vouched.
didericis commented 2026-05-28 21:56:12 -04:00
Author
Owner
Copy Link
Copy Source

I don't think we want to maintain an index/omit this

I don't think we want to maintain an index/omit this
didericis marked this conversation as resolved
didericis commented 2026-05-28 22:01:09 -04:00
Author
Owner
Copy Link
Copy Source

Addressed in 35f6584 — dropped the hand-maintained ADR index from docs/decisions/README.md; the files in the directory are the index now.

Addressed in 35f6584 — dropped the hand-maintained ADR index from `docs/decisions/README.md`; the files in the directory are the index now.
didericis force-pushed docs/decision-log from efdb6c930c to 044a8a3122 2026-05-28 22:27:02 -04:00 Compare
didericis added 8 commits 2026-05-28 23:05:36 -04:00
docs(research): issue tracking vs in-repo decision history c840182d12 
Analyze tracking feature requests in Gitea against the project's
in-repo PRDs/research notes, given the goal of keeping decision
history portable and not provider-locked. Recommends demoting issues
to an ephemeral inbox and reifying durable rationale into the repo.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
docs(decisions): add ADR-lite decision log 1df78ee77f 
Add docs/decisions/ with a convention README and back-fill two
decisions that previously had no in-repo home: merging PRs with
rebase (ADR 0001) and the agent-identity claimed-not-vouched trust
posture from PRD 0027 (ADR 0002). Point docs/INDEX.md at it.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
docs(prd): inline #88 rationale into PRD 0025 ccbed97776 
Add an "Alternatives considered" section enumerating the design
options from issue #88 (duplicate bottles / agent-side bottle_config
/ bottle-side extends) and why extends won, so the PRD stands without
the forge thread. Repoint the two phrases that depended on the #88
comment thread at the new section.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
docs(decisions): drop hand-maintained index from README 2141a85884 
Per review on PR #97: an index that lists every ADR is a sync
burden. The files in docs/decisions/ are the index.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
docs: hoist "when to write which document" to docs/README.md 1308e61c7e 
Move the document-type comparison out of docs/decisions/README.md
(where it only surfaced if you were already in the decisions dir) up
to a new docs/README.md, renamed "When to write which document".
Leave a pointer from the decisions README.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
docs: drop docs/INDEX.md, add PRD README with format d329e511fd 
Remove the one-line docs/INDEX.md (its directory pointers are covered
by docs/README.md's "when to write which document" table). Add
docs/prds/README.md documenting the PRD naming, Status lifecycle, and
section format. Repoint the AGENTS.md repository-layout list at the
new READMEs and add the decisions/ dir.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
docs(research): add README describing research notes 5c5f576df0 
Document what research notes are (opinionated investigations of a
question/design space), their unnumbered kebab-case naming, and their
loose verdict-first shape — explicitly freeform, not a template. Point
the AGENTS.md research line at it.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
docs: drop "forge" jargon for concrete Gitea wording
test / integration (pull_request) Successful in 53s
Details
test / integration (push) Successful in 57s
Details
test / unit (pull_request) Successful in 33s
Details
test / unit (push) Successful in 36s
Details
ae1531835d 
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 <noreply@anthropic.com>
didericis force-pushed docs/decision-log from 5871dbf24a to ae1531835d 2026-05-28 23:05:36 -04:00 Compare
didericis merged commit ae1531835d into main 2026-05-28 23:12:46 -04:00
Sign in to join this conversation.
Reviewers
No Reviewers
didericis
Labels
Clear labels
Compat/Breaking
Breaking change that won't be backward compatible
 Kind/Bug
Something is not working
 Kind/Documentation
Documentation changes
 Kind/Enhancement
Improve existing functionality
 Kind/Feature
New functionality
 Kind/Security
This is security issue
 Kind/Testing
Issue or pull request related to testing
Priority
Critical
1
The priority is critical
Priority
High
2
The priority is high
Priority
Low
4
The priority is low
Priority
Medium
3
The priority is medium
Reviewed
Confirmed
1
Issue has been confirmed
Reviewed
Duplicate
2
This issue or pull request already exists
Reviewed
Invalid
3
Invalid issue
Reviewed
Won't Fix
3
This issue won't be fixed
Status
Abandoned
3
Somebody has started to work on this but abandoned work
Status
Blocked
1
Something is blocking this issue or pull request
Status
Need More Info
2
Feedback is required to reproduce issue or to continue work
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
didericis-claude (didericis (claude)) didericis-codex (didericis (codex)) didericis-gemma (gemma) didericis
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: didericis/bot-bottle#97
Delete Branch "docs/decision-log"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?