Skip to content

RELEASE.md

Latest commit

 

History

History
257 lines (191 loc) · 6.81 KB

RELEASE.md

File metadata and controls

257 lines (191 loc) · 6.81 KB

Release Process

This document describes the release process for Semiont.

Overview

Semiont uses a two-step release process:

  1. Release workflow — Tags the version and publishes all npm packages
  2. release:bump — Bumps the version for the next development cycle

Step 1: Publish a Stable Release

The Release workflow handles tagging and npm publishing.

From the GitHub UI

  1. Go to Actions > Release in the repository: https://github.com/The-AI-Alliance/semiont/actions/workflows/release.yml
  2. Click Run workflow
  3. Optionally check Dry run to build without publishing
  4. Click the green Run workflow button
  5. Monitor the run — the tag and npm publish jobs appear as nested steps

From the command line

# Live release
gh workflow run release.yml

# Dry run (builds but does not publish)
gh workflow run release.yml --field dry_run=true

Monitor progress:

# List recent runs
gh run list --workflow=release.yml --limit=3

# Watch a specific run
gh run watch <run-id> --exit-status

What the release workflow does

  1. Verifies version sync across all package.json files
  2. Creates and pushes a git tag v{version} (skips if already exists)
  3. Creates a GitHub Release with auto-generated release notes from commits and merged PRs
  4. Publishes npm packages — all @semiont/* libraries, CLI, backend, and frontend

Step 2: Bump Version for Next Cycle

After the release completes, bump the version for the next development cycle:

./scripts/release/version-bump.sh patch  # Bug fixes (0.4.9 → 0.4.10)
./scripts/release/version-bump.sh minor  # New features (0.4.9 → 0.5.0)
./scripts/release/version-bump.sh major  # Breaking changes (0.4.9 → 1.0.0)
./scripts/release/version-bump.sh        # Interactive prompt

This script:

  • Bumps the version in version.json
  • Syncs to all package.json files
  • Commits (signed) and pushes to main

Version Management Scripts

npm run version:show    # Display current version across all packages
npm run version:sync    # Sync version.json to all package.json files
npm run version:bump    # Bump version (patch/minor/major)
npm run version:set     # Set a specific version

Package manifest: version.json

version.json is the workspace's single source of truth for the package list. Every script that walks the package set reads from it:

  • scripts/dev/build-packages.js — build orchestrator (used by npm run build)
  • scripts/ci/build.sh — CI build (libraries + apps in dependency order)
  • scripts/ci/publish.sh — version stamping + npm publish
  • scripts/release/version-bump.sh and scripts/release/version.mjs — version management
  • .github/workflows/publish-npm-packages.yml — release-summary readout

Each entry in version.json.packages looks like:

"@semiont/core": {
  "dir": "packages/core",
  "version": "0.4.22",
  "publish": true
}

Optional stage field for apps that publish from a staging directory (currently semiont-backend and semiont-frontend):

"semiont-backend": {
  "dir": "apps/backend",
  "stage": ".npm-stage/backend",
  "version": "0.4.22",
  "publish": true
}

Insertion order in the packages object is the build order — list each package after its dependencies.

Adding a new workspace package

  1. Create the package directory and its package.json as usual.
  2. Add an entry to version.json in the right dependency-order position, with publish: true if it should ship to npm or publish: false for internal packages (test helpers, MCP integration, the desktop app).
  3. That's it. Every script picks it up automatically — no other list to update.

If you forget step 2, local-build.sh will silently skip the package, the npm install for any consumer will 404, and you'll waste an hour chasing it. (Speaking from experience.)

Complete Release Example

# 1. Ensure you're on main with latest changes
git checkout main
git pull

# 2. Check current version and run tests
npm run version:show
npm test

# 3. Publish stable release
gh workflow run release.yml

# 4. Monitor until complete
gh run list --workflow=release.yml --limit=1
gh run watch <run-id> --exit-status

# 5. Bump version for next development cycle
./scripts/release/version-bump.sh patch

Version Numbering

Stable Releases

  • Format: X.Y.Z (e.g., 0.4.9)
  • Published with npm tag latest
  • Tagged in git as vX.Y.Z

Development Builds

  • Format: X.Y.Z-build.N (e.g., 0.4.10-build.1)
  • Published with npm tag dev
  • Build number increments with each CI run

Publishing Channels

npm Packages

Stable releases:

npm install @semiont/core@latest
npm install @semiont/cli@latest
npm install @semiont/backend@latest
npm install @semiont/frontend@latest

Development builds:

npm install @semiont/core@dev
npm install @semiont/cli@dev
npm install @semiont/backend@dev
npm install @semiont/frontend@dev

View all versions:

Version Bump Guidelines

Patch Version (X.Y.Z → X.Y.Z+1)

Use for:

  • Bug fixes
  • Documentation updates
  • Dependency updates (non-breaking)
  • Performance improvements

Minor Version (X.Y.Z → X.Y+1.0)

Use for:

  • New features (backward compatible)
  • New APIs or commands
  • Significant improvements
  • New platform support

Major Version (X.Y.Z → X+1.0.0)

Use for:

  • Breaking API changes
  • Major architectural changes
  • Incompatible configuration changes
  • Removal of deprecated features

Troubleshooting

Release workflow fails

  1. Check the run in GitHub Actions: https://github.com/The-AI-Alliance/semiont/actions/workflows/release.yml
  2. Expand the failed child job to see which step failed
  3. Re-run failed jobs from the parent run page

Version mismatch error

The tag job verifies all packages match version.json. If they don't:

npm run version:sync
git add -A && git commit -m "sync versions" && git push

Manual release (emergency)

If the workflow is broken, you can tag and trigger manually:

# 1. Create and push tag
git tag v0.4.9
git push origin v0.4.9

# 2. Trigger release
gh workflow run release.yml

Release Checklist

Before releasing:

  • All tests passing
  • No uncommitted changes
  • On main branch with latest changes
  • Version in version.json is correct

After releasing:

  • Verify npm packages published (including @semiont/backend and @semiont/frontend)
  • Test installation: npm install -g @semiont/cli@latest && semiont init && semiont provision
  • Bump version for next cycle: ./scripts/release/version-bump.sh

Questions?

For questions about the release process: