Releasing your firmware
Versions, release notes, and getting listed in Launchpad and the web flasher.
How to get a firmware from your computer to other people’s pedals: give it a version, publish an image, and list it in the catalog so Launchpad and the web flasher offer it.
Before the first release
- Your own repository, best started from the firmware template. It builds and tests every push and publishes releases.
- An
idof your own infirmware.json, never the template’smy-effect. It names your firmware’s storage on the pedal, so keep it forever: a new id makes everyone’s saved settings disappear. Claim it early in the catalog with a listing that has no releases yet. - A licence (a
LICENSEfile, and its name infirmware.json). - Parameter names you’re happy with. Saved settings are matched by name, so renaming a parameter later starts it at its default for everyone. Adding, removing and reordering parameters is fine.
A release
- Version: raise
versioninfirmware.json:1.0.0→1.0.1for fixes,1.1.0for new things,2.0.0for something incompatible. Pre-releases:1.1.0-beta.1. - Platform: move the
opengp5submodule to the OpenGP5 release you built and tested with (for examplegit -C opengp5 checkout v0.8.0-alpha), and set"platform"to itsmajor.minor. - Test it:
./test.sh: the simulator with your controls script;./build.sh;- on the pedal: the heaviest settings while
gp5_link.py statusruns, a power-off and back (do the settings survive?), and an update from your last release (do they still?).
- Tag and push:
git tag v1.0.1 && git push --tags. The template’s workflow builds the image and publishes it on your repository’s Releases page asGP-5_<id>.bin. - List it: add the release to
catalog/<id>.jsonin OpenGP5, newest first.python3 tools/catalog.py release GP-5_<id>.bin <its download URL>prints the entry from the image itself. Then runpython3 tools/catalog.py checkandindex, and open a pull request. CI downloads your release and checks it.
Writing the release notes
People flash this onto a pedal they love. Tell them:
- what’s new and what’s fixed, in plain words;
- whether their settings and presets carry over (they do, unless you renamed parameters or changed the id);
- what it was tested on;
- how to go back: the previous release stays listed, and recovery works as always.
Good practice
- Build from a clean checkout of your tag. The template’s CI does, and its image is byte-identical to a local build, so anyone can check it.
- Keep older releases listed in the catalog, so people can go back.
- Answer issues on your repository: bugs in a catalog firmware belong there, not in OpenGP5.