diff --git a/.beads/formulas/beads-release.formula.toml b/.beads/formulas/beads-release.formula.toml new file mode 100644 index 00000000..ef26f926 --- /dev/null +++ b/.beads/formulas/beads-release.formula.toml @@ -0,0 +1,345 @@ +description = """ +Beads release workflow - from version bump to verified release. + +This formula orchestrates a complete release cycle: +1. Preflight checks (clean git, up to date) +2. Documentation updates (CHANGELOG, info.go) +3. Version bump (all components) +4. Git operations (commit, tag, push) +5. CI verification (GitHub Actions) +6. Artifact verification (GitHub, npm, PyPI) +7. Local installation update +8. Daemon restart + +## Usage + +```bash +bd wisp create beads-release --var version=0.37.0 +``` + +Or assign to a polecat: +```bash +gt sling beads/polecats/p1 --formula beads-release --var version=0.37.0 +``` +""" +formula = "beads-release" +type = "workflow" +version = 1 + +[vars.version] +description = "The semantic version to release (e.g., 0.37.0)" +required = true + +[[steps]] +id = "preflight-git" +title = "Preflight: Check git status" +description = """ +Ensure working tree is clean before starting release. + +```bash +git status +``` + +If there are uncommitted changes, either: +- Commit them first +- Stash them: `git stash` +- Abort and resolve +""" + +[[steps]] +id = "preflight-pull" +title = "Preflight: Pull latest" +needs = ["preflight-git"] +description = """ +Ensure we're up to date with origin. + +```bash +git pull --rebase +``` + +Resolve any conflicts before proceeding. +""" + +[[steps]] +id = "review-changes" +title = "Review changes since last release" +needs = ["preflight-pull"] +description = """ +Understand what's being released. + +```bash +git log $(git describe --tags --abbrev=0)..HEAD --oneline +``` + +Categorize changes: +- Features (feat:) +- Fixes (fix:) +- Breaking changes +- Documentation +""" + +[[steps]] +id = "update-changelog" +title = "Update CHANGELOG.md" +needs = ["review-changes"] +description = """ +Write the [Unreleased] section with all changes for {{version}}. + +Format: Keep a Changelog (https://keepachangelog.com) + +Sections: +- ### Added +- ### Changed +- ### Fixed +- ### Documentation + +The bump script will stamp the date automatically. +""" + +[[steps]] +id = "update-info-go" +title = "Update info.go versionChanges" +needs = ["update-changelog"] +description = """ +Add entry to versionChanges in cmd/bd/info.go. + +This powers `bd info --whats-new` for agents. + +```go +"{{version}}": { + "summary": "Brief description", + "changes": []string{ + "Key change 1", + "Key change 2", + }, +}, +``` + +Focus on workflow-impacting changes agents need to know. +""" + +[[steps]] +id = "run-bump-script" +title = "Run bump-version.sh" +needs = ["update-info-go"] +description = """ +Update all component versions atomically. + +```bash +./scripts/bump-version.sh {{version}} +``` + +This updates: +- cmd/bd/version.go +- .claude-plugin/*.json +- integrations/beads-mcp/pyproject.toml +- integrations/beads-mcp/src/beads_mcp/__init__.py +- npm-package/package.json +- Hook templates +- README.md +- CHANGELOG.md (adds date) +""" + +[[steps]] +id = "verify-versions" +title = "Verify version consistency" +needs = ["run-bump-script"] +description = """ +Confirm all versions match {{version}}. + +```bash +grep 'Version = ' cmd/bd/version.go +jq -r '.version' .claude-plugin/plugin.json +jq -r '.version' npm-package/package.json +grep 'version = ' integrations/beads-mcp/pyproject.toml +``` + +All should show {{version}}. +""" + +[[steps]] +id = "commit-release" +title = "Commit release" +needs = ["verify-versions"] +description = """ +Stage and commit all version changes. + +```bash +git add -A +git commit -m "chore: Bump version to {{version}}" +``` + +Review the commit to ensure all expected files are included. +""" + +[[steps]] +id = "create-tag" +title = "Create release tag" +needs = ["commit-release"] +description = """ +Create annotated git tag. + +```bash +git tag -a v{{version}} -m "Release v{{version}}" +``` + +Verify: `git tag -l | tail -5` +""" + +[[steps]] +id = "push-main" +title = "Push to main" +needs = ["create-tag"] +description = """ +Push the release commit to origin. + +```bash +git push origin main +``` + +If rejected, someone else pushed. Pull, rebase, try again. +""" + +[[steps]] +id = "push-tag" +title = "Push release tag" +needs = ["push-main"] +description = """ +Push the version tag to trigger CI release. + +```bash +git push origin v{{version}} +``` + +This triggers GitHub Actions to build artifacts and publish. +""" + +[[steps]] +id = "wait-ci" +title = "Wait for CI" +needs = ["push-tag"] +description = """ +Monitor GitHub Actions for release completion. + +https://github.com/steveyegge/beads/actions + +Expected time: 5-10 minutes + +Watch for: +- Build artifacts (all platforms) +- Test suite pass +- npm publish +- PyPI publish +""" + +[[steps]] +id = "verify-github-release" +title = "Verify GitHub release" +needs = ["wait-ci"] +description = """ +Check the GitHub releases page. + +https://github.com/steveyegge/beads/releases/tag/v{{version}} + +Verify: +- Release created +- Binaries attached (linux, darwin, windows) +- Checksums present +""" + +[[steps]] +id = "verify-npm" +title = "Verify npm package" +needs = ["verify-github-release"] +description = """ +Confirm npm package published. + +```bash +npm show @beads/bd version +``` + +Should show {{version}}. + +Also check: https://www.npmjs.com/package/@beads/bd +""" + +[[steps]] +id = "verify-pypi" +title = "Verify PyPI package" +needs = ["verify-github-release"] +description = """ +Confirm PyPI package published. + +```bash +pip index versions beads-mcp 2>/dev/null | head -3 +``` + +Or check: https://pypi.org/project/beads-mcp/ + +Should show {{version}}. +""" + +[[steps]] +id = "local-install" +title = "Update local installation" +needs = ["verify-npm", "verify-pypi"] +description = """ +Update local bd to the new version. + +Option 1 - Homebrew: +```bash +brew upgrade bd +``` + +Option 2 - Install script: +```bash +curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash +``` + +Verify: +```bash +bd --version +``` + +Should show {{version}}. +""" + +[[steps]] +id = "restart-daemons" +title = "Restart daemons" +needs = ["local-install"] +description = """ +Restart bd daemons to pick up new version. + +```bash +bd daemons killall +``` + +Daemons will auto-restart with new version on next bd command. + +Verify: +```bash +bd daemons list +``` +""" + +[[steps]] +id = "release-complete" +title = "Release complete" +needs = ["restart-daemons"] +description = """ +Release v{{version}} is complete! + +Summary: +- All version files updated +- Git tag pushed +- CI artifacts built +- npm and PyPI packages published +- Local installation updated +- Daemons restarted + +Optional next steps: +- Announce on social media +- Update documentation site +- Close related milestone +"""