beads/examples/contributor-workflow/README.md

OSS Contributor Workflow Example

This example demonstrates how to use beads' contributor workflow to keep your planning issues separate from upstream PRs when contributing to open-source projects.

Problem

When contributing to OSS projects, you want to:

• Track your planning, todos, and design notes
• Keep experimental work organized
• NOT pollute upstream PRs with your personal planning issues

Solution

Use bd init --contributor to set up a separate planning repository that never gets committed to the upstream project.

Setup

Step 1: Fork and Clone

# Fork the project on GitHub, then clone your fork
git clone https://github.com/YOUR_USERNAME/project.git
cd project

# Add upstream remote (important for fork detection!)
git remote add upstream https://github.com/ORIGINAL_OWNER/project.git

Step 2: Initialize Beads with Contributor Wizard

# Run the contributor setup wizard
bd init --contributor

The wizard will:

1. ✅ Detect that you're in a fork (checks for 'upstream' remote)
2. ✅ Prompt you to create a planning repo (~/.beads-planning by default)
3. ✅ Configure auto-routing so your planning stays separate
4. ✅ Initialize the planning repo with git

Step 3: Start Working

# Create a planning issue
bd create "Plan how to fix bug X" -p 2

# This issue goes to ~/.beads-planning automatically!

How It Works

Auto-Routing

When you create issues as a contributor:

bd create "Fix authentication bug" -p 1

Beads automatically routes this to your planning repo (~/.beads-planning/.beads/issues.jsonl), not the current repo.

Viewing Issues

# See all issues (from both repos)
bd list

# See only current repo issues
bd list --source-repo .

# See only planning issues
bd list --source-repo ~/.beads-planning

Discovered Work

When you discover work while implementing:

# The new issue inherits source_repo from parent
bd create "Found edge case in auth" -p 1 --deps discovered-from:bd-42

Committing Code (Not Planning)

Your code changes get committed to the fork, but planning issues stay separate:

# Only commits to fork (not planning repo)
git add src/auth.go
git commit -m "Fix: authentication bug"
git push origin my-feature-branch

Your planning issues in ~/.beads-planning never appear in PRs.

Example Workflow

# 1. Create fork and clone
git clone https://github.com/you/upstream-project.git
cd upstream-project
git remote add upstream https://github.com/upstream/upstream-project.git

# 2. Run contributor setup
bd init --contributor
# Wizard detects fork ✓
# Creates ~/.beads-planning ✓
# Configures auto-routing ✓

# 3. Plan your work (routes to planning repo)
bd create "Research how auth module works" -p 2
bd create "Design fix for bug #123" -p 1
bd ready  # Shows planning issues

# 4. Implement (commit code only)
git checkout -b fix-auth-bug
# ... make changes ...
git add . && git commit -m "Fix: auth bug"

# 5. Track discovered work (stays in planning repo)
bd create "Found related issue in logout" -p 2 --deps discovered-from:bd-abc

# 6. Push code (planning never included)
git push origin fix-auth-bug
# Create PR on GitHub - zero planning pollution!

# 7. Clean up after PR merges
bd close bd-abc --reason "PR merged"

Configuration

The wizard configures these settings in .beads/beads.db:

contributor:
  planning_repo: ~/.beads-planning
  auto_route: true

Manual Configuration

If you prefer manual setup:

# Initialize beads normally
bd init

# Configure planning repo
bd config set contributor.planning_repo ~/.beads-planning
bd config set contributor.auto_route true

Multi-Repository View

Beads aggregates issues from multiple repos:

# List issues from all configured repos
bd list

# Filter by source repository
bd list --source-repo .                    # Current repo only
bd list --source-repo ~/.beads-planning    # Planning repo only

Benefits

✅ Clean PRs - No personal todos in upstream contributions ✅ Private planning - Experimental work stays local ✅ Git ledger - Everything is version controlled ✅ Unified view - See all issues with bd list ✅ Auto-routing - No manual sorting needed

Common Questions

Q: What if I want some issues in the upstream repo?

A: Override auto-routing with --source-repo flag:

bd create "Document new API" -p 2 --source-repo .

Q: Can I change the planning repo location?

A: Yes, configure it:

bd config set contributor.planning_repo /path/to/my-planning

Q: What if I have push access to upstream?

A: The wizard will ask if you want a planning repo anyway. You can say "no" to store everything in the current repo.

Q: How do I disable auto-routing?

A: Turn it off:

bd config set contributor.auto_route false

See Also

• Multi-Repo Migration Guide
• Team Workflow Example
• Protected Branch Setup