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)

# 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:

./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

# 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