From 1e2ce29cf6fa96a54edbb0b35e90c59cfea1fa89 Mon Sep 17 00:00:00 2001 From: topkoa Date: Mon, 13 Jul 2026 00:41:44 -0400 Subject: [PATCH] docs: make FEP-first impossible to miss before the gate fires MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The CI gate catches spec drift at merge time; these two additions catch it at write time, which is where "developer didn't read the spec first" actually happens. CLAUDE.md (Song Formats): a spec-is-sacrosanct paragraph next to the spec pointer — the spec defines the format, the app implements it, any new manifest key/file/directory lands in the spec first via the FEP process, and the gate has no in-repo bypass. AI agents and contributors both hit this while writing feedpak-touching code, not after CI reddens. .github/pull_request_template.md (new — the repo had only issue templates): a feedpak-surface section requiring either "doesn't touch pack I/O" or a link to the landed FEP + the .feedpak-spec-ref bump, plus the standing changelog/tests/DCO checklist. Signed-off-by: topkoa --- .github/pull_request_template.md | 17 +++++++++++++++++ CLAUDE.md | 14 ++++++++++++++ 2 files changed, 31 insertions(+) create mode 100644 .github/pull_request_template.md diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..1ceb6ac --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,17 @@ +## What + + + +## feedpak surface + + + +- [ ] This PR does **not** change how the app reads/writes feedpaks (manifest keys, pack files, folder layout) +- [ ] …or it does, and the spec change landed first via the [FEP process](https://github.com/got-feedback/feedpak-spec/blob/main/CONTRIBUTING.md) — FEP / spec PR: `got-feedback/feedpak-spec#___` — and `.feedpak-spec-ref` is bumped to the merged SHA in this PR + +## Checklist + +- [ ] `CHANGELOG.md` `[Unreleased]` updated (user-visible changes) +- [ ] Tests added/updated for new behaviour +- [ ] Commits are DCO signed off (`git commit -s`) diff --git a/CLAUDE.md b/CLAUDE.md index 9f6f973..c8486e3 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -588,6 +588,20 @@ tab, key/scale annotations, etc.). Published as **feedpak**; this codebase still **sloppak** name internally — same on-disk format. [docs/sloppak-spec.md](docs/sloppak-spec.md) is a local pointer + code map. +**The spec is sacrosanct — read it BEFORE changing how this app reads or writes packs.** The +spec repo defines the format; this app merely implements it ("a change is not part of the format +until it lands here" — feedpak-spec/GOVERNANCE.md). Any new manifest key, file, or directory the +app touches must land in the spec **first**, via the +[FEP process](https://github.com/got-feedback/feedpak-spec/blob/main/CONTRIBUTING.md) (proposal +issue → one spec PR updating spec + schemas + example + changelog → then bump `.feedpak-spec-ref` +here in the same PR as your code). CI enforces this: the `feedpak-spec` job +([docs/feedpak-spec-gate.md](docs/feedpak-spec-gate.md)) fails any PR whose code touches a +manifest key the pinned spec doesn't declare, and there is **no in-repo bypass** — the exceptions +file is a closed grandfather list that only shrinks. If the format seems to be missing something +you need, that's a FEP conversation, not a workaround. (Cautionary tale: `original_audio`, #933 — +shipped without a spec entry, and third-party packers reverse-engineered a folder convention out +of a code comment.) + **Key code:** - `lib/sloppak.py` — format detection, zip/directory resolution, metadata extraction, song loading - `lib/sloppak_convert.py` — sloppak assembly pipeline, Demucs stem splitting