tf_code/FORK_MANAGEMENT.md

# tfcode Fork Management Strategy

> How we manage the soft fork of opencode for tfcode development

---

## Repository Architecture

### Three-Repo Model

| Repo | URL | Purpose | Access |
|------|-----|---------|--------|
| **Upstream** | `github.com/anomalyco/opencode` | Official source, releases | Read-only |
| **Mirror** | `gitea.toothfairyai.com/GitHub/opencode` | Auto-mirror of upstream | Read-only |
| **Development** | `gitea.toothfairyai.com/ToothFairyAI/tf_code` | Our fork, tfcode product | Read-write |

### Visual Flow

```
┌─────────────────────────────────────────────────────────────────────┐
│                                                                     │
│   UPSTREAM                   MIRROR                    DEV REPO     │
│   (Official)                 (Reference)               (Our Fork)   │
│                                                                     │
│   ┌───────────┐             ┌───────────┐            ┌───────────┐│
│   │           │             │           │            │           ││
│   │  opencode │───auto────▶│  opencode │──manual──▶│  tf_code  ││
│   │  (github) │   mirror    │  (gitea)  │   PR sync │  (gitea)  ││
│   │           │             │           │            │           ││
│   └───────────┘             └───────────┘            └───────────┘│
│        │                          │                        │        │
│        │                          │                        │        │
│   Releases                  Releases +                tfcode       │
│   (v1.x.x)                 Commit history             product      │
│                                                     + TF integrations│
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘
```

---

## Sync Workflow

### Per-Release Sync Process

When a new opencode release is published:

**1. Mirror Updates** (Automatic)
- Gitea automatically mirrors the new release
- Tags appear in `GitHub/opencode` repo

**2. Create Sync PR** (Manual)
```bash
# In tf_code repo
git remote add mirror https://gitea.toothfairyai.com/GitHub/opencode.git
git fetch mirror --tags

# Create sync branch from latest release
git checkout -b sync/v1.3.0
git merge mirror/dev --no-commit

# Review conflicts, resolve manually
# Reapply branding changes if needed

# Push and create PR
git push origin sync/v1.3.0
```

**3. Evaluate Merge**
- Review all changes from upstream
- Check for breaking changes
- Verify branding still applies
- Test ToothFairyAI integrations

**4. Merge to Main**
- If approved, merge PR to `main`
- If rejected, note incompatibilities for later work

---

## Rebrand Tracking

### What Needs Rebranding

| Category | Original | Rebranded | Files Affected |
|----------|----------|-----------|----------------|
| **Command** | `opencode` | `tfcode` | CLI, scripts |
| **Package** | `opencode-ai` | `tfcode` | package.json, pyproject.toml |
| **Config** | `opencode.json` | `tfcode.json` | config loaders |
| **Env vars** | `OPENCODE_*` | `TFCODE_*` | documentation, code |
| **URLs** | `opencode.ai` | `toothfairyai.com` | docs, links |
| **Directories** | `.opencode/` | `.tfcode/` | config paths |
| **Branding** | opencode logos | tfcode logos | assets/ |

### Rebrand Script

After each upstream merge, run rebrand script:

```bash
./scripts/rebrand.sh
```

---

## Gitea Configuration

### Mirror Setup

In Gitea admin panel for `GitHub/opencode`:

```
Mirror Settings:
- URL: https://github.com/anomalyco/opencode.git
- Sync Interval: 30 minutes
- Sync: Enable
- LFS: Enable if used
```

---

## Conflict Resolution Guidelines

### Common Conflict Areas

| Area | Conflict Likelihood | Resolution Strategy |
|------|---------------------|---------------------|
| Package.json | High | Keep tfcode name, merge deps |
| Config schemas | Medium | Merge both schemas |
| CLI commands | High | Keep tfcode branding |
| Core engine | Low | Usually clean merge |
| UI/Themes | Medium | Keep tfcode branding |

### Conflict Resolution Process

1. **Identify conflict type**:
   - Branding conflict (expected, reapply our changes)
   - Feature conflict (evaluate which to keep)
   - Breaking change (may require code updates)

2. **Resolution priority**:
   - Keep upstream core changes (features, fixes)
   - Reapply our branding on top
   - Preserve TF integrations

3. **Test after merge**:
   - Run test suite
   - Verify tfcode branding intact
   - Test TF tool sync functionality

---

## Release Schedule

### Upstream Sync Cadence

| Trigger | Action |
|---------|--------|
| **Minor release** (v1.x.0) | Full sync PR, thorough review |
| **Patch release** (v1.x.y) | Quick sync PR, focus on bug fixes |
| **Major release** (v2.0.0) | Careful evaluation, may defer |

### Our Release Process

1. Sync from upstream (if available)
2. Test tfcode functionality
3. Update version in package files
4. Tag release in tf_code repo
5. Build and publish packages

---

## Do's and Don'ts

### ✅ Do

- Keep upstream code changes when merging
- Reapply branding after merges
- Test thoroughly after each sync
- Document any breaking changes from upstream
- Maintain separate release notes for tfcode

### ❌ Don't

- Don't modify mirror repo (read-only)
- Don't skip conflict resolution
- Don't auto-merge without review
- Don't lose TF integration changes during merge
- Don't contribute back to opencode directly (unless agreed)

---

## Quick Reference Commands

```bash
# Add mirror remote (one-time setup)
git remote add mirror https://gitea.toothfairyai.com/GitHub/opencode.git

# Fetch latest from mirror
git fetch mirror --tags

# Check what's new since last sync
git log HEAD..mirror/dev --oneline

# Create sync PR branch
git checkout -b sync/v1.3.0
git merge mirror/dev

# After resolving conflicts
./scripts/rebrand.sh  # Reapply branding
npm test              # Test
git push origin sync/v1.3.0

# Merge PR after approval
git checkout main
git merge --no-ff sync/v1.3.0
git push origin main
git tag v1.3.0-tf.1
```