From b6949ff0c3bfc7d2208fa200f76c0a071602134d Mon Sep 17 00:00:00 2001 From: indifferentketchup Date: Mon, 4 May 2026 16:30:50 +0000 Subject: [PATCH] docs: add downstream-consumers, release flow, feature-branch conventions Captures iblogs as primary codex consumer with the call-site checklist for cross-repo public-API changes; spells out the semver / changelog cadence; documents the -bootstrap branch + --no-ff merge pattern set by the redactor and iblogs-bootstrap branches; pins the specs/plans path convention from the superpowers skills. Co-Authored-By: Claude Opus 4.7 (1M context) --- CLAUDE.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 5404b64..0aed72e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -84,6 +84,10 @@ Scaffolded games: `Minecraft`, `Hytale`, `SevenDaysToDie` (stubs only — empty At minimum: (1) entry count after `parse()` matches the synthetic fixture's line count, (2) one or more named-group `FIELDS` regexes from the `Pattern` class extract correctly from a representative line, (3) `Detective` handed the fixture path returns an instance of this Log class. Use `#[DataProvider]` when the same shape repeats per file. +### Downstream consumers + +`iblogs` (sibling repo at `/opt/iblogs`, package `indifferentketchup/iblogs`, fork of `aternosorg/mclogs`) is the primary consumer of codex via a Composer `vcs` repository entry pinned to the latest minor tag. Public-API changes in `src/{Detective,Log,Printer,Util}/*.php` and `src/Analysis/*.php` propagate there; when modifying those types, sanity-check the iblogs call sites at `/opt/iblogs/src/{Detective.php,Log.php,Printer/Printer.php,Printer/FormatModification.php,Api/Response/CodexLogResponse.php}` and the stub class at `/opt/iblogs/src/Data/Deobfuscator.php`. + ## Pitfalls 1. **`PatternParser` is incompatible with named regex groups.** PHP's `preg_match` returns named groups *plus* their numeric duplicates in the same array; `PatternParser`'s foreach iterates both and throws on the string-key entries. Convention: `LINE` regexes (used by the parser) use **unnamed** groups with field order documented in the Pattern class's docblock. Named groups are fine inside extractor regexes invoked from analysers, since `PatternAnalyser` hands the whole match array to `Insight::setMatches`. @@ -97,6 +101,9 @@ At minimum: (1) entry count after `parse()` matches the synthetic fixture's line - **One commit per concrete log type** when adding game support: pattern class + log subclass + synthetic fixture + test in a single commit, run `composer test`, then move on. `Detective::__construct()` wiring goes in its own follow-up commit once all log types are present. - **Out-of-scope cleanup goes in its own commit.** Tempting workflow/lint fixes (e.g. deprecated CI syntax, comment hygiene) noticed mid-feature should not be folded in — separate commit or follow-up PR. - **Pre-destructive checkpoint pattern.** Before bulk renames/moves: `git commit --allow-empty -m "pre-X checkpoint"` as a revert anchor. Skip the empty slot if it produces no diff at the end of a plan. +- **Release flow.** Semver: a new public API surface bumps the minor version, not the patch (`v0.1.x → v0.2.x`). Cut: rename `[Unreleased]` to `[X.Y.Z] — YYYY-MM-DD` in `CHANGELOG.md`, add a `[X.Y.Z]:` link reference at the bottom, fresh empty `[Unreleased]` above; lightweight `backup/pre-vX.Y.Z` tag (local only) before annotated `git tag -a vX.Y.Z`; push the annotated tag only. +- **Feature branches.** Substantive feature work lands on a `-bootstrap`-style branch off master with a `backup/pre-` lightweight tag at the branch start, merged `--no-ff` after user review. The `redactor` and `iblogs-bootstrap` branches set the precedent. +- **Specs and plans live at** `docs/superpowers/specs/YYYY-MM-DD--design.md` and `docs/superpowers/plans/YYYY-MM-DD-.md` per the brainstorming and writing-plans skill conventions. ## Privacy / fixture rules