166d66205c
Fixes GH#409 - Documentation inconsistently referred to beads.jsonl as the canonical filename when issues.jsonl has been the default since v0.25.1 (bd-6xd). Updated files: - docs/ARCHITECTURE.md - docs/CLI_REFERENCE.md - docs/PROTECTED_BRANCHES.md - docs/ADVANCED.md - docs/GIT_INTEGRATION.md - docs/MULTI_REPO_AGENTS.md - docs/MULTI_REPO_MIGRATION.md - docs/TROUBLESHOOTING.md - examples/*/README.md - skills/beads/references/CLI_REFERENCE.md Note: beads.jsonl is still supported for backward compatibility. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
212 lines
5.0 KiB
Markdown
212 lines
5.0 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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`:
|
|
|
|
```yaml
|
|
contributor:
|
|
planning_repo: ~/.beads-planning
|
|
auto_route: true
|
|
```
|
|
|
|
### Manual Configuration
|
|
|
|
If you prefer manual setup:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
bd create "Document new API" -p 2 --source-repo .
|
|
```
|
|
|
|
### Q: Can I change the planning repo location?
|
|
|
|
A: Yes, configure it:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
bd config set contributor.auto_route false
|
|
```
|
|
|
|
## See Also
|
|
|
|
- [Multi-Repo Migration Guide](../../docs/MULTI_REPO_MIGRATION.md)
|
|
- [Team Workflow Example](../team-workflow/)
|
|
- [Protected Branch Setup](../protected-branch/)
|