Versioning and Releases

BMad Method uses a simplified release system with manual control and automatic release notes generation.

🚀 Release Workflow

Command Line Release (Recommended)

The fastest way to create a release with beautiful release notes:

# Preview what will be in the release
npm run preview:release

# Create a release
npm run release:patch    # 5.1.0 → 5.1.1 (bug fixes)
npm run release:minor    # 5.1.0 → 5.2.0 (new features)
npm run release:major    # 5.1.0 → 6.0.0 (breaking changes)

# Watch the release process
npm run release:watch

One-Liner Release

npm run preview:release && npm run release:minor && npm run release:watch

📝 What Happens Automatically

When you trigger a release, the GitHub Actions workflow automatically:

✅ Validates - Runs tests, linting, and formatting checks
✅ Bumps Version - Updates package.json and installer version
✅ Generates Release Notes - Categorizes commits since last release:
- ✨ New Features (feat:, Feature:)
- 🐛 Bug Fixes (fix:, Fix:)
- 🔧 Maintenance (chore:, Chore:)
- 📦 Other Changes (everything else)
✅ Creates Git Tag - Tags the release version
✅ Publishes to NPM - With @latest tag for user installations
✅ Creates GitHub Release - With formatted release notes

📋 Sample Release Notes

The workflow automatically generates professional release notes like this:

## 🚀 What's New in v5.2.0

### ✨ New Features

- feat: add team collaboration mode
- feat: enhance CLI with interactive prompts

### 🐛 Bug Fixes

- fix: resolve installation path issues
- fix: handle edge cases in agent loading

### 🔧 Maintenance

- chore: update dependencies
- chore: improve error messages

## 📦 Installation

```bash
npx bmad-method install
```

Full Changelog: https://github.com/bmadcode/BMAD-METHOD/compare/v5.1.0...v5.2.0


## 🎯 User Installation

After any release, users can immediately get the new version with:

```bash
npx bmad-method install    # Always gets latest release
```

## 📊 Preview Before Release

Always preview what will be included in your release:

```bash
npm run preview:release
```

This shows:

- Commits since last release
- Categorized changes
- Estimated next version
- Release notes preview

## 🔧 Manual Release (GitHub UI)

You can also trigger releases through GitHub Actions:

1. Go to **GitHub Actions** → **Manual Release**
2. Click **"Run workflow"**
3. Choose version bump type (patch/minor/major)
4. Everything else happens automatically

## 📈 Version Strategy

- **Patch** (5.1.0 → 5.1.1): Bug fixes, minor improvements
- **Minor** (5.1.0 → 5.2.0): New features, enhancements
- **Major** (5.1.0 → 6.0.0): Breaking changes, major redesigns

## 🛠️ Development Workflow

1. **Develop Freely** - Merge PRs to main without triggering releases
2. **Test Unreleased Changes** - Clone repo to test latest main branch
3. **Release When Ready** - Use command line or GitHub Actions to cut releases
4. **Users Get Updates** - Via simple `npx bmad-method install` command

This gives you complete control over when releases happen while automating all the tedious parts like version bumping, release notes, and publishing.

## 🔍 Troubleshooting

### Check Release Status

```bash
gh run list --workflow="Manual Release"
npm view bmad-method dist-tags
git tag -l | sort -V | tail -5
```

### View Latest Release

```bash
gh release view --web
npm view bmad-method versions --json
```

### If Version Sync Needed

If your local files don't match the published version after a release:

```bash
./sync-version.sh    # Automatically syncs local files with npm latest
```

### If Release Fails

- Check GitHub Actions logs: `gh run view <run-id> --log-failed`
- Verify NPM tokens are configured
- Ensure branch protection allows workflow pushes

3.9 KiB Raw Blame History