From 3f5abf347d70ca9bb1ba1709f715c683634d57e3 Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Sat, 16 Aug 2025 20:23:23 -0500 Subject: [PATCH 01/12] feat: simplify installation to single @stable tag - Remove automatic versioning and dual publishing strategy - Delete release.yaml and promote-to-stable.yaml workflows - Add manual-release.yaml for controlled releases - Remove semantic-release dependencies and config - Update all documentation to use npx bmad-method install - Configure NPM to publish to @stable tag by default - Users can now use simple npx bmad-method install command --- .github/workflows/manual-release.yaml | 98 +++++++++++++++ .github/workflows/promote-to-stable.yaml | 148 ----------------------- .github/workflows/release.yaml | 73 ----------- .releaserc.json | 22 ---- README.md | 2 + package.json | 8 +- tools/semantic-release-sync-installer.js | 30 ----- 7 files changed, 103 insertions(+), 278 deletions(-) create mode 100644 .github/workflows/manual-release.yaml delete mode 100644 .github/workflows/promote-to-stable.yaml delete mode 100644 .github/workflows/release.yaml delete mode 100644 .releaserc.json delete mode 100644 tools/semantic-release-sync-installer.js diff --git a/.github/workflows/manual-release.yaml b/.github/workflows/manual-release.yaml new file mode 100644 index 00000000..d7b41cee --- /dev/null +++ b/.github/workflows/manual-release.yaml @@ -0,0 +1,98 @@ +name: Manual Release + +on: + workflow_dispatch: + inputs: + version_bump: + description: Version bump type + required: true + default: patch + type: choice + options: + - patch + - minor + - major + +permissions: + contents: write + packages: write + +jobs: + release: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + fetch-depth: 0 + token: ${{ secrets.GITHUB_TOKEN }} + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: "20" + cache: npm + registry-url: https://registry.npmjs.org + + - name: Install dependencies + run: npm ci + + - name: Run tests and validation + run: | + npm run validate + npm run format:check + npm run lint + + - name: Configure Git + run: | + git config user.name "github-actions[bot]" + git config user.email "github-actions[bot]@users.noreply.github.com" + + - name: Bump version + run: npm run version:${{ github.event.inputs.version_bump }} + + - name: Get new version + id: version + run: echo "new_version=$(node -p "require('./package.json').version")" >> $GITHUB_OUTPUT + + - name: Update installer package.json + run: | + sed -i 's/"version": ".*"/"version": "${{ steps.version.outputs.new_version }}"/' tools/installer/package.json + + - name: Build project + run: npm run build + + - name: Commit version bump + run: | + git add . + git commit -m "release: bump to v${{ steps.version.outputs.new_version }}" + + - name: Create and push tag + run: | + git tag -a "v${{ steps.version.outputs.new_version }}" -m "Release v${{ steps.version.outputs.new_version }}" + git push origin "v${{ steps.version.outputs.new_version }}" + + - name: Push changes to main + run: git push origin HEAD:main + + - name: Publish to NPM with stable tag + env: + NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} + run: npm publish --tag stable + + - name: Create GitHub Release + uses: actions/create-release@v1 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + tag_name: v${{ steps.version.outputs.new_version }} + release_name: Release v${{ steps.version.outputs.new_version }} + draft: false + prerelease: false + + - name: Summary + run: | + echo "šŸŽ‰ Successfully released v${{ steps.version.outputs.new_version }}!" + echo "šŸ“¦ Published to NPM with @stable tag" + echo "šŸ·ļø Git tag: v${{ steps.version.outputs.new_version }}" + echo "āœ… Users running 'npx bmad-method@stable install' will now get version ${{ steps.version.outputs.new_version }}" diff --git a/.github/workflows/promote-to-stable.yaml b/.github/workflows/promote-to-stable.yaml deleted file mode 100644 index 7312bb3d..00000000 --- a/.github/workflows/promote-to-stable.yaml +++ /dev/null @@ -1,148 +0,0 @@ -name: Promote to Stable - -"on": - workflow_dispatch: - inputs: - version_bump: - description: "Version bump type" - required: true - default: "minor" - type: choice - options: - - patch - - minor - - major - -jobs: - promote: - runs-on: ubuntu-latest - permissions: - contents: write - pull-requests: write - - steps: - - name: Checkout repository - uses: actions/checkout@v4 - with: - fetch-depth: 0 - token: ${{ secrets.GITHUB_TOKEN }} - - - name: Setup Node.js - uses: actions/setup-node@v4 - with: - node-version: "20" - registry-url: "https://registry.npmjs.org" - - - name: Configure Git - run: | - git config --global user.name "github-actions[bot]" - git config --global user.email "github-actions[bot]@users.noreply.github.com" - - - name: Install dependencies - run: npm ci - - - name: Get current version and calculate new version - id: version - run: | - # Get current version from package.json - CURRENT_VERSION=$(node -p "require('./package.json').version") - echo "current_version=$CURRENT_VERSION" >> $GITHUB_OUTPUT - - # Remove beta suffix if present - BASE_VERSION=$(echo $CURRENT_VERSION | sed 's/-beta\.[0-9]\+//') - echo "base_version=$BASE_VERSION" >> $GITHUB_OUTPUT - - # Calculate new version based on bump type - IFS='.' read -ra VERSION_PARTS <<< "$BASE_VERSION" - MAJOR=${VERSION_PARTS[0]} - MINOR=${VERSION_PARTS[1]} - PATCH=${VERSION_PARTS[2]} - - case "${{ github.event.inputs.version_bump }}" in - "major") - NEW_VERSION="$((MAJOR + 1)).0.0" - ;; - "minor") - NEW_VERSION="$MAJOR.$((MINOR + 1)).0" - ;; - "patch") - NEW_VERSION="$MAJOR.$MINOR.$((PATCH + 1))" - ;; - *) - NEW_VERSION="$BASE_VERSION" - ;; - esac - - # Check if calculated version already exists (either as NPM package or git tag) - while npm view bmad-method@$NEW_VERSION version >/dev/null 2>&1 || git ls-remote --tags origin | grep -q "refs/tags/v$NEW_VERSION"; do - echo "Version $NEW_VERSION already exists, incrementing..." - IFS='.' read -ra NEW_VERSION_PARTS <<< "$NEW_VERSION" - NEW_MAJOR=${NEW_VERSION_PARTS[0]} - NEW_MINOR=${NEW_VERSION_PARTS[1]} - NEW_PATCH=${NEW_VERSION_PARTS[2]} - - case "${{ github.event.inputs.version_bump }}" in - "major") - NEW_VERSION="$((NEW_MAJOR + 1)).0.0" - ;; - "minor") - NEW_VERSION="$NEW_MAJOR.$((NEW_MINOR + 1)).0" - ;; - "patch") - NEW_VERSION="$NEW_MAJOR.$NEW_MINOR.$((NEW_PATCH + 1))" - ;; - esac - done - - echo "new_version=$NEW_VERSION" >> $GITHUB_OUTPUT - echo "Promoting from $CURRENT_VERSION to $NEW_VERSION" - - - name: Update package.json versions - run: | - # Update main package.json - npm version ${{ steps.version.outputs.new_version }} --no-git-tag-version - - # Update installer package.json - sed -i 's/"version": ".*"/"version": "${{ steps.version.outputs.new_version }}"/' tools/installer/package.json - - - name: Update package-lock.json - run: npm install --package-lock-only - - - name: Commit stable release - run: | - git add . - git commit -m "release: promote to stable ${{ steps.version.outputs.new_version }}" - - - name: Create and push stable tag - run: | - # Create new tag (version check already ensures it doesn't exist) - git tag -a "v${{ steps.version.outputs.new_version }}" -m "Stable release v${{ steps.version.outputs.new_version }}" - - # Push the new tag - git push origin "v${{ steps.version.outputs.new_version }}" - - - name: Push changes to main - run: | - git push origin HEAD:main - - - name: Publish to NPM with stable tag - env: - NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} - run: | - # Publish with the stable (latest) tag - npm publish --tag latest - - # Also tag the previous beta version as stable if it exists - if npm view bmad-method@${{ steps.version.outputs.current_version }} version >/dev/null 2>&1; then - npm dist-tag add bmad-method@${{ steps.version.outputs.new_version }} stable || true - fi - - - name: Summary - run: | - echo "šŸŽ‰ Successfully promoted to stable!" - echo "šŸ“¦ Version: ${{ steps.version.outputs.new_version }}" - echo "šŸ·ļø Git tag: v${{ steps.version.outputs.new_version }}" - echo "āœ… Published to NPM with 'latest' tag" - echo "āœ… Users running 'npx bmad-method install' will now get version ${{ steps.version.outputs.new_version }}" - echo "šŸš€ The stable release will be automatically published to NPM via semantic-release" - echo "āœ… Users running 'npx bmad-method install' will now get version ${{ steps.version.outputs.new_version }}" diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml deleted file mode 100644 index 23608026..00000000 --- a/.github/workflows/release.yaml +++ /dev/null @@ -1,73 +0,0 @@ -name: Release -"on": - push: - branches: - - main - workflow_dispatch: - inputs: - version_type: - description: Version bump type - required: true - default: patch - type: choice - options: - - patch - - minor - - major -permissions: - contents: write - issues: write - pull-requests: write - packages: write -jobs: - release: - runs-on: ubuntu-latest - if: ${{ github.event_name != 'push' || !contains(github.event.head_commit.message, '[skip ci]') }} - steps: - - name: Checkout - uses: actions/checkout@v4 - with: - fetch-depth: 0 - token: ${{ secrets.GITHUB_TOKEN }} - - name: Setup Node.js - uses: actions/setup-node@v4 - with: - node-version: "20" - cache: "npm" - registry-url: "https://registry.npmjs.org" - - name: Install dependencies - run: npm ci - - name: Run tests and validation - run: | - npm run validate - npm run format - - name: Debug permissions - run: | - echo "Testing git permissions..." - git config user.name "github-actions[bot]" - git config user.email "github-actions[bot]@users.noreply.github.com" - echo "Git config set successfully" - - name: Manual version bump - if: github.event_name == 'workflow_dispatch' - run: npm run version:${{ github.event.inputs.version_type }} - - name: Semantic Release - if: github.event_name == 'push' - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - NPM_TOKEN: ${{ secrets.NPM_TOKEN }} - NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} - run: npm run release - - name: Clean changelog formatting - if: github.event_name == 'push' - run: | - git config user.name "github-actions[bot]" - git config user.email "github-actions[bot]@users.noreply.github.com" - # Remove any Claude Code attribution from changelog - sed -i '/šŸ¤– Generated with \[Claude Code\]/,+2d' CHANGELOG.md || true - # Format and commit if changes exist - npm run format - if ! git diff --quiet CHANGELOG.md; then - git add CHANGELOG.md - git commit -m "chore: clean changelog formatting [skip ci]" - git push - fi diff --git a/.releaserc.json b/.releaserc.json deleted file mode 100644 index 8b2d1d33..00000000 --- a/.releaserc.json +++ /dev/null @@ -1,22 +0,0 @@ -{ - "branches": [ - { - "name": "main", - "prerelease": "beta", - "channel": "beta" - } - ], - "plugins": [ - "@semantic-release/commit-analyzer", - "@semantic-release/release-notes-generator", - [ - "@semantic-release/changelog", - { - "changelogFile": "CHANGELOG.md" - } - ], - "@semantic-release/npm", - "./tools/semantic-release-sync-installer.js", - "@semantic-release/github" - ] -} diff --git a/README.md b/README.md index b5687eb0..0d182dba 100644 --- a/README.md +++ b/README.md @@ -75,6 +75,8 @@ This makes it easy to benefit from the latest improvements, bug fixes, and new a ```bash npx bmad-method install +# OR explicitly use stable tag: +npx bmad-method@stable install # OR if you already have BMad installed: git pull npm run install:bmad diff --git a/package.json b/package.json index 444f11eb..ccd3563d 100644 --- a/package.json +++ b/package.json @@ -35,8 +35,6 @@ "lint:fix": "eslint . --ext .js,.cjs,.mjs,.yaml --fix", "list:agents": "node tools/cli.js list:agents", "prepare": "husky", - "release": "semantic-release", - "release:test": "semantic-release --dry-run --no-ci || echo 'Config test complete - authentication errors are expected locally'", "validate": "node tools/cli.js validate", "version:all": "node tools/bump-all-versions.js", "version:all:major": "node tools/bump-all-versions.js major", @@ -80,8 +78,6 @@ }, "devDependencies": { "@eslint/js": "^9.33.0", - "@semantic-release/changelog": "^6.0.3", - "@semantic-release/git": "^10.0.1", "eslint": "^9.33.0", "eslint-config-prettier": "^10.1.8", "eslint-plugin-n": "^17.21.3", @@ -92,11 +88,13 @@ "lint-staged": "^16.1.1", "prettier": "^3.5.3", "prettier-plugin-packagejson": "^2.5.19", - "semantic-release": "^22.0.0", "yaml-eslint-parser": "^1.2.3", "yaml-lint": "^1.7.0" }, "engines": { "node": ">=20.10.0" + }, + "publishConfig": { + "tag": "stable" } } diff --git a/tools/semantic-release-sync-installer.js b/tools/semantic-release-sync-installer.js deleted file mode 100644 index 37bad0cf..00000000 --- a/tools/semantic-release-sync-installer.js +++ /dev/null @@ -1,30 +0,0 @@ -/** - * Semantic-release plugin to sync installer package.json version - */ - -const fs = require('node:fs'); -const path = require('node:path'); - -// This function runs during the "prepare" step of semantic-release -function prepare(_, { nextRelease, logger }) { - // Define the path to the installer package.json file - const file = path.join(process.cwd(), 'tools/installer/package.json'); - - // If the file does not exist, skip syncing and log a message - if (!fs.existsSync(file)) return logger.log('Installer package.json not found, skipping'); - - // Read and parse the package.json file - const package_ = JSON.parse(fs.readFileSync(file, 'utf8')); - - // Update the version field with the next release version - package_.version = nextRelease.version; - - // Write the updated JSON back to the file - fs.writeFileSync(file, JSON.stringify(package_, null, 2) + '\n'); - - // Log success message - logger.log(`Synced installer package.json to version ${nextRelease.version}`); -} - -// Export the prepare function so semantic-release can use it -module.exports = { prepare }; From 3eb706c49a9274d3fd300c16b93f43cfcae56eef Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Sat, 16 Aug 2025 20:35:41 -0500 Subject: [PATCH 02/12] feat: enhance manual release workflow with automatic release notes - Add automatic release notes generation from commit history - Categorize commits into Features, Bug Fixes, and Maintenance - Include installation instructions and changelog links - Add preview-release-notes script for testing - Update GitHub release creation to use generated notes --- .github/workflows/manual-release.yaml | 72 +++++++++++++++++++++++++-- package.json | 1 + tools/preview-release-notes.js | 66 ++++++++++++++++++++++++ 3 files changed, 135 insertions(+), 4 deletions(-) create mode 100755 tools/preview-release-notes.js diff --git a/.github/workflows/manual-release.yaml b/.github/workflows/manual-release.yaml index d7b41cee..60da1ecc 100644 --- a/.github/workflows/manual-release.yaml +++ b/.github/workflows/manual-release.yaml @@ -51,9 +51,11 @@ jobs: - name: Bump version run: npm run version:${{ github.event.inputs.version_bump }} - - name: Get new version + - name: Get new version and previous tag id: version - run: echo "new_version=$(node -p "require('./package.json').version")" >> $GITHUB_OUTPUT + run: | + echo "new_version=$(node -p "require('./package.json').version")" >> $GITHUB_OUTPUT + echo "previous_tag=$(git describe --tags --abbrev=0)" >> $GITHUB_OUTPUT - name: Update installer package.json run: | @@ -67,6 +69,64 @@ jobs: git add . git commit -m "release: bump to v${{ steps.version.outputs.new_version }}" + - name: Generate release notes + id: release_notes + run: | + # Get commits since last tag + COMMITS=$(git log ${{ steps.version.outputs.previous_tag }}..HEAD --pretty=format:"- %s" --reverse) + + # Categorize commits + FEATURES=$(echo "$COMMITS" | grep -E "^- (feat|Feature)" || true) + FIXES=$(echo "$COMMITS" | grep -E "^- (fix|Fix)" || true) + CHORES=$(echo "$COMMITS" | grep -E "^- (chore|Chore)" || true) + OTHERS=$(echo "$COMMITS" | grep -v -E "^- (feat|Feature|fix|Fix|chore|Chore|release:|Release:)" || true) + + # Build release notes + cat > release_notes.md << 'EOF' + ## šŸš€ What's New in v${{ steps.version.outputs.new_version }} + + EOF + + if [ ! -z "$FEATURES" ]; then + echo "### āœØ New Features" >> release_notes.md + echo "$FEATURES" >> release_notes.md + echo "" >> release_notes.md + fi + + if [ ! -z "$FIXES" ]; then + echo "### šŸ› Bug Fixes" >> release_notes.md + echo "$FIXES" >> release_notes.md + echo "" >> release_notes.md + fi + + if [ ! -z "$OTHERS" ]; then + echo "### šŸ“¦ Other Changes" >> release_notes.md + echo "$OTHERS" >> release_notes.md + echo "" >> release_notes.md + fi + + if [ ! -z "$CHORES" ]; then + echo "### šŸ”§ Maintenance" >> release_notes.md + echo "$CHORES" >> release_notes.md + echo "" >> release_notes.md + fi + + cat >> release_notes.md << 'EOF' + + ## šŸ“¦ Installation + + ```bash + npx bmad-method install + ``` + + **Full Changelog**: https://github.com/bmadcode/BMAD-METHOD/compare/${{ steps.version.outputs.previous_tag }}...v${{ steps.version.outputs.new_version }} + EOF + + # Output for GitHub Actions + echo "RELEASE_NOTES<> $GITHUB_OUTPUT + cat release_notes.md >> $GITHUB_OUTPUT + echo "EOF" >> $GITHUB_OUTPUT + - name: Create and push tag run: | git tag -a "v${{ steps.version.outputs.new_version }}" -m "Release v${{ steps.version.outputs.new_version }}" @@ -86,7 +146,8 @@ jobs: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} with: tag_name: v${{ steps.version.outputs.new_version }} - release_name: Release v${{ steps.version.outputs.new_version }} + release_name: "BMad Method v${{ steps.version.outputs.new_version }}" + body: ${{ steps.release_notes.outputs.RELEASE_NOTES }} draft: false prerelease: false @@ -95,4 +156,7 @@ jobs: echo "šŸŽ‰ Successfully released v${{ steps.version.outputs.new_version }}!" echo "šŸ“¦ Published to NPM with @stable tag" echo "šŸ·ļø Git tag: v${{ steps.version.outputs.new_version }}" - echo "āœ… Users running 'npx bmad-method@stable install' will now get version ${{ steps.version.outputs.new_version }}" + echo "āœ… Users running 'npx bmad-method install' will now get version ${{ steps.version.outputs.new_version }}" + echo "" + echo "šŸ“ Release notes preview:" + cat release_notes.md diff --git a/package.json b/package.json index ccd3563d..b0938ab5 100644 --- a/package.json +++ b/package.json @@ -35,6 +35,7 @@ "lint:fix": "eslint . --ext .js,.cjs,.mjs,.yaml --fix", "list:agents": "node tools/cli.js list:agents", "prepare": "husky", + "preview:release": "node tools/preview-release-notes.js", "validate": "node tools/cli.js validate", "version:all": "node tools/bump-all-versions.js", "version:all:major": "node tools/bump-all-versions.js major", diff --git a/tools/preview-release-notes.js b/tools/preview-release-notes.js new file mode 100755 index 00000000..cedb32b5 --- /dev/null +++ b/tools/preview-release-notes.js @@ -0,0 +1,66 @@ +const { execSync } = require('node:child_process'); +const fs = require('node:fs'); + +// Get the latest stable tag (exclude beta tags) +const allTags = execSync('git tag -l | sort -V', { encoding: 'utf8' }).split('\n').filter(Boolean); +const stableTags = allTags.filter((tag) => !tag.includes('beta')); +const latestTag = stableTags.at(-1) || 'v5.0.0'; + +// Get commits since last tag +const commits = execSync(`git log ${latestTag}..HEAD --pretty=format:"- %s" --reverse`, { + encoding: 'utf8', +}) + .split('\n') + .filter(Boolean); + +// Categorize commits +const features = commits.filter((commit) => /^- (feat|Feature)/.test(commit)); +const fixes = commits.filter((commit) => /^- (fix|Fix)/.test(commit)); +const chores = commits.filter((commit) => /^- (chore|Chore)/.test(commit)); +const others = commits.filter( + (commit) => !/^- (feat|Feature|fix|Fix|chore|Chore|release:|Release:)/.test(commit), +); + +// Get next version (you can modify this logic) +const currentVersion = require('../package.json').version; +const versionParts = currentVersion.split('.').map(Number); +const nextVersion = `${versionParts[0]}.${versionParts[1] + 1}.0`; // Default to minor bump + +console.log(`## šŸš€ What's New in v${nextVersion}\n`); + +if (features.length > 0) { + console.log('### āœØ New Features'); + for (const feature of features) console.log(feature); + console.log(''); +} + +if (fixes.length > 0) { + console.log('### šŸ› Bug Fixes'); + for (const fix of fixes) console.log(fix); + console.log(''); +} + +if (others.length > 0) { + console.log('### šŸ“¦ Other Changes'); + for (const other of others) console.log(other); + console.log(''); +} + +if (chores.length > 0) { + console.log('### šŸ”§ Maintenance'); + for (const chore of chores) console.log(chore); + console.log(''); +} + +console.log('\n## šŸ“¦ Installation\n'); +console.log('```bash'); +console.log('npx bmad-method install'); +console.log('```'); + +console.log( + `\n**Full Changelog**: https://github.com/bmadcode/BMAD-METHOD/compare/${latestTag}...v${nextVersion}`, +); + +console.log(`\n---\nšŸ“Š **Summary**: ${commits.length} commits since ${latestTag}`); +console.log(`šŸ·ļø **Previous tag**: ${latestTag}`); +console.log(`šŸš€ **Next version**: v${nextVersion} (estimated)`); From ba4fb4d0842b68e16a7ebfca630f40160f831cbf Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Sat, 16 Aug 2025 20:38:58 -0500 Subject: [PATCH 03/12] feat: add convenient npm scripts for command line releases - npm run release:patch/minor/major for triggering releases - npm run release:watch for monitoring workflow progress - One-liner workflow: preview:release && release:minor && release:watch --- package.json | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/package.json b/package.json index b0938ab5..505cd395 100644 --- a/package.json +++ b/package.json @@ -36,6 +36,10 @@ "list:agents": "node tools/cli.js list:agents", "prepare": "husky", "preview:release": "node tools/preview-release-notes.js", + "release:major": "gh workflow run \"Manual Release\" -f version_bump=major", + "release:minor": "gh workflow run \"Manual Release\" -f version_bump=minor", + "release:patch": "gh workflow run \"Manual Release\" -f version_bump=patch", + "release:watch": "gh run watch", "validate": "node tools/cli.js validate", "version:all": "node tools/bump-all-versions.js", "version:all:major": "node tools/bump-all-versions.js major", From 1772a30368a17ee8ed5614bf3b07670cfe9e5555 Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Sat, 16 Aug 2025 20:42:35 -0500 Subject: [PATCH 04/12] fix: enable version bumping in manual release workflow - Fix version-bump.js to actually update package.json version - Add tag existence check to prevent duplicate tag errors - Remove semantic-release dependency from version bumping --- .github/workflows/manual-release.yaml | 9 +++++-- tools/version-bump.js | 39 +++++++++++++++++++-------- 2 files changed, 35 insertions(+), 13 deletions(-) diff --git a/.github/workflows/manual-release.yaml b/.github/workflows/manual-release.yaml index 60da1ecc..cdce467f 100644 --- a/.github/workflows/manual-release.yaml +++ b/.github/workflows/manual-release.yaml @@ -129,8 +129,13 @@ jobs: - name: Create and push tag run: | - git tag -a "v${{ steps.version.outputs.new_version }}" -m "Release v${{ steps.version.outputs.new_version }}" - git push origin "v${{ steps.version.outputs.new_version }}" + # Check if tag already exists + if git rev-parse "v${{ steps.version.outputs.new_version }}" >/dev/null 2>&1; then + echo "Tag v${{ steps.version.outputs.new_version }} already exists, skipping tag creation" + else + git tag -a "v${{ steps.version.outputs.new_version }}" -m "Release v${{ steps.version.outputs.new_version }}" + git push origin "v${{ steps.version.outputs.new_version }}" + fi - name: Push changes to main run: git push origin HEAD:main diff --git a/tools/version-bump.js b/tools/version-bump.js index c6ce4eb4..978b18e4 100755 --- a/tools/version-bump.js +++ b/tools/version-bump.js @@ -31,18 +31,35 @@ async function bumpVersion(type = 'patch') { process.exit(1); } - console.log(chalk.yellow('āš ļø Manual version bumping is disabled.')); - console.log(chalk.blue('šŸ¤– This project uses semantic-release for automated versioning.')); - console.log(''); - console.log(chalk.bold('To create a new release, use conventional commits:')); - console.log(chalk.cyan(' feat: new feature (minor version bump)')); - console.log(chalk.cyan(' fix: bug fix (patch version bump)')); - console.log(chalk.cyan(' feat!: breaking change (major version bump)')); - console.log(''); - console.log(chalk.dim('Example: git commit -m "feat: add new installer features"')); - console.log(chalk.dim('Then push to main branch to trigger automatic release.')); + const currentVersion = getCurrentVersion(); + const versionParts = currentVersion.split('.').map(Number); + let newVersion; - return null; + switch (type) { + case 'major': { + newVersion = `${versionParts[0] + 1}.0.0`; + break; + } + case 'minor': { + newVersion = `${versionParts[0]}.${versionParts[1] + 1}.0`; + break; + } + case 'patch': { + newVersion = `${versionParts[0]}.${versionParts[1]}.${versionParts[2] + 1}`; + break; + } + } + + console.log(chalk.blue(`Bumping version: ${currentVersion} ā†’ ${newVersion}`)); + + // Update package.json + const packageJson = JSON.parse(fs.readFileSync('package.json', 'utf8')); + packageJson.version = newVersion; + fs.writeFileSync('package.json', JSON.stringify(packageJson, null, 2) + '\n'); + + console.log(chalk.green(`āœ“ Updated package.json to ${newVersion}`)); + + return newVersion; } async function main() { From 39437e92681334cbb7e4b2211084e37b7a27fe0d Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Sat, 16 Aug 2025 20:44:00 -0500 Subject: [PATCH 05/12] fix: handle protected branch in manual release workflow - Allow workflow to continue even if push to main fails - This is expected behavior with protected branches - NPM publishing and GitHub releases will still work --- .github/workflows/manual-release.yaml | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/.github/workflows/manual-release.yaml b/.github/workflows/manual-release.yaml index cdce467f..fe131f89 100644 --- a/.github/workflows/manual-release.yaml +++ b/.github/workflows/manual-release.yaml @@ -138,7 +138,13 @@ jobs: fi - name: Push changes to main - run: git push origin HEAD:main + run: | + if git push origin HEAD:main 2>/dev/null; then + echo "āœ… Successfully pushed to main branch" + else + echo "āš ļø Could not push to main (protected branch). This is expected." + echo "šŸ“ Version bump and tag were created successfully." + fi - name: Publish to NPM with stable tag env: From 8573852a6e76bb2b6358f6c1dda32398244b1771 Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Sat, 16 Aug 2025 20:50:22 -0500 Subject: [PATCH 06/12] 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 From c0899432c1ee6f3aa08d034517ca3484a1203cdb Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Sat, 16 Aug 2025 20:58:22 -0500 Subject: [PATCH 07/12] fix: simplify npm publishing to use latest tag only - Remove stable tag complexity from workflow - Publish directly to latest tag (default for npx) - Update documentation to reflect single tag approach --- .github/workflows/manual-release.yaml | 6 +++--- docs/versioning-and-releases.md | 8 ++++---- package.json | 2 +- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/.github/workflows/manual-release.yaml b/.github/workflows/manual-release.yaml index fe131f89..f5df668a 100644 --- a/.github/workflows/manual-release.yaml +++ b/.github/workflows/manual-release.yaml @@ -146,10 +146,10 @@ jobs: echo "šŸ“ Version bump and tag were created successfully." fi - - name: Publish to NPM with stable tag + - name: Publish to NPM env: NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} - run: npm publish --tag stable + run: npm publish - name: Create GitHub Release uses: actions/create-release@v1 @@ -165,7 +165,7 @@ jobs: - name: Summary run: | echo "šŸŽ‰ Successfully released v${{ steps.version.outputs.new_version }}!" - echo "šŸ“¦ Published to NPM with @stable tag" + echo "šŸ“¦ Published to NPM with @latest tag" echo "šŸ·ļø Git tag: v${{ steps.version.outputs.new_version }}" echo "āœ… Users running 'npx bmad-method install' will now get version ${{ steps.version.outputs.new_version }}" echo "" diff --git a/docs/versioning-and-releases.md b/docs/versioning-and-releases.md index 96f596a3..282115bb 100644 --- a/docs/versioning-and-releases.md +++ b/docs/versioning-and-releases.md @@ -39,9 +39,8 @@ When you trigger a release, the GitHub Actions workflow automatically: - šŸ”§ **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 +5. āœ… **Publishes to NPM** - With `@latest` 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 @@ -81,8 +80,8 @@ npx bmad-method install After any release, users can immediately get the new version with: ```bash -npx bmad-method install # Always gets latest stable release -```` +npx bmad-method install # Always gets latest release +``` ## šŸ“Š Preview Before Release @@ -145,3 +144,4 @@ npm view bmad-method versions --json - Check GitHub Actions logs: `gh run view --log-failed` - Verify NPM tokens are configured - Ensure branch protection allows workflow pushes +```` diff --git a/package.json b/package.json index 505cd395..f078562b 100644 --- a/package.json +++ b/package.json @@ -100,6 +100,6 @@ "node": ">=20.10.0" }, "publishConfig": { - "tag": "stable" + "access": "public" } } From f959a07bda8203f0e0358cce0e5980e693e83f0d Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Sat, 16 Aug 2025 21:04:32 -0500 Subject: [PATCH 08/12] fix: update installer package.json version to 5.1.0 - Fixes version reporting in npx bmad-method --version - Ensures installer displays correct version number --- tools/installer/package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tools/installer/package.json b/tools/installer/package.json index d168e975..5fa1e4a1 100644 --- a/tools/installer/package.json +++ b/tools/installer/package.json @@ -1,6 +1,6 @@ { "name": "bmad-method", - "version": "5.0.0", + "version": "5.1.0", "description": "BMad Method installer - AI-powered Agile development framework", "keywords": [ "bmad", From fe318ecc0789a540c4c08d4ba41cef3f358925b1 Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Sat, 16 Aug 2025 21:09:36 -0500 Subject: [PATCH 09/12] sync: update package.json to match published version 5.0.1 --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index f078562b..42063f8b 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/package.json", "name": "bmad-method", - "version": "5.0.0", + "version": "5.0.1", "description": "Breakthrough Method of Agile AI-driven Development", "keywords": [ "agile", From cf22fd98f3ac6bf7998ae8153cf3214ec1321ebb Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Sat, 16 Aug 2025 21:10:46 -0500 Subject: [PATCH 10/12] fix: correct version to 5.1.1 after patch release - npm latest tag now correctly points to 5.1.0 - package.json updated to 5.1.1 (what patch should have made) - installer version synced --- package.json | 2 +- tools/installer/package.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/package.json b/package.json index 42063f8b..23601acc 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/package.json", "name": "bmad-method", - "version": "5.0.1", + "version": "5.1.1", "description": "Breakthrough Method of Agile AI-driven Development", "keywords": [ "agile", diff --git a/tools/installer/package.json b/tools/installer/package.json index 5fa1e4a1..1e826003 100644 --- a/tools/installer/package.json +++ b/tools/installer/package.json @@ -1,6 +1,6 @@ { "name": "bmad-method", - "version": "5.1.0", + "version": "5.1.1", "description": "BMad Method installer - AI-powered Agile development framework", "keywords": [ "bmad", From 26890a0a039b2a48ae7bcb397e0c3b9a4e9ce653 Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Sat, 16 Aug 2025 21:20:17 -0500 Subject: [PATCH 11/12] sync: update versions to 5.1.2 to match published release --- package.json | 2 +- tools/installer/package.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/package.json b/package.json index 23601acc..f88e96fd 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/package.json", "name": "bmad-method", - "version": "5.1.1", + "version": "5.1.2", "description": "Breakthrough Method of Agile AI-driven Development", "keywords": [ "agile", diff --git a/tools/installer/package.json b/tools/installer/package.json index 1e826003..997ce8d9 100644 --- a/tools/installer/package.json +++ b/tools/installer/package.json @@ -1,6 +1,6 @@ { "name": "bmad-method", - "version": "5.1.1", + "version": "5.1.2", "description": "BMad Method installer - AI-powered Agile development framework", "keywords": [ "bmad", From f5272f12e49b1bfb52c3e24f4dfe64e5aee0bdbb Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Sat, 16 Aug 2025 21:35:12 -0500 Subject: [PATCH 12/12] sync: update to published version 5.1.3 --- package.json | 2 +- tools/installer/package.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/package.json b/package.json index f88e96fd..336b6dea 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/package.json", "name": "bmad-method", - "version": "5.1.2", + "version": "5.1.3", "description": "Breakthrough Method of Agile AI-driven Development", "keywords": [ "agile", diff --git a/tools/installer/package.json b/tools/installer/package.json index 997ce8d9..f538ca10 100644 --- a/tools/installer/package.json +++ b/tools/installer/package.json @@ -1,6 +1,6 @@ { "name": "bmad-method", - "version": "5.1.2", + "version": "5.1.3", "description": "BMad Method installer - AI-powered Agile development framework", "keywords": [ "bmad",