bmad-method 5.0.0 → 5.0.1

package/docs/versioning-and-releases.md

@@ -1,85 +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 - 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)
-```text
-
-### What Happens Automatically
+```bash
+# Preview what will be in the release
+npm run preview:release
 
-When you push commits with `fix:` or `feat:`, GitHub Actions will:
+# 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)
 
-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
+# Watch the release process
+npm run release:watch
+```
 
-### Your Simple Workflow
+### One-Liner Release
 
 ```bash
-# Make your changes
-git add .
-git commit -m "feat: add team collaboration mode"
-git push
+npm run preview:release && npm run release:minor && npm run release:watch
+```
 
-# That's it! Release happens automatically 🎉
-# Users can now run: npx bmad-method (and get the new version)
-````
+## 📝 What Happens Automatically
+
+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 `@latest` tag for user installations
+6. ✅ **Creates GitHub Release** - With formatted release notes
+
+## 📋 Sample Release Notes
+
+The workflow automatically generates professional release notes like this:
 
-### Commits That DON'T Trigger Releases
+````markdown
+## 🚀 What's New in v5.2.0
 
-These commit types won't create releases (use them for maintenance):
+### ✨ New Features
 
-````bash
-chore: update dependencies     # No release
-docs: fix typo in readme      # No release
-style: format code            # No release
-test: add unit tests          # No release
-```text
+- feat: add team collaboration mode
+- feat: enhance CLI with interactive prompts
 
-### Test Your Setup
+### 🐛 Bug Fixes
+
+- fix: resolve installation path issues
+- fix: handle edge cases in agent loading
+
+### 🔧 Maintenance
+
+- chore: update dependencies
+- chore: improve error messages
+
+## 📦 Installation
 
 ```bash
-npm run release:test    # Safe to run locally - tests the config
+npx bmad-method install
+```
 ````
 
----
+**Full Changelog**: https://github.com/bmadcode/BMAD-METHOD/compare/v5.1.0...v5.2.0
 
-## Manual Release Methods (Exceptions Only)
+````
 
-**⚠️ Only use these methods if you need to bypass the automatic system**
+## 🎯 User Installation
 
-### Quick Manual Version Bump
+After any release, users can immediately get the new version with:
 
 ```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)
+npx bmad-method install    # Always gets latest release
+```
+
+## 📊 Preview Before Release
+
+Always preview what will be included in your release:
 
-# Then manually publish:
-npm publish
-git push && git push --tags
+```bash
+npm run preview:release
 ```
 
-### Manual GitHub Actions Trigger
+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
 
-You can also trigger releases manually through GitHub Actions workflow dispatch if needed.
+## 📈 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
 
-## Summary
+## 🛠️ Development Workflow
 
-**For 99% of releases**: Just use `fix:` or `feat:` commit messages and push. Everything else is automatic!
+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
 
-**Manual methods**: Only needed for special cases or if you want to bypass the automated system.
+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 <run-id> --log-failed`
+- Verify NPM tokens are configured
+- Ensure branch protection allows workflow pushes
+````

package/docs/versions.md

@@ -2,9 +2,9 @@
 
 ## Previous Versions
 
-- [Version 3](https://github.com/bmadcode/BMAD-METHOD/tree/V3)
-- [Version 2](https://github.com/bmadcode/BMAD-METHOD/tree/V2)
-- [Version 1](https://github.com/bmadcode/BMAD-METHOD/tree/V1)
+- [Version 3](https://github.com/bmadcode/BMad-Method/tree/V3)
+- [Version 2](https://github.com/bmadcode/BMad-Method/tree/V2)
+- [Version 1](https://github.com/bmadcode/BMad-Method/tree/V1)
 
 ## Current Version: V4 - Alpha
 
@@ -16,7 +16,6 @@ Guiding Principles of V4:
 - Helpers for installers and web builders that will work with any OS and IDE easily
 - Align all agents to be the same for IDE and Web, without losing the power of the web versions, or the leanness of the files in the IDE to reduce context
 - Further improvements to the two most important agents - the SM and DEV
-- Expansion Packs - Coming soon...
 
 ## V3
 
@@ -26,7 +25,7 @@ V3 didn't fix the disconnect, but it did make it easier to maintain them all in
 
 V3's biggest impact was a full explosion of customizability. Tasks, Personas, Agent Configurations, Doc Templates, data payloads.
 
-BUT - the BIGGEST change was the realization that we were barely scratching the surface of what could be loaded into Gemini Gems and still have very long chats. The BMAD AGENT arose, and with a single V3 release - the future of the BMad Method was changed forever.
+BUT - the BIGGEST change was the realization that we were barely scratching the surface of what could be loaded into Gemini Gems and still have very long chats. The BMad AGENT arose, and with a single V3 release - the future of the BMad Method was changed forever.
 
 Now, instead of configuring 4+ web agents, all needing many files uploaded to create them, a single Agent called BMad, with a whole team, and the ability to switch and maintain personas evolved. Now you could in the same chat thread, talk to the whole team, or anyone on the team. No more exporting and reimporting docs to different chats - all of the sudden, you could finish the PRD, and ask Josh to pass it off to the Architect, and that was it, the architect just had it and we moved on! And all of that with just 7 total files to upload, delivering all power.