oh-my-opencode-slim/docs/release.md

Release Process

This project has two related release tracks:

• Plugin release: the npm package version from package.json, tagged as v<version> and published to npm.
• Companion release: native desktop binaries, tagged as companion-v<version> and uploaded as GitHub Release assets.

The companion uses separate versioning so the plugin can ship patches without rebuilding native binaries every time.

1. Inspect the release diff

Before writing release notes, inspect the actual changes between the previous plugin tag and the new plugin tag or release branch state.

git log --oneline --decorate v2.0.0..HEAD
git diff --stat v2.0.0..HEAD
git diff --name-only v2.0.0..HEAD

Use that diff to write the GitHub release body. Do not rely on memory.

Recommended release note sections:

• Added
• Changed
• Fixed
• Docs
• CI
• Compatibility / migration notes
• Publish notes

2. Choose versions

Pick versions independently:

plugin: 2.0.3
plugin tag: v2.0.3

companion: 0.1.3
companion tag: companion-v0.1.3

Use a plugin patch release for ordinary bug fixes and release-process fixes. Only bump the companion when the Rust companion changes or the plugin expects a new companion state protocol or asset set.

3. Update companion references

When releasing a new companion binary, update the packaged companion manifest:

// src/companion/companion-manifest.json
{
  "version": "0.1.3",
  "tag": "companion-v0.1.3",
  "repo": "alvinunreal/oh-my-opencode-slim",
  "checksums": {
    "oh-my-opencode-slim-companion-v0.1.3-aarch64-apple-darwin.tar.gz": "..."
  }
}

The installer and updater read the packaged JSON manifest at runtime. Keep the matching fallback constant in src/companion/updater.ts synchronized with the JSON manifest; tests cover this sync.

Also update the Rust crate version:

# companion/Cargo.toml
version = "0.1.3"

Regenerate or update companion/Cargo.lock so the package entry matches.

Update companion documentation in:

• docs/companion.md
• docs/configuration.md

Supported companion workflow target names:

macos-arm64
macos-x64
linux-x64
linux-arm64
windows-x64

Expected release asset names for companion 0.1.3:

oh-my-opencode-slim-companion-v0.1.3-aarch64-apple-darwin.tar.gz
oh-my-opencode-slim-companion-v0.1.3-x86_64-apple-darwin.tar.gz
oh-my-opencode-slim-companion-v0.1.3-x86_64-unknown-linux-gnu.tar.gz
oh-my-opencode-slim-companion-v0.1.3-aarch64-unknown-linux-gnu.tar.gz
oh-my-opencode-slim-companion-v0.1.3-x86_64-pc-windows-msvc.zip

4. Build and publish companion assets

Trigger the manual workflow:

gh workflow run companion-release.yml \
  -f version=0.1.3 \
  -f targets=macos-arm64,macos-x64,linux-x64,linux-arm64,windows-x64

Watch the run:

gh run list --workflow companion-release.yml --limit 5
gh run watch <run-id>

Verify the companion release:

gh release view companion-v0.1.3

Download assets for a local sanity check:

mkdir -p /tmp/companion-v0.1.3-assets
gh release download companion-v0.1.3 \
  --dir /tmp/companion-v0.1.3-assets

Confirm the asset list matches the installer targets before publishing the plugin package that points to this companion tag.

Copy each asset's SHA256 digest into src/companion/companion-manifest.json. GitHub release asset metadata reports these as digest: sha256:<hash>; store only the hash value in the manifest. Then mirror the same values in the fallback COMPANION_MANIFEST constant in src/companion/updater.ts.

Manual companion upload fallback

If the workflow builds artifacts successfully but the release upload step fails, download the workflow artifacts and upload them manually:

gh run download <run-id> \
  --dir /tmp/companion-v0.1.3-assets

gh release create companion-v0.1.3 \
  --title "Companion v0.1.3" \
  --notes "Manual companion binary release for oh-my-opencode-slim." \
  /tmp/companion-v0.1.3-assets/*

If the release already exists, upload with clobber:

gh release upload companion-v0.1.3 \
  /tmp/companion-v0.1.3-assets/* \
  --clobber

Then verify:

gh release view companion-v0.1.3

5. Bump the plugin package

For a stable patch, update package.json:

{
  "version": "2.0.3"
}

If you manually edit the version, do not later run bun run release:patch or npm version patch, because that would bump the package again.

If you have not manually edited the version, use npm's version command instead:

npm version patch

That creates the version commit and v<version> tag automatically.

6. Verify before tagging or publishing

Run the standard checks:

bun run check:ci
bun run typecheck
bun test
bun run build

Skill Synchronization Hashes Gate

If this release changes any bundled skill content (under src/skills/), you must populate the LEGACY_MANAGED_SKILL_HASHES table in src/hooks/auto-update-checker/skill-sync.ts with the hashes of the previously published versions of those skills (obtained from published npm package tarballs). This ensures existing users' installations are adopted and upgraded safely. If this is a migration-only release without skill changes, confirm the table is kept as-is.

Before committing or tagging, inspect:

git status --short
git diff
git log --oneline -10

7. Commit and push release prep

Stage only intended files. Typical files for a companion-backed plugin patch:

.github/workflows/companion-release.yml
companion/Cargo.toml
companion/Cargo.lock
docs/companion.md
docs/configuration.md
package.json
src/companion/companion-manifest.json
src/companion/updater.ts

Commit and push:

git add <intended-files>
git commit -m "chore: prepare companion 0.1.3 release"
git push

8. Create and push the plugin tag

If npm version created the tag, push it:

git push --follow-tags

If the package version was edited manually, create and push the tag yourself:

git tag -a v2.0.3 -m "v2.0.3"
git push origin v2.0.3

Verify the tag exists remotely:

git ls-remote --tags origin v2.0.3

9. Create the GitHub plugin release

Use release notes based on the actual git diff.

gh release create v2.0.3 \
  --title "v2.0.3" \
  --notes-file /tmp/oh-my-opencode-slim-v2.0.3-notes.md

If a release already exists, update it:

gh release edit v2.0.3 \
  --title "v2.0.3" \
  --notes-file /tmp/oh-my-opencode-slim-v2.0.3-notes.md

Verify:

gh release view v2.0.3

10. Publish npm

Publishing is the final step and requires npm authentication:

npm login
npm publish

After publishing, verify the package version:

npm view oh-my-opencode-slim version

11. Current v2.0.3 release checklist

For the 2.0.3 / companion-v0.1.3 release, the completed state should be:

• package.json version is 2.0.3.
• src/companion/companion-manifest.json points to companion-v0.1.3.
• Git tag v2.0.3 exists on origin.
• GitHub release v2.0.3 exists.
• GitHub release companion-v0.1.3 exists with the expected assets.
• Working tree is clean.
• bun run check:ci, bun run typecheck, bun test, and bun run build pass.
• npm publish is run only after the GitHub release and companion assets are ready.