Versioning and releases

FORGE Studio follows Semantic Versioning 2.0.0. A version is MAJOR.MINOR.PATCH, optionally followed by a prerelease tag: 0.3.0, 0.3.0-alpha.3, 0.4.0-beta.1.

Where the version lives

package.json "version" is the only place the version is written. Everything else reads it:

Consumer	How it uses the version
electron-builder	Artifact names (FORGE Studio-0.3.0-alpha.3-arm64.dmg) and the DMG title
The app	app.getVersion(): Settings → About, the update check, pack compatibility
Packs	A pack's min_studio_version is compared against it at install time
Auto-updates	electron-updater reads the update channel from the prerelease tag (alpha → alpha-mac.yml)
Git	The release tag is v + the version (v0.3.0-alpha.3)

npm run release:check (run in CI) fails if package.json holds something that is not a release version, or if package-lock.json disagrees with it. The Release workflow additionally refuses a tag that does not equal v<package.json version>, or a version with no CHANGELOG.md section.

What counts as a breaking change

The public surface of FORGE Studio is what users and pack authors depend on:

• the workflow YAML schema (schema_version, stage and parameter fields);
• the pack format: manifest.yaml, the module calling conventions for MATLAB, Python and Julia modules, and the stage config files Studio writes for them;
• files Studio writes that users keep: job outputs, history, settings;
• the CLI and Yarra/batch entry points.

A change that makes an existing workflow, pack or saved job stop working, or silently changes its results, is breaking. UI layout changes are not.

Which number to bump

FORGE Studio is pre-1.0, so per SemVer the rules shift down one place:

Change	Before 1.0	From 1.0
Breaking change (see above)	MINOR (0.3.x → 0.4.0)	MAJOR
New feature, backwards compatible	MINOR	MINOR
Bug fix only	PATCH (0.3.0 → 0.3.1)	PATCH

A pack that needs a feature added in 0.4.0 sets min_studio_version: "0.4.0". Prerelease builds of a line satisfy that line's minimum, so 0.4.0-alpha.2 can install it too.

Prereleases

Prereleases are alpha.N or beta.N, counting from 1. No other prerelease tags (rc.1, dev, alpha without a number): electron-updater turns the first identifier into the channel file name, and the Release workflow uploads only the latest, alpha and beta channel files.

• alpha: feature work still landing; may break between alphas.
• beta: feature-complete for the line; fixes only.

A line usually runs 0.4.0-alpha.1 … 0.4.0-beta.1 … 0.4.0. SemVer orders them that way: 0.4.0-alpha.9 < 0.4.0-beta.1 < 0.4.0. A tag with a prerelease tag becomes a GitHub prerelease; a plain vX.Y.Z becomes a full release.

Cutting a release

1. Make sure everything going out is described under ## [Unreleased] in CHANGELOG.md.

2. On a branch off main, bump the version:

   npm run release:bump -- alpha      # 0.3.0-alpha.2 -> 0.3.0-alpha.3
   npm run release:bump -- beta       # 0.3.0-alpha.3 -> 0.3.0-beta.1
   npm run release:bump -- release    # 0.3.0-beta.2  -> 0.3.0
   npm run release:bump -- patch      # 0.3.0 -> 0.3.1
   npm run release:bump -- minor      # 0.3.1 -> 0.4.0  (also 0.3.0-alpha.3 -> 0.4.0)
   npm run release:bump -- 0.4.0-alpha.1   # start a new prerelease line

   This updates package.json and package-lock.json and moves the [Unreleased] notes under a dated ## [<version>] heading. It refuses to go backwards, to use an unsupported prerelease tag, or to release with an empty [Unreleased] section.

3. Open a release: v<version> PR, get it green, and squash-merge it.

4. Tag the merge commit on main and push the tag:

   git tag v0.3.0-alpha.3 <merge-commit>
   git push origin v0.3.0-alpha.3

   The tag starts the Release workflow, which builds every platform and creates a draft GitHub Release. Publish the draft when the artifacts are checked; installed apps see the update only after that.

Tags are never moved or reused. If a release is broken, fix it and release the next version.

Bundled engines

Studio pins the engines it bundles in build.config.json: FORGE by release tag (v0.13.1), Sentinel by commit. Bumping a bundled engine is a Studio change like any other: a FORGE minor bump that changes reconstruction defaults is at least a Studio minor bump, and the changelog says which engine version ships. FORGE's own versioning is described in its repository (RELEASING.md).