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

feat: split branding into a checker and a helper over one canonical file

Browse Source 
check-branding.sh could say what disagreed but not fix it, and its
canonical block lived in its own header — so renaming meant hand-editing
the checker, which is exactly the fragile step it exists to catch.

branding.conf now holds the identity once. Both scripts read it and
neither contains a branding literal anywhere, so a rename never has to
rewrite its own tooling.

brand-plugin.sh derives the package name and Rust types from the display
name, validates them against what Cargo actually accepts, rewrites every
tracked file longest-value-first (a short name can be a substring of a
longer one), appends the retired spellings to STALE, and finishes by
running the checker. A run that ends green is a rename that landed. Dry
run unless --apply.

It refuses three things worth refusing:

- Package names Cargo rejects — digit-leading (`206 Prototype` derives to
  `206_prototype`), Rust keywords, built-in crate collisions. Verified
  against cargo init rather than assumed.
- Moving CLAP_ID or VST3_CLASS_ID without --allow-identity-change. Hosts
  key saved projects off those; changing either orphans every existing
  session silently. The 16-byte class ID is *proposed*, never derived —
  it is a fixed-width frozen identity, so the choice stays human.
- Development history in CLAP_DESCRIPTION. Hosts show it to users who
  never knew the codename, so any retired name or the repo codename
  appearing there is rejected.

The checker gains the other half of its job: asserting canonical values
are present where they belong, not only that retired ones are gone.
Absence alone would pass a rename to the *wrong* new spelling. New
positive assertions cover Cargo authors, Cargo.lock, the CI bundle
command and NOTICE — every one of which the recent Bari 206 rename had to
touch. Structural checks read their file locations from branding.conf so
a plugin whose params outgrow src/lib.rs can point them elsewhere.

Also fixes NOTICE naming the repo rather than the product, found by the
new assertion, and excludes branding.conf from the stale sweep — it lists
every retired spelling by definition, the same reason check-branding.sh
was already excluded.

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-08-31 23:11:47 +09:00
parent b05ad27a24
commit a46e7eb961
5 changed files with 411 additions and 92 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+35 -19
View File
@@ -20,31 +20,45 @@ sh check-branding.sh
## Renaming
Branding is duplicated across `Cargo.toml`, `bundler.toml`, `src/lib.rs` and the docs,
and nothing makes those agree — so a half-finished rename builds a bundle under one name
while the docs and deploy script look for another.
Identity is duplicated across `Cargo.toml`, `bundler.toml`, `src/lib.rs`, `NOTICE`,
`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.
`check-branding.sh` declares the identity once at the top and asserts every copy matches:
`branding.conf` holds the canonical identity once. Two scripts read it:
```bash
sh check-branding.sh # exit 0 = consistent, 1 = drift found
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
```
It covers the identity a host actually sees (package and bundle names, `Plugin::NAME`,
`VENDOR`, `EMAIL`, `CLAP_ID`, `VST3_CLASS_ID`, the descriptions) and the Rust type names
(`MyPlugin`, `PluginParams`) at every site they appear. Renaming the types is cosmetic —
no host ever sees them — but leaving `MyPlugin` in a shipped plugin is the kind of residue
that says nobody read the file. Leave them as-is and those checks simply stay green.
**`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`.
To rename: edit the canonical block at the top of the script, run it, and fix everything
it reports. The placeholder spellings are pre-seeded into its `STALE` list, and each one
arms itself as soon as you change the matching canonical value — so leftovers surface
without you having to track them. It also asserts `VST3_CLASS_ID` is exactly 16 bytes and
that `CLAP_ID` is reverse-DNS safe, both of which are otherwise a compile error or a
silent identity change between machines.
**`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.
Checks for files the template doesn't ship (e.g. a `deploy.ps1`) report as `skip` and
start enforcing once you add them.
Three things it will refuse or warn about, all learned the hard way:
- **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.
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.
Checks for files the template doesn't ship (a `deploy.ps1`, say) report as `skip` and start
enforcing once you add them.
## Build
@@ -105,7 +119,9 @@ 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
check-branding.sh # Asserts the plugin's identity strings agree everywhere (see Renaming)
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
.gitattributes # Pins *.sh to LF so Windows checkouts keep a valid shebang
.github/workflows/ # CI: branding check, both feature sets build, test, bundle
```