brainy/RELEASE-GUIDE.md

Brainy Release Guide

Version Numbering Rules (Semantic Versioning)

For Brainy, we follow this pattern:

• PATCH (2.3.0 → 2.3.1): Bug fixes, internal improvements, dependency updates
• MINOR (2.3.0 → 2.4.0): New features, enhancements, non-breaking changes
• MAJOR (2.x.x → 3.0.0): ONLY when we completely change the API

IMPORTANT: Breaking Changes ≠ Major Version

BREAKING CHANGE in commit messages triggers MAJOR version bumps!

• DO NOT use "BREAKING CHANGE" unless users need to rewrite their code
• Internal changes (like removing tar-stream) are NOT breaking changes
• API additions are NOT breaking changes
• Performance improvements are NOT breaking changes

Commit Message Guidelines

✅ CORRECT Examples:

# New features → MINOR bump
git commit -m "feat: add new model delivery system"

# Bug fixes → PATCH bump
git commit -m "fix: resolve model download timeout"

# Internal improvements → PATCH bump
git commit -m "refactor: simplify model manager logic"
git commit -m "perf: optimize model caching"
git commit -m "chore: remove unused dependency"

❌ AVOID These Mistakes:

# DON'T use BREAKING CHANGE for internal changes
git commit -m "feat: improve model delivery

BREAKING CHANGE: removed tar-stream dependency"  # WRONG! This triggers v3.0.0

Release Workflow Checklist

Before Committing:

• Review commit message - no "BREAKING CHANGE" unless API changes
• Consider: Will users need to change their code? If NO → Not breaking

Release Commands:

# Let standard-version figure it out from commits
npm run release              # Recommended - auto-detects version

# Or be explicit:
npm run release:patch        # 2.4.0 → 2.4.1 (fixes)
npm run release:minor        # 2.4.0 → 2.5.0 (features)
npm run release:major        # 2.4.0 → 3.0.0 (API changes only!)

After Release:

git push --follow-tags origin main
npm publish
gh release create $(git describe --tags --abbrev=0) --generate-notes

When to Use Major Version (3.0.0)

ONLY when we make changes like:

• Removing methods from the public API
• Changing method signatures (parameters, return types)
• Renaming public methods
• Changing default behaviors that break existing code

Examples:

• ❌ search(query, limit, options) → search(query, options) (major)
• ✅ Adding find() method (minor - doesn't break existing code)
• ✅ Internal refactoring (patch - users don't see it)

Quick Decision Tree

1. Does this fix a bug? → PATCH (fix:)
2. Does this add new functionality? → MINOR (feat:)
3. Will users' existing code break? → MAJOR (with BREAKING CHANGE)
4. Is it internal/maintenance? → PATCH (chore:/refactor:/perf:)

Emergency: If Wrong Version is Released

# 1. Deprecate wrong version on npm
npm deprecate @soulcraft/brainy@X.X.X "Incorrect version - use Y.Y.Y"

# 2. Fix version in package.json
# 3. Republish correct version
npm publish

# 4. Delete wrong GitHub tag/release
git push origin :vX.X.X
gh release delete vX.X.X --yes

# 5. Create correct tag/release
git tag vY.Y.Y
git push --tags
gh release create vY.Y.Y --generate-notes

Remember:

• Most releases should be MINOR or PATCH
• Major versions should be RARE
• When in doubt, it's probably MINOR
• NEVER use "BREAKING CHANGE" for internal changes