Releases and upgrades
Cutting a release
Releases are tags named version-<x.y.z> (for example version-0.3.3). Pushing one runs the Release workflow, which:
- Derives the version by stripping
version-. - Builds static binaries for
linux/amd64anddarwin/arm64withscripts/build-release.sh, stamping the version into the binary, and writesSHA256SUMS. - Checks that the built binary reports the version.
- Creates a GitHub release with the tarballs, checksums, and generated notes.
Use an annotated tag. Its annotation becomes the release’s upgrade notes, so an operator-visible change, such as a new or newly enforced environment variable, travels with the tag:
git tag -a version-0.4.0 -m "Requires DAGNATS_LOOP_STATE_MAX_BYTES=524288 on the sidecar."
git push origin version-0.4.0An unannotated tag still releases, with no upgrade notes. These docs read the latest version-* tag at build time to show the current version.
A binary built any other way reports 0.0.0-dev, which makes a running instance unable to say what it is. Build with scripts/build-release.sh <version> [os/arch …], which is also what the workflow runs.
Upgrading
- Read the upgrade notes of every release between yours and the target.
- Back up the database (Backups).
- Run
notify validate-stepswith the new binary against the database. Some releases tighten workflow rules, rejecting forms that older versions accepted (for example a dynamic delay must now declaredynamicKind, and a scheduled digest’s cron must be the 5-field form). This lists the affected workflows before you deploy rather than after. - Upgrade the dagnats sidecar if the new notify pins a newer one.
- Replace the binary and restart. Schema migrations run at start. Workflows are re-registered with the engine automatically.
- Check
/healthzfor the new version and/readyzfor readiness.
The HTTP API follows an additive contract: within Notify-Contract: 1, routes and fields are added but not removed or reinterpreted.
Upgrade note: verified phones for SMS (#130)
The release that adds phone verification stops existing SMS workflows from sending until you act:
- Every existing subscriber phone becomes unverified. An
smsstep texts only a phone the subscriber verified themselves, so until they do, every sms step is skipped withskipReason: "no_verified_phone". Nothing fails; the other steps of the run still go out. - SMS is off by default for a subscriber with no SMS preference. An existing sms step has no
defaultEnabled, so it sends only to subscribers who turned SMS on for that workflow.
To restore SMS:
- On each workflow that should text people without an opt-in (sign-off requests, for example), set
"defaultEnabled": trueon the sms step, or tick Send when the subscriber has no SMS preference in the console’s step editor. - Have each subscriber verify their phone from your app: mint a subscriber session and call
POST /v1/me/phone/verification, then.../confirmwith the code they receive. There is no way to mark a phone verified from your backend; that is the point of the change.
Stored phones are also normalised to E.164 on their next write, so +1 (555) 111-2222 is stored as +15551112222. A phone that is not a valid E.164 number is stored as written and can never be verified.