From 8573852a6e76bb2b6358f6c1dda32398244b1771 Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Sat, 16 Aug 2025 20:50:22 -0500 Subject: [PATCH] docs: update versioning and releases documentation - Replace old semantic-release documentation with new simplified system - Document command line release workflow (npm run release:*) - Explain automatic release notes generation and categorization - Add troubleshooting section and preview functionality - Reflect current single @stable tag installation approach --- docs/versioning-and-releases.md | 172 ++++++++++++++++++++++---------- 1 file changed, 121 insertions(+), 51 deletions(-) diff --git a/docs/versioning-and-releases.md b/docs/versioning-and-releases.md index 5fabdb0a..96f596a3 100644 --- a/docs/versioning-and-releases.md +++ b/docs/versioning-and-releases.md @@ -1,77 +1,147 @@ -# How to Release a New Version +# Versioning and Releases -## Automated Releases (Recommended) +BMad Method uses a simplified release system with manual control and automatic release notes generation. -The easiest way to release new versions is through **automatic semantic releases**. Just commit with the right message format and push and everything else happens automatically. +## 🚀 Release Workflow -### Commit Message Format +### Command Line Release (Recommended) -Use these prefixes to control what type of release happens: +The fastest way to create a release with beautiful release notes: ```bash -fix: resolve CLI argument parsing bug # → patch release (4.1.0 → 4.1.1) -feat: add new agent orchestration mode # → minor release (4.1.0 → 4.2.0) -feat!: redesign CLI interface # → major release (4.1.0 → 5.0.0) +# 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 ``` -### What Happens Automatically - -When you push commits with `fix:` or `feat:`, GitHub Actions will: - -1. ✅ Analyze your commit messages -2. ✅ Bump version in `package.json` -3. ✅ Generate changelog -4. ✅ Create git tag -5. ✅ **Publish to NPM automatically** -6. ✅ Create GitHub release with notes - -### Your Simple Workflow +### One-Liner Release ```bash -# Make your changes -git add . -git commit -m "feat: add team collaboration mode" -git push - -# That's it! Release happens automatically 🎉 -# Users can now run: npx bmad-method (and get the new version) +npm run preview:release && npm run release:minor && npm run release:watch ``` -### Commits That DON'T Trigger Releases +## 📝 What Happens Automatically -These commit types won't create releases (use them for maintenance): +When you trigger a release, the GitHub Actions workflow automatically: + +1. ✅ **Validates** - Runs tests, linting, and formatting checks +2. ✅ **Bumps Version** - Updates `package.json` and installer version +3. ✅ **Generates Release Notes** - Categorizes commits since last release: + - ✨ **New Features** (`feat:`, `Feature:`) + - 🐛 **Bug Fixes** (`fix:`, `Fix:`) + - 🔧 **Maintenance** (`chore:`, `Chore:`) + - 📦 **Other Changes** (everything else) +4. ✅ **Creates Git Tag** - Tags the release version +5. ✅ **Publishes to NPM** - With `@stable` tag for user installations +6. ✅ **Creates GitHub Release** - With formatted release notes +7. ✅ **Updates Dist Tags** - So `npx bmad-method install` gets latest version + +## 📋 Sample Release Notes + +The workflow automatically generates professional release notes like this: + +````markdown +## 🚀 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 -chore: update dependencies # No release -docs: fix typo in readme # No release -style: format code # No release -test: add unit tests # No release +npx bmad-method install ``` +```` -### Test Your Setup +**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 -npm run release:test # Safe to run locally - tests the config -``` +npx bmad-method install # Always gets latest stable release +```` ---- +## 📊 Preview Before Release -## Manual Release Methods (Exceptions Only) - -⚠️ Only use these methods if you need to bypass the automatic system - -### Quick Manual Version Bump +Always preview what will be included in your release: ```bash -npm run version:patch # 4.1.0 → 4.1.1 (bug fixes) -npm run version:minor # 4.1.0 → 4.2.0 (new features) -npm run version:major # 4.1.0 → 5.0.0 (breaking changes) - -# Then manually publish: -npm publish -git push && git push --tags +npm run preview:release ``` -### Manual GitHub Actions Trigger +This shows: -You can also trigger releases manually through GitHub Actions workflow dispatch if needed. +- 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 Release Fails + +- Check GitHub Actions logs: `gh run view --log-failed` +- Verify NPM tokens are configured +- Ensure branch protection allows workflow pushes