MSaving

Releases

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

The project doesn’t run MSaving anywhere and publishes no images: operators build each release from their own checkout. A release is a version tag on main of the msaving 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).
  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: fixes only. MINOR: new features, new migrations, new API routes. MAJOR: something operators must do by hand, or /v2. 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.

Edit this page · Report a problem