oh-my-opencode-free-fork/GIT_STRATEGY.md

Git Strategy and Workflow - Oh My OpenCode Free Fork

This document outlines the git workflow and branching strategy for the oh-my-opencode-free fork, ensuring clean development, easy upstream updates, and professional collaboration.

🏗️ Branch Structure

Main Branches

Branch	Purpose	Protection	Upstream Tracking
dev	Main development branch	✅ Protected	origin/dev
main	Stable releases (future)	✅ Protected	-

Release Branch (Selective Features)

Branch	Purpose	Protection
release	Production-ready with selected features only	✅ Protected

The release branch contains only approved features cherry-picked from dev. This allows:

• Excluding experimental or unstable features
• Building Docker images with specific feature sets
• Clean separation between development and production

Feature Branches

Branch Type	Naming Convention	Example
Features	feature/<feature-name>	feature/todo-codebase-compaction
Bug Fixes	fix/<issue-description>	fix/compaction-threshold-calculation
Refactoring	refactor/<component>	refactor/hook-injection-logic
Experiments	experiment/<idea>	experiment/alternative-compaction-prompt

🎯 Release Branch Workflow (Selective Features)

The release branch is used by the oh-my-opencode-free Docker build. Only merge features you want in production.

Branch Flow Diagram

upstream (origin/dev) ──────────────────────────────► upstream updates
         │
         ▼
dev ─────┬──────────────────────────────────────────► all features
         │
         ├── feature/todo-compaction      ✓ merge to release
         ├── feature/parallel-agents      ✓ merge to release  
         └── feature/experimental         ✗ skip (not ready)
         │
         ▼
release ─────────────────────────────────────────────► selected features only
         │
         ▼
Docker build (oh-my-opencode-free)

Adding Features to Release

# Ensure release branch exists and is current
git checkout release
git pull gitea release

# Merge a specific feature from dev
git merge feature/todo-compaction --no-ff -m "release: add todo-compaction feature"

# Or cherry-pick specific commits
git cherry-pick <commit-hash>

# Test the build
bun install && bun run build && bun run typecheck

# Push to Gitea (triggers Docker rebuild if CI configured)
git push gitea release

Removing Features from Release

# Find the merge commit
git log --oneline --merges release

# Revert the merge
git revert -m 1 <merge-commit-hash>

# Push
git push gitea release

Syncing Release with Upstream

# Update dev from upstream first
git checkout dev
git fetch origin
git merge origin/dev

# Then selectively update release
git checkout release

# Option 1: Rebase release onto new dev (keeps feature selection)
git rebase dev

# Option 2: Reset and re-merge features (clean slate)
git reset --hard dev~5  # Go back to before your features
git merge feature/todo-compaction --no-ff
git merge feature/parallel-agents --no-ff
# Skip features you don't want

git push gitea release --force-with-lease

Listing Features in Release vs Dev

# Show what's in release but not in dev (your additions)
git log --oneline release ^dev

# Show what's in dev but not in release (excluded features)
git log --oneline dev ^release

---

🚀 Development Workflow

1. Starting a New Feature

# Ensure you're on latest dev
git checkout dev
git pull origin dev

# Create feature branch
git checkout -b feature/your-feature-name

# Develop and commit
git add .
git commit -m "feat: Add your feature description"

# Push feature branch (optional, for collaboration)
git push -u origin feature/your-feature-name

2. Feature Development

# Regular development cycle
git add .
git commit -m "feat: Implement core logic"

# Test your changes
bun run build && bun run typecheck

# Make more commits as needed
git commit -m "fix: Handle edge case"

3. Merging to Dev

# Switch to dev and ensure it's up to date
git checkout dev
git pull origin dev

# Merge feature branch
git merge feature/your-feature-name

# If merge conflicts, resolve them:
# 1. Edit conflicted files
# 2. git add <resolved-files>
# 3. git commit

# Push merged changes
git push origin dev

# Clean up feature branch
git branch -d feature/your-feature-name

4. Handling Upstream Updates

# Fetch latest upstream changes
git fetch origin

# Check what changed
git log --oneline origin/dev ^dev

# Option 1: Rebase (clean history)
git rebase origin/dev

# Option 2: Merge (preserve history)
git merge origin/dev

# Resolve any conflicts and push
git push origin dev

📋 Commit Message Convention

