beads/RELEASING.md

Release Process

Quick guide for releasing a new version of beads.

Pre-Release Checklist

1. Kill all running daemons:

   pkill -f "bd.*daemon"
   

2. Run tests and build:

   TMPDIR=/tmp go test ./...
   golangci-lint run ./...
   TMPDIR=/tmp go build -o bd ./cmd/bd
   

3. Update local Go install:

   TMPDIR=/tmp go install ./cmd/bd
   bd version  # Verify it shows new version
   

4. Update CHANGELOG.md:

   • Add version heading: ## [0.9.X] - YYYY-MM-DD
   • Summarize changes under: Added, Fixed, Changed, Performance, Community
   • Update Version History section
   • Add Upgrade Guide section if needed

5. Commit changelog:

   git add CHANGELOG.md
   git commit -m "Add 0.9.X release notes"
   

Version Bump

Use the automated script to update all version files:

./scripts/bump-version.sh 0.9.X --commit

This updates:

• cmd/bd/version.go
• .claude-plugin/plugin.json
• .claude-plugin/marketplace.json
• integrations/beads-mcp/pyproject.toml
• integrations/beads-mcp/src/beads_mcp/__init__.py
• README.md
• PLUGIN.md

Publish to All Channels

1. Create Git Tag

git tag v0.9.X
git push origin main
git push origin v0.9.X

2. Publish to PyPI (MCP Server)

cd integrations/beads-mcp

# Clean and rebuild
rm -rf dist/ build/ src/*.egg-info
uv build

# Upload to PyPI
python3 -m twine upload dist/*
# Username: __token__
# Password: <your PyPI API token>

See integrations/beads-mcp/PYPI.md for detailed PyPI instructions.

3. Update Homebrew Formula

The formula needs the SHA256 of the tag tarball:

# Compute SHA256 from tag
curl -sL https://github.com/steveyegge/beads/archive/refs/tags/v0.9.X.tar.gz | shasum -a 256

# Clone tap repo (if not already)
git clone https://github.com/steveyegge/homebrew-beads /tmp/homebrew-beads
cd /tmp/homebrew-beads
git config user.name "Your Name"
git config user.email "your.email@example.com"

# Update Formula/bd.rb:
# - url: https://github.com/steveyegge/beads/archive/refs/tags/v0.9.X.tar.gz
# - sha256: <computed SHA256>

# Commit and push
git add Formula/bd.rb
git commit -m "Update bd formula to v0.9.X"
git push origin main

Install/upgrade locally with:

brew update
brew uninstall bd
brew install --build-from-source bd
bd version  # Verify it shows new version

4. GitHub Releases (Automated)

GoReleaser automatically creates releases when you push tags!

The .github/workflows/release.yml workflow:

• Triggers on v* tags
• Builds cross-platform binaries (Linux, macOS, Windows for amd64/arm64)
• Generates checksums
• Creates GitHub release with binaries and changelog
• Publishes release automatically

Just push your tag and wait ~5 minutes:

git push origin v0.9.X

Monitor at: https://github.com/steveyegge/beads/actions

The release will appear at: https://github.com/steveyegge/beads/releases

Post-Release

1. Verify installations:

   # Homebrew
   brew update && brew upgrade bd && bd version
   
   # PyPI
   pip install --upgrade beads-mcp
   beads-mcp --help
   

2. Announce (optional):

   • Project Discord/Slack
   • Twitter/social media
   • README badges

Troubleshooting

Stale dist/ directory

Always rm -rf dist/ before uv build to avoid uploading old versions.

PyPI version conflict

PyPI doesn't allow re-uploading same version. Increment version number even for fixes.

Homebrew SHA256 mismatch

Wait a few seconds after pushing tag for GitHub to make tarball available, then recompute SHA256.

Missing PyPI credentials

Set up API token at https://pypi.org/manage/account/token/ and use __token__ as username.

Automation Status

✅ Automated:

• GitHub releases with binaries (GoReleaser + GitHub Actions)
• Cross-platform builds (Linux, macOS, Windows)
• Checksums and changelog generation

🔄 TODO:

• Auto-publish to PyPI
• Auto-update Homebrew formula

Related Documentation

• CHANGELOG.md - Release history
• scripts/README.md - Version bump script details
• integrations/beads-mcp/PYPI.md - Detailed PyPI guide