# 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

```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 <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

```bash
# 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

```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 <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

```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 <commit-hash>
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 <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](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.*