Follow conventional commits for consistency:

type(scope): description

[optional body]

[optional footer]

Types

• feat: New features
• fix: Bug fixes
• docs: Documentation
• style: Code style changes
• refactor: Code refactoring
• test: Testing
• chore: Maintenance

Examples

feat: Add custom todo+codebase compaction hook
fix: Resolve compaction threshold calculation bug
docs: Update git strategy documentation
refactor: Simplify hook injection logic

🔄 Update Strategy for Upstream Changes

Scenario: Upstream Releases New Features

# Backup current state
git branch backup-$(date +%Y%m%d)

# Option A: Rebase (Recommended)
git fetch origin
git rebase origin/dev
# Resolve conflicts if any
git rebase --continue

# Option B: Merge
git fetch origin
git merge origin/dev

# Test that custom features still work
bun install && bun run build && bun run typecheck

# Push updated dev
git push origin dev

Conflict Resolution Guidelines

1. Prioritize Custom Features: Keep your custom logic when conflicts occur
2. Test Thoroughly: Ensure custom compaction still works after merges
3. Document Changes: Update this doc if workflow changes
4. Backup First: Always create backups before major operations

🛡️ Quality Assurance

Pre-Merge Checklist

• Build passes: bun run build
• Types check: bun run typecheck
• Tests pass: bun run test (if applicable)
• Custom features work: Test compaction, agents, etc.
• No console errors: Clean build output
• Documentation updated: README, this doc, etc.

Post-Merge Verification

# Full verification script
bun install
bun run build
bun run typecheck

# Test custom features
ls src/hooks/todo-codebase-compaction/
grep "custom_compaction" src/config/schema.ts

echo "✅ All checks passed!"

🤝 Collaboration Guidelines

For Team Members

1. Never commit directly to dev - Always use feature branches
2. Keep feature branches focused - One feature per branch
3. Regular rebasing - Keep up with upstream changes
4. Clear commit messages - Follow conventional commits
5. Test before merging - Ensure no regressions

Code Review Process

# Before merging, get review
gh pr create --base dev --head feature/your-feature

# Or manual review
git diff dev..feature/your-feature

🏷️ Tagging Strategy

Version Tags (Future)

v1.0.0     # First stable release
v1.1.0     # Feature release
v1.1.1     # Bug fix release

Feature Tags

feature/compaction-v1    # Major feature milestone
experiment/alternative-prompts    # Experimental features

🚨 Emergency Procedures

Lost Commits

# Find lost commits
git reflog

# Restore from reflog
git checkout <commit-hash>
git branch recovery-branch

Upstream Conflicts

# Abort and try different strategy
git rebase --abort
git merge origin/dev    # Try merge instead

# Or create fresh feature branch
git checkout -b feature/fresh-start origin/dev
# Re-implement changes

Repository Corruption

# Fresh clone and reapply changes
cd ..
rm -rf oh-my-opencode-free-fork
git clone <your-gitea-url> oh-my-opencode-free-fork
cd oh-my-opencode-free-fork
# Reapply custom changes from backups

📊 Metrics and Monitoring

Branch Health

• Max feature branch age: 2 weeks
• Max dev branch divergence: 5 commits
• Required reviews: 1 reviewer for merges

Quality Metrics

• Build success rate: >95%
• Test coverage: Track and improve
• Merge conflict rate: <10%

🎯 Best Practices

General

• Small, focused commits - Easier to review and revert
• Regular pushes - Don't accumulate large changes
• Clear naming - Descriptive branch and commit names
• Documentation - Keep this and README updated

Custom Features

• Isolate custom code - Keep it separate from upstream changes
• Test compatibility - Ensure custom features work with upstream updates
• Document overrides - Note where you deviate from upstream
• Plan for conflicts - Have strategies for resolving upstream conflicts

Performance

• Fast-forward merges - Prefer rebase for clean history
• Shallow clones - For CI/CD if needed
• Branch cleanup - Delete merged branches regularly

📚 Resources

• Git Flow
• Conventional Commits
• Git Rebase vs Merge

---

📝 Change Log

• 2026-01-08: Initial git strategy documentation
• 2026-01-08: Added custom compaction workflow
• 2026-01-08: Established feature branch workflow

---

This strategy ensures clean, maintainable development while preserving your custom oh-my-opencode features.