Actonos Release Agent Skill

ActonOS Release Skill

Use this skill when creating releases for ActonOS — bumping versions, generating changelogs, tagging, and publishing artifacts.

Release Checklist

Before creating a release, ensure:

• [ ] All tests pass: make test
• [ ] Linters pass: make lint
• [ ] Build succeeds: make build
• [ ] CHANGELOG.md has entries under [Unreleased]
• [ ] Documentation is up to date
• [ ] No critical open issues for this version

Version Bump

Quick Commands

# Patch release (bug fixes): 0.1.0 → 0.1.1
make bump-patch

# Minor release (new features): 0.1.0 → 0.2.0
make bump-minor

# Major release (breaking changes): 0.1.0 → 1.0.0
make bump-major

What Happens

The scripts/version-bump.sh script automatically:

• Reads current version from VERSION file
• Calculates new version
• Updates VERSION file
• Updates CHANGELOG.md:
• Moves [Unreleased] entries to [X.Y.Z] - YYYY-MM-DD
• Creates fresh [Unreleased] section
• Updates comparison links
• Creates git commit: chore(release): vX.Y.Z
• Creates annotated git tag: vX.Y.Z

Dry Run

Preview without modifying files:

bash scripts/version-bump.sh patch --dry-run

Changelog Management

Before Release

Add entries to CHANGELOG.md under [Unreleased]:

## [Unreleased]

### Added
- Multi-agent swarm delegation with configurable timeout (#42)
- Discord channel adapter (#38)

### Fixed
- FTS5 index corruption on concurrent writes (#35)
- Token refresh daemon race condition (#33)

### Changed
- Improved agent manifest validation error messages

Auto-Generate from Commits

# Generate entries from conventional commits since last tag
bash scripts/changelog-gen.sh

# Since a specific tag
bash scripts/changelog-gen.sh v0.1.0

# All commits
bash scripts/changelog-gen.sh --all

The script groups commits by type:

• feat → Added
• fix → Fixed
• refactor, docs, style, test, build, ci, chore → Changed
• Breaking changes (!) → Removed (with ⚠️ marker)

Full Release Workflow

Step 1: Prepare

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

# Verify everything passes
make lint
make test
make build

Step 2: Review Changelog

# Auto-generate changelog entries
bash scripts/changelog-gen.sh

# Review and edit CHANGELOG.md manually
# Add any missing entries, polish descriptions

Step 3: Bump Version

# Choose the appropriate bump type
make bump-minor  # or bump-patch / bump-major

Step 4: Push

# Push commit and tag
git push origin main --tags

Step 5: Build & Publish Artifacts

# Docker image
make docker
docker push actonos/actonos:$(cat VERSION)
docker push actonos/actonos:latest

# ISO (if releasing bare-metal)
make iso

Step 6: Create GitHub Release

• Go to GitHub → Releases → "Create new release"
• Select the tag vX.Y.Z
• Title: ActonOS vX.Y.Z
• Body: Copy the changelog section for this version
• Attach artifacts:
• build/actond (Linux AMD64 binary)
• build/ActonOS-vX.Y.Z.iso (if applicable)

Hotfix Release

For urgent fixes on a released version:

# 1. Create hotfix branch from the tag
git checkout -b hotfix/v0.2.1 v0.2.0

# 2. Apply the fix
# ... make changes ...
git commit -m "fix(memory): critical FTS5 corruption on write"

# 3. Bump patch version
bash scripts/version-bump.sh patch

# 4. Merge back to main
git checkout main
git merge hotfix/v0.2.1

# 5. Push
git push origin main --tags

# 6. Clean up
git branch -d hotfix/v0.2.1

Version Files Reference

| File | Purpose | Updated By |

|:---|:---|:---|

| VERSION | Source of truth | scripts/version-bump.sh |

| CHANGELOG.md | Release history | Manual + scripts/version-bump.sh |

| Go binary -ldflags | Embedded version | Makefile (reads VERSION) |

| Docker tag | Image version | Makefile (reads VERSION) |

| ISO filename | Image version | scripts/build-iso.sh (reads VERSION) |

Pre-1.0 Policy

While in 0.x.y:

• MINOR bumps may include breaking changes (API is unstable)
• PATCH bumps are always backward-compatible
• Document breaking changes clearly in CHANGELOG under Removed or Changed

After 1.0.0:

• Strict SemVer compliance
• Breaking changes require MAJOR bump
• Deprecation warnings for at least 1 minor version before removal

Reference Files

• docs/VERSIONING.md — Versioning strategy
• docs/CONTRIBUTING.md — Release section
• scripts/version-bump.sh — Version bump script
• scripts/changelog-gen.sh — Changelog generator
• Makefile — Build and release targets