Skip to content

RELEASE.md

Latest commit

 

History

History
136 lines (94 loc) · 4.17 KB

RELEASE.md

File metadata and controls

136 lines (94 loc) · 4.17 KB

Release Process

OMA ships through GitHub Releases assets only. The root package.json.version is the single release base for both lanes.

Lanes

  • dev → alpha prerelease lane
  • main → stable release lane

Version Authority

  • package.json.version must always be a stable base version (x.y.z).
  • Alpha tags use v<base>-alpha.<n>.
  • Stable tags use v<base>.
  • Alpha numbering is derived from existing remote tags for the same base.
  • If an alpha/stable tag for the current commit already exists, workflows reuse it instead of creating a new tag.

Workflow Model

Local flow operator (release:flow)

Use this local script to inspect and validate release state before pushing or running CI:

bun run release:flow status [--json]
bun run release:flow status --refresh-refs [--json]
bun run release:flow check --lane alpha|stable|both [--json]

Add --refresh-refs when you want the report to fetch and evaluate origin/main, origin/dev, and tags before printing the result.

What it reports:

  • current branch + working-tree clean status
  • local main/dev branch heads and resolved versions
  • resolved alpha/stable tag target for the current workspace base
  • base version relation (same-base, post-stable-bump, drift, unknown)
  • whether main is contained in dev history (when determinable locally)

The check mode is intended for local validation only and can be run in JSON mode for automation: bun run release:flow check --lane both --json.

Shared CI

CI runs for pull requests plus pushes to dev and main.

Enforced checks:

  • bun run release:audit
  • bun run format:check
  • bun run lint
  • bun run typecheck
  • bun run test
  • bun run build
  • OMA_E2E=true bun test ./test/e2e/oma-workflow.e2e.ts when provider credentials are available

Alpha release (dev)

After a successful CI push run on dev:

  1. resolve the release base from package.json.version
  2. reuse any existing v<base>-alpha.<n> tag already pointing at HEAD
  3. otherwise create the next deterministic alpha tag
  4. create/update the GitHub prerelease
  5. upload tarballs, checksums, and Linux packages as release assets

Stable release (main)

After a successful CI push run on main:

  1. resolve the stable tag v<base> from package.json.version
  2. reuse the tag on reruns when it already points at HEAD
  3. create/update the GitHub release
  4. upload release assets
  5. bump dev to the next patch base so alpha numbering resets for the next cycle

Manual asset recovery

If a release already exists but asset upload needs to be rebuilt, run Release Assets with workflow_dispatch and pass tag_name.

Main merge policy

Main Source Policy rejects pull requests to main unless:

  • the head branch is exactly dev
  • the head repository is the same repository

This keeps stable releases sourced from the dev lane.

Distribution

Supported distribution paths:

  • install.sh
  • direct download from GitHub Releases assets
  • .deb / .rpm assets attached to GitHub Releases
  • oma upgrade from the stable lane by default or the alpha lane with --channel alpha

Unsupported distribution paths:

  • package-registry publishing
  • legacy release PR automation
  • package registry installs as a release channel

Operational Notes

Remote prerequisites still owned outside this repo change:

  • dev and main must exist remotely
  • workflow tokens must be allowed to push tags and the post-release dev bump commit
  • required checks/rulesets must later be aligned with the new CI and Main Source Policy workflow names

Release-sensitive files

Treat changes to these paths as release-sensitive:

  • package.json
  • install.sh
  • scripts/**
  • .github/workflows/**
  • .github/PULL_REQUEST_TEMPLATE.md
  • README.md
  • README.tr.md
  • RELEASE.md
  • docs/getting-started.md
  • docs/v2/release-evidence-matrix.md
  • packages/cli/src/commands/upgrade.ts
  • packages/cli/src/i18n.ts

Do Not

  • reintroduce package-registry publishing for OMA
  • reintroduce legacy release PR automation
  • create stable releases from branches other than main
  • merge to main from anything other than same-repo dev
  • store prerelease intent inside package.json.version