From 336de62f7b445e83b7c68d6cd3c9ce1da4d02e41 Mon Sep 17 00:00:00 2001 From: Oussama Douhou Date: Thu, 8 Jan 2026 19:49:14 +0100 Subject: [PATCH] docs: add release branch workflow for selective feature inclusion --- GIT_STRATEGY.md | 402 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 402 insertions(+) create mode 100644 GIT_STRATEGY.md diff --git a/GIT_STRATEGY.md b/GIT_STRATEGY.md new file mode 100644 index 0000000..ac3e463 --- /dev/null +++ b/GIT_STRATEGY.md @@ -0,0 +1,402 @@ +# 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/todo-codebase-compaction` | +| **Bug Fixes** | `fix/` | `fix/compaction-threshold-calculation` | +| **Refactoring** | `refactor/` | `refactor/hook-injection-logic` | +| **Experiments** | `experiment/` | `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 + +```bash +# 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 + +# 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 + +```bash +# Find the merge commit +git log --oneline --merges release + +# Revert the merge +git revert -m 1 + +# Push +git push gitea release +``` + +### Syncing Release with Upstream + +```bash +# 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 + +```bash +# 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 + +```bash +# 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 + +```bash +# 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 + +```bash +# 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 +# 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 + +```bash +# 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 + +```bash +# 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 + +```bash +# 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 + +```bash +# 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 +```bash +# Find lost commits +git reflog + +# Restore from reflog +git checkout +git branch recovery-branch +``` + +### Upstream Conflicts +```bash +# 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 +```bash +# Fresh clone and reapply changes +cd .. +rm -rf oh-my-opencode-free-fork +git clone 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](https://nvie.com/posts/a-successful-git-branching-model/) +- [Conventional Commits](https://conventionalcommits.org/) +- [Git Rebase vs Merge](https://www.atlassian.com/git/tutorials/merging-vs-rebasing) + +--- + +## 📝 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.* \ No newline at end of file