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
This commit is contained in:
Brian Madison
@@ -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 <run-id> --log-failed`
|
||||
- Verify NPM tokens are configured
|
||||
- Ensure branch protection allows workflow pushes
|
||||
|
||||
Reference in New Issue
Block a user