Releases

How a version gets to operators: the VERSION file, tags, and what a release must not break.

The project runs no Waterflow server for anyone else and publishes no images: operators build each release from their own checkout. A release is a version tag on main of the waterflow monorepo, made from the repository’s VERSION file.

Making a release

1. Everything for it is merged into dev, CI green, and tried with docker compose up -d --build from a clean checkout (and docker compose down -v first, so the migrations run from empty).
2. PR dev into main that also sets VERSION to the new version (1.2.0), merge.
3. On GitHub, Actions → Release → Run workflow on main. It runs .github/workflows/release.yml: the tests again, then the tag v1.2.0 (from VERSION) and a GitHub release with notes generated from the merged pull requests.
4. Edit the release notes into plain words: what operators and users will notice, and anything they must do (a new service in the compose file, a new setting). The same text goes into the Changelog, newest first, in the release’s docs PR; the release notes end with a link to it.
5. Servers’ admin pages show the new version within 6 hours (they read GitHub’s latest release); operators update with two commands or the one-click updater. Both build the new version on their machine.

Between releases dev keeps the last release’s VERSION, so a server built from dev reports that number.

Versions

MAJOR.MINOR.PATCH:

• PATCH (0.1.5 to 0.1.6): bug fixes only.
• MINOR (0.1.5 to 0.2.0): new features, with any migrations and API routes they bring.
• MAJOR (1.0.0, 2.0.0): a major release. 1.0.0 is the launch, released when the project owner decides Waterflow is truly ready; until then the first number stays 0. After it, a change operators must make by hand, or /v2, also takes a MAJOR.

Within /v1 the API only adds (mobile apps in the stores talk to servers several versions apart), and /v1/instance reports api_version.

What a release must not break

• Upgrades from any earlier release, skipping versions: migrations are additive and applied in order; a breaking schema change takes two releases (add and use the new thing, remove the old one later).
• Existing data: never edit a released migration.
• The operator’s .env: settings only get added, with safe defaults; never renamed or removed in a MINOR.
• The compose file: git pull updates it, but the one-click updater only restarts the services already running, with the helper’s own definition unchanged. A new service, or a change to the updater service, goes in the release notes (“run docker compose up -d once”), and the release must still work until they do.
• The operator’s checkout: operators shouldn’t edit tracked files (settings go in .env), so git pull stays a fast-forward. A new file can collide with an untracked one an operator made at the same path (git pull refuses to overwrite it): avoid that, or say in the release notes which file to delete first.