diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 05a22bc77..ea819f655 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -12,6 +12,7 @@ Existing module authors can opt into [automatic publication](../docs/MODULE_AUTH - [ ] I verified the source, licences, UI and qualification reports, including instance isolation and Part/project/reboot persistence where applicable; no required acceptance check is failed or untested. - [ ] New or changed module: I read the guide for its category in `docs/module-guides/` (and `sequencing.md` if it acts in time), walked its checklists, and TESTING.md lists what I did not test. `npm run module:doctor -- ` is green. +- [ ] The module builds, installs and works when it is the only module chosen. It depends on no other module: no `requires`, no hooks into another module, not stacked on another module's pull request. - [ ] Every code change to a module has a greater semantic version and exact catalog pin (documentation and media edits need none). - [ ] Source and media are original or properly licensed; authors and full licence texts are preserved. - [ ] No Elektron firmware, extracted routines/tables, upgrade files or other infringing material is included. diff --git a/AGENTS.md b/AGENTS.md index f1adc42d2..442127075 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -20,6 +20,7 @@ Modwerk builds custom firmware modules for Elektron instruments. This repository - Never commit firmware, extracted stock code or tables, memory dumps or built images. Firmware stays on the developer's computer and never enters CI. - Before planning a new module, check what Modwerk already has: the library, `sdk/catalog.json`, `sdk/digitakt/modules/`, `sdk/digitone/modules/`, `sdk/drafts/` and open pull requests. If one already does the job, extend it through the update workflow instead of building a duplicate. - Refuse a module that copies someone else's protected work: another product's code or firmware, factory samples or recordings, artwork or a trademarked name, or a port without its author's permission or a licence that allows it. Say why briefly and offer an original take. Ideas, techniques and published algorithms are free to use; when the source or licence is unclear, ask before writing anything. +- Refuse a module that depends on another module. Every module builds, installs and works when it is the only module chosen, on the stock OS, the base and the shared SDK. So no module calls, extends or hooks another module's code, engine, rows, tables or files, and none declares `requires`, adds a "needs X" selection rule or opens a pull request stacked on another module's. Code two modules share goes into the base or the shared SDK first, in its own owner-reviewed pull request, or both features ship as one module. There is no exception; see [cross-compatibility](docs/module-guides/README.md#cross-compatibility). - Do not edit generated files by hand: `src/catalog/module-documents.json`, `src/catalog/compatibility-checks.json`, `src/catalog/compatibility-pairs.json`, the licence notices and the machine registry. `npm run modules:generate`, `licenses:generate` and `machines:generate` write them. - Fold what you learn back into the context. When work turns up something every later developer or agent needs (a trap, a tool quirk, a measured constraint, a step a guide lacks or states wrongly), write it into the file a reader would open for that task, rather than leaving it in the session, a PR comment or private notes: the matching [module guide](docs/module-guides/README.md), [docs/ADD_A_MODULE.md](docs/ADD_A_MODULE.md), [docs/DEVELOPER_WORKFLOW.md](docs/DEVELOPER_WORKFLOW.md), or this file when it affects every task. Correct a stale line instead of adding a contradicting one, keep it short and general, and keep it stock-free: no firmware bytes, code, tables or dumps, and a hardware behaviour only as observed on a named build. Leave `sdk/octabam/AGENTS.md` unchanged. Put the edit on the pull request you already have open for this work (a small docs-only pull request when none is open), never inside a module release (it is outside a registered author's scope and would end automatic publication), and tell the owner what you added. - When you find a bug, a fix, or an improvement that makes Modwerk easier to use or develop for, outside the task at hand, commit it to the pull request you already have open for this work and add a line to its description saying what it is and how you checked it. With none open, send it as its own small, readable pull request: title it `Fix: …`, `Improvement: …` or `Docs: …` (a workflow labels it from that), one change, and a description that says in plain words what was wrong or hard, what changes and how you checked it. Never fold it into a module release. In a contributor's fork, offer it and open it with their OK; if you can't fix it, open an issue instead. See [Fixes and improvements](docs/DEVELOPER_WORKFLOW.md#fixes-and-improvements). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 011302642..9cbeb8d78 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,6 +10,7 @@ Follow [Add or port a module](docs/ADD_A_MODULE.md). It covers porting from octa What review expects for a new module, or for a change to how a module runs: +- a module that stands alone: it builds and works with no other module chosen. A module that depends on another is refused ([cross-compatibility](docs/module-guides/README.md#cross-compatibility)); - worst-case cycle counts and exact memory accounting (Octatrack, see [qualification](docs/MODULE_QUALIFICATION.md)); - a hardware report from a real unit that states its model, how long it ran, what was tested and the limitations. There is no minimum duration or track count; - complete documentation with a short tutorial, and real black-and-white screenshots of where the module is selected and of its controls ([captures](docs/MODULE_UI_CAPTURES.md)); diff --git a/docs/ADD_A_MODULE.md b/docs/ADD_A_MODULE.md index c9efaf575..79d274da3 100644 --- a/docs/ADD_A_MODULE.md +++ b/docs/ADD_A_MODULE.md @@ -24,6 +24,7 @@ Every module follows [the guide for its category](module-guides/README.md): effe - Never commit firmware, extracted stock code or tables, memory dumps, emulator cards or built images. Firmware stays on your computer. Stock code is referenced by address, length and SHA-256 and copied from each user's own OS file when they build. - Keep every author's credit and full licence text. Pin ported source to an exact commit. Both module contracts accept an optional `author.contributors` array of `{ "github": "handle", "name": "Display name" }` entries (`name` is optional). Each contributor appears on a separate line below the primary author in library cards, page headers and module information; describe their contribution in `author.credits` and the README. This attribution does not grant module ownership, report access or release authority; those continue to use the primary author and declared maintainers. - Code or behaviour changes inside a module folder need a higher semantic `version` in its manifest, and the same version in `sdk/catalog.json` once listed. Documentation/media/prose-only edits need a version bump only when requesting automatic author publication. +- No module depends on another. Each builds, installs and works when it is the only module chosen: no `requires`, no hooks into another module's code, no "needs X" selection rule, no pull request stacked on another module's. Shared code goes into the base or the shared SDK first, or the features ship as one module. Review refuses a dependent module, with no exception ([cross-compatibility](module-guides/README.md#cross-compatibility)). - One module per pull request. The owner approves the first release and changes beyond the registered author's scope. Later scoped updates can use automatic author publication after evidence verification and required checks. ## Persistence and multiple instances diff --git a/docs/module-guides/README.md b/docs/module-guides/README.md index 366956a86..6291bf6ff 100644 --- a/docs/module-guides/README.md +++ b/docs/module-guides/README.md @@ -68,6 +68,8 @@ Most of these need a native toolchain and your own original OS 1.40C kept outsid ## Cross-compatibility +**No module depends on another, on any machine.** Every module builds, installs and works when it is the only module chosen, on the stock OS, the base and the shared SDK. It never calls, extends or hooks another module's code, engine, rows, tables or files, and it declares no `requires`. No "needs X" selection rule, and no module pull request stacked on another's. When two modules need the same code, put it in the base or the shared SDK first, as an event or a table, in its own owner-reviewed pull request, or ship both features as one module. Review refuses a module that depends on another, and no exception entry covers it. + Every Octatrack module must install beside every other active module and the Modwerk base. `npm run modules:compat` checks this on every pull request, as part of `npm run check` and `npm run module:doctor`, so registered authors' automatic updates pass it too. It reads declarations only: your manifest's detours, hooks, pokes, references, caves, grown tables, kept bytes and stock copies, the port recipes, the committed base package and octabam's DSP resource rules. It needs no firmware and runs in under a second. It checks every pair and the whole set. - **One owner per byte.** No two modules, and no module and the base, may patch overlapping stock bytes or relocate the same stock table (Elekloader's rule 5).