From 598476d3b5e4adebe76fc747687541e3cbd6debf Mon Sep 17 00:00:00 2001
From: Steve Yegge <steve.yegge@gmail.com>
Date: Thu, 16 Oct 2025 15:36:58 -0700
Subject: [PATCH] Add release process documentation

---
 RELEASING.md        | 150 ++++++++++++++++++++++++++++++++++++++++++++
 bd-formula-0.9.8.rb |  29 +++++++++
 2 files changed, 179 insertions(+)
 create mode 100644 RELEASING.md
 create mode 100644 bd-formula-0.9.8.rb

diff --git a/RELEASING.md b/RELEASING.md
new file mode 100644
index 00000000..66fda0fb
--- /dev/null
+++ b/RELEASING.md
@@ -0,0 +1,150 @@
+# Release Process
+
+Quick guide for releasing a new version of beads.
+
+## Pre-Release Checklist
+
+1. **Run tests and build**:
+   ```bash
+   go test ./...
+   golangci-lint run ./...
+   go build -o bd ./cmd/bd
+   ```
+
+2. **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
+
+3. **Commit changelog**:
+   ```bash
+   git add CHANGELOG.md
+   git commit -m "Add 0.9.X release notes"
+   ```
+
+## Version Bump
+
+Use the automated script to update all version files:
+
+```bash
+./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
+
+```bash
+git tag v0.9.X
+git push origin main
+git push origin v0.9.X
+```
+
+### 2. Publish to PyPI (MCP Server)
+
+```bash
+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](integrations/beads-mcp/PYPI.md) for detailed PyPI instructions.
+
+### 3. Update Homebrew Formula
+
+The formula needs the SHA256 of the tag tarball:
+
+```bash
+# 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
+
+# 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 to 0.9.X"
+git push origin main
+```
+
+Users can then upgrade with:
+```bash
+brew update
+brew upgrade bd
+```
+
+### 4. Create GitHub Release
+
+1. Go to https://github.com/steveyegge/beads/releases/new
+2. Choose tag: `v0.9.X`
+3. Title: `v0.9.X`
+4. Description: Copy from CHANGELOG.md
+5. Attach binaries (optional - GitHub Actions can automate this)
+6. Publish release
+
+## Post-Release
+
+1. **Verify installations**:
+   ```bash
+   # 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 Ideas (Future)
+
+Consider GitHub Actions to:
+- Run tests on tag push
+- Auto-build and publish to PyPI
+- Auto-update Homebrew formula
+- Create GitHub release with binaries
+
+## Related Documentation
+
+- [CHANGELOG.md](CHANGELOG.md) - Release history
+- [scripts/README.md](scripts/README.md) - Version bump script details
+- [integrations/beads-mcp/PYPI.md](integrations/beads-mcp/PYPI.md) - Detailed PyPI guide
diff --git a/bd-formula-0.9.8.rb b/bd-formula-0.9.8.rb
new file mode 100644
index 00000000..d15b0bfe
--- /dev/null
+++ b/bd-formula-0.9.8.rb
@@ -0,0 +1,29 @@
+class Bd < Formula
+  desc "AI-supervised issue tracker for coding workflows"
+  homepage "https://github.com/steveyegge/beads"
+  url "https://github.com/steveyegge/beads/archive/refs/tags/v0.9.8.tar.gz"
+  sha256 "f5c35edaea7f12013cc3ce2237971ae188be226ae3eb6fad18f2f3afbf83d73f"
+  license "MIT"
+  head "https://github.com/steveyegge/beads.git", branch: "main"
+
+  depends_on "go" => :build
+
+  def install
+    # Build the CLI
+    system "go", "build", *std_go_args(ldflags: "-s -w -X main.Version=#{version}"), "./cmd/bd"
+  end
+
+  test do
+    # Test that the binary runs and outputs version
+    output = shell_output("#{bin}/bd version")
+    assert_match "bd version #{version}", output
+
+    # Test init command
+    system bin/"bd", "init", "--prefix=test"
+    assert_predicate testpath/".beads/test.db", :exist?
+
+    # Test list command (should show no issues)
+    list_output = shell_output("#{bin}/bd list --db=#{testpath}/.beads/test.db")
+    assert_match "Found 0 issues", list_output
+  end
+end