Set your Sage version compatibility

Do not mix up the version fields

version identifies your app release. It is required app metadata, but it does not decide whether Sage sees an update. Sage compares the finalized manifest and its hash, so any finalized manifest change can produce an update without changing version.

manifestVersion identifies the Sage manifest file format. It is not your app version or the Sage release you support. It currently defaults to 0, so a version 0 manifest can omit it.

sageVersion.min and sageVersion.testedMax describe compatibility with Sage itself. min is the hard lower boundary; testedMax is an optional upper testing boundary.

Declare the compatibility range

Set sageVersion.min to the oldest Sage release that provides every API, capability, and behavior your app requires. Set sageVersion.testedMax to the newest Sage release on which you have actually tested the app.

Both values must be complete semantic versions such as 0.13.0. When testedMax is present, it must be greater than or equal to min.

{
  "version": "1.4.0",
  "sageVersion": {
    "min": "0.13.0",
    "testedMax": "0.14.0"
  }
}

Know what Sage enforces

If the user runs a Sage version below min, Sage blocks installing, updating to, or launching that app version. A blocked update leaves the currently installed app unchanged.

The range is inclusive. With min set to 0.13.0 and testedMax set to 0.14.0, both boundary releases are compatible. A Sage release newer than testedMax produces a compatibility warning and requires review instead of being applied automatically, but the user can still install, update, and launch the app.

If testedMax is omitted, Sage applies no upper testing warning. An invalid semantic version, or a testedMax lower than min, makes the compatibility requirement invalid.

• Below min: blocked
• From min through testedMax: compatible
• Above testedMax: allowed with a warning

Choose boundaries from real requirements

Raise min only when a release starts depending on something older Sage versions do not provide. A rebuild, content change, or ordinary app release is not by itself a reason to raise it.

Advance testedMax after testing against a newer Sage release. Keeping it honest gives users a useful warning when they are ahead of the versions you have verified; omitting it means future Sage releases will be treated as compatible without that warning.

Test the boundaries before publishing

Test installation and launch on the exact min release and on the newest release you claim in testedMax. For an update, confirm that a compatible manifest applies normally and that an update requiring newer Sage does not replace the working installed version.

When practical, also check one release below min and one above testedMax. The first should be blocked with an upgrade requirement; the second should show a warning while still allowing the user to continue.