Release · licence · catalog
Ship
Shipping is four artefacts and one decision: what licence the code must have. Then a pull request with one JSON file.
The four artefacts
| Artefact | Made by | Notes |
|---|---|---|
| the plugin folder | your build | .so + skin + version.xml |
| one zip | tools/release.py | installer, uninstaller, INSTALL.md, manifest, SHA256SUMS |
tested.json | you | device, firmware, date — this is what makes a listing “Verified” |
| catalog entry | a PR | catalog/plugins/<id>.json, no versions or checksums inside |
Version numbers are a convention, not a style
vst.json carries an integer: 1010 is 1.0.1
(major*1000 + minor*100 + patch*10). Get it wrong and the release says 1.0.0 while the
plugin inside says 1.0.1 — nobody notices until a bug report quotes the wrong version.
Licence decides what you can publish
- Check the vendored code’s own licence file, not a catalog field; they disagree in this ecosystem.
- GPL is viral: a GPL core makes the plugin GPL-3.0-only. That is fine — it just has to be stated and the source has to be public.
- Ship a root
LICENSEwith an SPDX-identifiable text, aTHIRD_PARTY_NOTICESnaming upstream commits and your local changes, and no manufacturer assets (no stock skins, no logos, no product art). - If you build from firmware-derived material, you must not publish a zip at all — the catalog has a build-yourself path for that.
Release, without gh
# tag + release
POST /repos/<owner>/<repo>/releases {"tag_name":"v1.0.1","name":"…","body":"…"}
# asset
POST https://uploads.github.com/repos/<owner>/<repo>/releases/<id>/assets?name=<zip>
# verify the upload against your local hash
sha256sum dist/<zip> == the "digest" the API returns
Releases are immutable in practice: never re-upload under an existing tag, cut a new one.
Before anything becomes public
- Export, do not publish the working tree. Build a folder with source, docs,
LICENSE, README,
tested.json; leave out internal notes, build output and device screenshots of things you removed. - Strip what is private but not secret: device IPs, host paths, personal
hostnames. Turn hardcoded IPs in scripts into
${DEVICE:?set DEVICE}. - Run a check.
tools/publish-check/check.sh <export>must exit 0. It catches addresses and paths that secret scanning does not. - Verify the push. A push that printed a normal line left our first repository
empty. Ask the API for
/contentsor/commitsbefore believing it.
The catalog PR
{ "id": "mpc-multihead-echo", "name": "MPC Multihead Echo", "author": "you",
"repo": "you/mpc-vst-multihead-echo", "kind": "effect", "license": "GPL-3.0-only",
"summary": "One line, descriptive.",
"screenshot": "https://raw.githubusercontent.com/you/…/<commit>/docs/panel.png",
"style": "delay", "tags": ["tape-echo","delay"] }
Validate it locally first: python3 tools/catalog_build.py --check-registry and
python3 tools/catalog_check.py <zip> --catalog. Then one PR adding that file. CI
checks the entry and your latest release; new releases appear on their own afterwards.
The one warning you will get
catalog_check flags a .so that calls socket/bind/accept.
If that is the companion screen, say so in the release notes and the PR: what it serves, that it
never sends anything outbound, and which environment switch turns it off. An explained warning is
not a problem; an unexplained one is a question the maintainer has to ask.
What a good listing says
- Tested on a named device, firmware and date — and the truth about what was not tested.
- Bench figure, because “optimised” without a number is a wish.
- Limits: what it cannot do, and what it depends on.
- Credit for anything you borrowed — an idea counts, and saying where it came from costs one paragraph.