mirror of
https://gitea.toothfairyai.com/ToothFairyAI/tf_code.git
synced 2026-04-19 15:14:49 +00:00
feat: initialize tfcode project structure
- Add README.md as living documentation - Add tfcode.json schema and config template - Add FORK_MANAGEMENT.md with mirror-based fork strategy - Add scripts/rebrand.sh for reapplying branding after upstream merges - Add packages/tf-sync Python module using official ToothFairyAI SDK - Add packages/tf-mcp-bridge TypeScript module (stub) - Multi-region support (AU, EU, US) - Tool sync: MCP servers, Agent Skills, Database Scripts, API Functions
This commit is contained in:
Gab
218
FORK_MANAGEMENT.md
Normal file
218
FORK_MANAGEMENT.md
Normal file
@@ -0,0 +1,218 @@
|
||||
# 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
|
||||
```
|
||||
Reference in New Issue
Block a user