musiikki/nih-plug-template
Template
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: move branding into tools/ and drive the checker from a table

Browse Source 
Three changes that only make sense together.

**tools/**. check-branding.sh, brand-plugin.sh and branding.conf were
accumulating in the repo root, and a deploy.sh/bat/ps1 set would land
there too. They now live in tools/ and resolve the repo root explicitly
rather than assuming their own directory is it, so they behave the same
however they are invoked.

**One name drives the rest.** branding.conf now derives the package name,
the Rust types and the display name from PLUGIN_NAME, each overridable.
Derivation-by-default removes a class of drift; the override matters
because the derivation is sometimes invalid — "206 Prototype" derives to
"206_prototype", which cargo rejects outright — and because PLUGIN_NAME is
cosmetic while the package name is structural. A display tweak should not
silently rename the crate, its bundle lookup, the CI command and the
lockfile. This template overrides three of them, which a real plugin
normally will not: its names are the template's own rather than derived
from a product name.

An overridden PKG that no longer matches the derivation is reported at
info level, never failed. The override is usually deliberate; a display
rename that forgot the package looks identical from here, and is not.

**The site table is data.** branding-sites.tsv lists every place a name
must appear and in what form; check-branding.sh iterates it instead of
carrying 29 check calls in shell. The scripts are now identical across
every plugin built from this template, with only the table and conf
differing — which matters because the template and codename-206 had
already diverged by two checks, so every sync was a shell merge.

brand-plugin.sh regenerates the rows it owns and preserves the rest, so a
hand-added row for a file this template does not ship survives a rename.
Custom rows are value-substituted like any other tracked file, so they
track the rename rather than going stale — the first cut excluded the
whole table from substitution and got that wrong.

brand-plugin.sh also gained an interactive mode: run it with no arguments
and it prompts for each value with the current one as the default, so
Enter keeps it and a run that answers nothing changes nothing. It only
engages when there is a terminal to ask at, so CI gets the usage message
and exit 2 rather than a hang.

Verified by applying a full rename to a sandboxed copy: 8 files rewritten,
29 owned rows regenerated, 1 custom row preserved and substituted, checker
green at 48/0/7, and the result compiles as bari_206.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WHt4DykxXaQnyaJfyS8KCn
This commit is contained in:
Mikkeli Matlock
2026-09-01 10:15:34 +09:00
parent 2dd47b5afd
commit 8c24b83ea3
7 changed files with 307 additions and 186 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+36 -30
View File
@@ -24,41 +24,49 @@ Identity is duplicated across `Cargo.toml`, `bundler.toml`, `src/lib.rs`, `NOTIC
`Cargo.lock`, the CI workflow and the docs. Nothing makes those agree, so a half-finished
rename builds a bundle under one name while CI bundles another.
`branding.conf` holds the canonical identity once. Two scripts read it:
Everything for it lives in `tools/`:
```bash
sh brand-plugin.sh --display "Fuzz Box" # derive, validate, show the plan (dry run)
sh brand-plugin.sh --display "Fuzz Box" --apply
sh check-branding.sh # exit 0 = consistent, 1 = drift
```
tools/branding.conf the names, and what derives from what
tools/branding-sites.tsv where each name has to appear, and in what form
tools/brand-plugin.sh changes names
tools/check-branding.sh verifies them
```
**`brand-plugin.sh` changes names.** It derives the package name and Rust types from the
display name, validates them against what Cargo actually accepts, rewrites every tracked
file, appends the retired spellings to `STALE`, and finishes by running the checker — a run
that ends green is a rename that landed. It is a dry run unless you pass `--apply`.
```bash
sh tools/brand-plugin.sh # interactive; Enter keeps a value
sh tools/brand-plugin.sh --display "Fuzz Box" # or non-interactive; dry run
sh tools/brand-plugin.sh --display "Fuzz Box" --apply
sh tools/check-branding.sh # exit 0 = consistent, 1 = drift
```
**`check-branding.sh` verifies them.** Both directions: every canonical value is asserted
present where it belongs, *and* no retired spelling survives anywhere. Absence alone is not
enough — renaming to the wrong new spelling would pass a stale-sweep and still break CI.
**One name drives the rest.** `PLUGIN_NAME` derives the package name (`Fuzz Box` →
`fuzz_box`), the Rust types (`FuzzBox`, `FuzzBoxParams`) and the display name. Each is
overridable in `branding.conf`, because the derivation is sometimes wrong and sometimes
outright invalid — `206 Prototype` derives to `206_prototype`, which Cargo rejects since a
package name cannot start with a digit. The helper refuses those, along with Rust keywords
and built-in crate names.
Three things it will refuse or warn about, all learned the hard way:
**The checker does both halves.** Every canonical value is asserted *present* where it
belongs, and every retired spelling is swept for. Absence alone is not enough: renaming to
the wrong new spelling would pass a stale-sweep and still break CI.
- **A package name Cargo rejects.** Names cannot start with a digit (`206 Prototype` →
`206_prototype`, rejected), be a Rust keyword, or collide with a built-in crate.
- **Moving frozen identity.** `CLAP_ID` and `VST3_CLASS_ID` are how hosts recognise saved
projects and presets. Change either and every existing session silently loses the plugin —
the track comes up empty, with no error. Pick them once before the first release; after
that they never move. `--allow-identity-change` is required to touch them, and the helper
proposes a valid 16-byte class ID rather than deriving one, because that choice is yours.
- **Development history in `CLAP_DESCRIPTION`.** Hosts show it to users who never knew your
codename. Any retired name or the repo's own codename appearing there is rejected.
**Two things it will not do for you.** `CLAP_ID` and `VST3_CLASS_ID` are how hosts recognise
saved projects and presets — change either and every existing session silently loses the
plugin, with no error. They need `--allow-identity-change`, and the 16-byte class ID is
*proposed* rather than derived, because that choice is yours. And `CLAP_DESCRIPTION` is
rejected if it carries a retired name or the repo codename: hosts show it to users who never
knew your development history.
The repo name is deliberately *not* derived. It is fixed when the repo is created and keeps
its development codename while the plugin gets a product name; `CODENAME` in `branding.conf`
records it so it can be kept out of user-facing text.
**The repo name is deliberately not derived.** It is fixed when the repo is created and keeps
its development codename while the plugin gets a product name. `CODENAME` records it so it
can be kept out of user-facing text.
Checks for files the template doesn't ship (a `deploy.ps1`, say) report as `skip` and start
enforcing once you add them.
Adding a site the template doesn't ship is one row in `branding-sites.tsv` with owner
`custom` — no shell to edit, and it survives regeneration. Rows the helper owns are rewritten
on each rename; custom rows are carried through and value-substituted like any other file.
Both files can be hand-edited; the helper is what keeps them agreeing, so run the checker
after if you do.
## Build
@@ -119,9 +127,7 @@ bundler.toml # Bundle name for `cargo xtask bundle`
src/lib.rs # Plugin skeleton — params, DSP, and egui editor, with one example gain param
xtask/ # Bundler xtask (cargo xtask bundle)
.cargo/config.toml # xtask alias
branding.conf # Canonical identity — the one place names are declared
check-branding.sh # Asserts every name is present where it belongs and no old one survives
brand-plugin.sh # Renames the plugin everywhere, then verifies with the checker
tools/ # Branding toolkit — see Renaming
.gitattributes # Pins *.sh to LF so Windows checkouts keep a valid shebang
.github/workflows/ # CI: branding check, both feature sets build, test, bundle
```