From b3d547802060699d778e5e9c7e1e7e02aa0c4471 Mon Sep 17 00:00:00 2001 From: Erich Blume Date: Tue, 3 Mar 2026 15:30:00 -0800 Subject: [PATCH] Use towncrier orphan fragment naming for C0 changes C0 changes have no branch name, so `main..md` fragments collide. Switch to towncrier's `+..md` orphan convention and rename existing `main.*` fragments. Co-Authored-By: Claude Opus 4.6 --- CLAUDE.md | 4 +++- .../{main.infra.md => +changelog-subdir-hook.infra.md} | 0 .../{main.bugfix.md => +frigate-db-path.bugfix.md} | 0 docs/changelog.d/+orphan-fragment-convention.doc.md | 1 + docs/how-to/agent-change-process.md | 4 ++-- docs/tutorials/ai-assistance-guide.md | 4 ++++ 6 files changed, 10 insertions(+), 3 deletions(-) rename docs/changelog.d/{main.infra.md => +changelog-subdir-hook.infra.md} (100%) rename docs/changelog.d/{main.bugfix.md => +frigate-db-path.bugfix.md} (100%) create mode 100644 docs/changelog.d/+orphan-fragment-convention.doc.md diff --git a/CLAUDE.md b/CLAUDE.md index 3b4160b..050b0f9 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -19,9 +19,11 @@ blumeops is Erich Blume's GitOps repository for personal infrastructure, orchest 3. **Classify the change as C0/C1/C2 before starting** (see below) — this determines branching and PR requirements 4. **Feature branches + PRs for C1/C2** - checkout main, pull, create branch, open PR via `tea pr create`. C0 goes direct to main. 5. **Check PR comments with `mise run pr-comments `** before proceeding -6. **Add changelog fragments (all change levels)** - `docs/changelog.d/..md` +6. **Add changelog fragments (all change levels)** - `docs/changelog.d/..md` Types: `feature`, `bugfix`, `infra`, `doc`, `ai`, `misc` Applies to C0, C1, and C2 whenever the change is user-visible or noteworthy. + - **C1/C2:** Use branch name: `..md` + - **C0:** Use orphan prefix: `+..md` (avoids `main.*` collisions) 7. **Test before applying** - dry runs (`--check --diff`), syntax checks, `ssh indri '...'` 8. **Wait for user review before deploying** (C1/C2) 9. **Never merge PRs or push to main without explicit request** (C0 commits to main are fine) diff --git a/docs/changelog.d/main.infra.md b/docs/changelog.d/+changelog-subdir-hook.infra.md similarity index 100% rename from docs/changelog.d/main.infra.md rename to docs/changelog.d/+changelog-subdir-hook.infra.md diff --git a/docs/changelog.d/main.bugfix.md b/docs/changelog.d/+frigate-db-path.bugfix.md similarity index 100% rename from docs/changelog.d/main.bugfix.md rename to docs/changelog.d/+frigate-db-path.bugfix.md diff --git a/docs/changelog.d/+orphan-fragment-convention.doc.md b/docs/changelog.d/+orphan-fragment-convention.doc.md new file mode 100644 index 0000000..40acdbc --- /dev/null +++ b/docs/changelog.d/+orphan-fragment-convention.doc.md @@ -0,0 +1 @@ +Use towncrier orphan fragment naming (`+slug..md`) for C0 changes to avoid `main.*` collisions. diff --git a/docs/how-to/agent-change-process.md b/docs/how-to/agent-change-process.md index 429e473..a83737e 100644 --- a/docs/how-to/agent-change-process.md +++ b/docs/how-to/agent-change-process.md @@ -29,7 +29,7 @@ A change where the risk is low enough that problems can be quickly fixed forward 1. Run `mise run ai-docs` to load context 2. Implement the change directly on main -3. Add a changelog fragment if the change is user-visible or noteworthy (`docs/changelog.d/..md`) +3. Add a changelog fragment if the change is user-visible or noteworthy (`docs/changelog.d/+..md`) 4. Commit and push No feature branch or PR required. If something goes wrong, fix forward with another commit. @@ -270,7 +270,7 @@ tags: - **C0:** Commit directly to main - **C1:** Single feature branch, PR early, push often - **C2:** Branch named `mikado/`, Mikado Branch Invariant enforced, `C2()` commit convention, PR early, push after every leaf-node closure -- **Changelog fragments (all levels):** Add `docs/changelog.d/..md` for any user-visible or noteworthy change, regardless of change class. C0 includes the fragment in the same commit. C1 includes it during the branch work. C2 includes it in the `finalize` commit. +- **Changelog fragments (all levels):** Add `docs/changelog.d/..md` for any user-visible or noteworthy change, regardless of change class. C0 uses orphan fragments (`+..md`) to avoid `main.*` collisions. C1/C2 use the branch name (`..md`). C0 includes the fragment in the same commit. C1 includes it during the branch work. C2 includes it in the `finalize` commit. - **Deploy from branches** — C1 and C2 changes deploy from the unmerged branch (ArgoCD `--revision`, Ansible from checkout, etc.). Reset to main after merge. - GitOps requires pushing to test — if a pushed commit breaks, revert it promptly diff --git a/docs/tutorials/ai-assistance-guide.md b/docs/tutorials/ai-assistance-guide.md index 274dd48..07192a1 100644 --- a/docs/tutorials/ai-assistance-guide.md +++ b/docs/tutorials/ai-assistance-guide.md @@ -58,7 +58,11 @@ EOF Add a fragment for user-visible changes: ```bash +# C1/C2: use branch name echo "Description" > docs/changelog.d/branch-name.feature.md + +# C0: use orphan prefix (no branch to name after) +echo "Description" > docs/changelog.d/+descriptive-slug.feature.md ``` Types (file suffix): `.feature`, `.bugfix`, `.infra`, `.doc`, `.ai`, `.misc`