Deploy Process

indexion Release Process

Prerequisites

• .gitmodules has pushRecurseSubmodules = on-demand for all submodules
• scripts/sync-version.sh exists and syncs moon.mod.json → version.mbt + marketplace.json + plugin.json

Version Convention

• SoT: moon.mod.json → "version" field
• Semver: MAJOR.MINOR.PATCH
• Tags: v{VERSION} (e.g. v0.8.0)
• Propagation targets:
  • src/update/version.mbt → current_version constant
  • skills/.claude-plugin/marketplace.json → "version" field
  • skills/.claude-plugin/plugin.json → "version" field

Release Steps

1. Commit feature changes

Commit all feature/fix changes BEFORE the version bump. The release commit should contain ONLY version changes.

If submodules have changes:

# kgfs submodule
cd kgfs && git add -A && git commit -m "feat: ..." && cd ..

# skills submodule
cd skills && git add -A && git commit -m "feat: ..." && cd ..

# Parent: stage submodule refs + changed files
git add kgfs skills src/ cmd/ ... && git commit -m "feat: ..."

2. Update RELEASE_NOTES.md

Prepend release notes for the new version at the top of RELEASE_NOTES.md:

# vX.Y.Z

## Highlights

- **Feature A** — Brief description
- **Feature B** — Brief description

## New Features

### Feature A

Detailed description...

## Improvements

- Item 1
- Item 2

## Bug Fixes

- Fix 1
- Fix 2

---

# vX.Y-1.Z (previous version header follows)

Use git log vPREV..HEAD --oneline to review commits since last release.

3. Run local verification

Before bumping version, verify all checks pass locally:

# MoonBit tests
moon test --target native

# TypeScript tests
bun run test

# Lint
bun run lint

4. Bump version in moon.mod.json

Edit moon.mod.json and change the "version" field:

• +0.0.1 for patches (bug fixes)
• +0.1.0 for minor (new features, backward compatible)
• +1.0.0 for major (breaking changes)

5. Run sync-version.sh

bash scripts/sync-version.sh

This propagates the version to version.mbt and marketplace.json.

6. Commit version in skills submodule

marketplace.json lives inside the skills submodule, so it needs its own commit:

cd skills && git add .claude-plugin/marketplace.json .claude-plugin/plugin.json && git commit -m "release: vX.Y.Z" && cd ..

7. Create release commit (WITHOUT tag)

git add moon.mod.json src/update/version.mbt skills RELEASE_NOTES.md
git commit -m "release: vX.Y.Z"

DO NOT create the tag yet.

8. Push and wait for CI

git push

push.recurseSubmodules = on-demand ensures:

1. kgfs submodule is pushed first
2. skills submodule is pushed second
3. Parent is pushed last

Wait for CI to pass on GitHub Actions. Check the workflow status before proceeding.

9. Create and push tag (after CI passes)

Only after CI passes:

git tag -a vX.Y.Z -m "release: vX.Y.Z"
git push origin vX.Y.Z

Use git tag -a (annotated tag) for proper release semantics.

Push Safety

The .gitmodules file enforces pushRecurseSubmodules = on-demand for all submodules. This is a repository-level setting that applies to every clone.

Additionally, .git/config has the same setting as a local override. Both are needed:

• .gitmodules: shared across clones (checked into git)
• .git/config: applies immediately to the current working copy

Verification

After push, verify:

# Tags are consistent
git tag --sort=-v:refname | head -1  # should be vX.Y.Z

# Submodules point to pushed commits
git submodule status  # no + prefix = clean

# Version is consistent across all targets
grep '"version"' moon.mod.json
grep 'current_version' src/update/version.mbt
grep '"version"' skills/.claude-plugin/marketplace.json
grep '"version"' skills/.claude-plugin/plugin.json

Rollback

If CI fails after pushing the release commit:

# Fix the issue locally
# Commit the fix
git add ... && git commit -m "fix: ..."

# Push the fix
git push

# Wait for CI to pass, then proceed to step 9

If the tag was already pushed and needs to be removed:

# Remove tag from remote
git push origin :refs/tags/vX.Y.Z

# Remove tag locally
git tag -d vX.Y.Z

# After fixing issues, recreate the tag on the correct commit
git tag -a vX.Y.Z -m "release: vX.Y.Z"
git push origin vX.Y.Z

DO NOT

• Do NOT create the tag before CI passes
• Do NOT amend the release commit after pushing
• Do NOT force-push to main
• Do NOT skip sync-version.sh — manual version editing causes drift
• Do NOT push parent before submodules — on-demand handles this, don't override

Source: trkbt10/indexion — distributed by TomeVault.