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`