oussamadouhou/oh-my-opencode-free-fork
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add release branch workflow for selective feature inclusion

Browse Source
This commit is contained in:
Oussama Douhou
2026-01-08 19:49:14 +01:00
parent 9bff359782
commit 336de62f7b
1 changed files with 402 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

402
GIT_STRATEGY.md Normal file
View File

@@ -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-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.*