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
parent
39437e9268
commit
8573852a6e
|
|
@ -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
|
```bash
|
||||||
fix: resolve CLI argument parsing bug # → patch release (4.1.0 → 4.1.1)
|
# Preview what will be in the release
|
||||||
feat: add new agent orchestration mode # → minor release (4.1.0 → 4.2.0)
|
npm run preview:release
|
||||||
feat!: redesign CLI interface # → major release (4.1.0 → 5.0.0)
|
|
||||||
|
# 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
|
### One-Liner Release
|
||||||
|
|
||||||
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
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Make your changes
|
npm run preview:release && npm run release:minor && npm run release:watch
|
||||||
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)
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### 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
|
```bash
|
||||||
chore: update dependencies # No release
|
npx bmad-method install
|
||||||
docs: fix typo in readme # No release
|
|
||||||
style: format code # No release
|
|
||||||
test: add unit tests # No release
|
|
||||||
```
|
```
|
||||||
|
````
|
||||||
|
|
||||||
### 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
|
```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)
|
Always preview what will be included in your release:
|
||||||
|
|
||||||
⚠️ Only use these methods if you need to bypass the automatic system
|
|
||||||
|
|
||||||
### Quick Manual Version Bump
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
npm run version:patch # 4.1.0 → 4.1.1 (bug fixes)
|
npm run preview:release
|
||||||
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
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### 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
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue