From 4e8745e711a2fb8860964bdf94ee2a2868b3c221 Mon Sep 17 00:00:00 2001 From: drunkonjava Date: Thu, 31 Jul 2025 18:22:42 -0400 Subject: [PATCH] docs: Add comprehensive hybrid workflow documentation Add detailed guide for the hybrid workflow implementation including: - Overview of main/dev branch strategy - Step-by-step workflows for common tasks - Tool usage instructions (claude-branch.sh, apply-branch-protection.sh) - Best practices for both Claude and human developers - Migration guide for adopting the workflow - Troubleshooting common issues - Philosophy behind the hybrid approach This documentation serves as the primary reference for understanding and using the hybrid workflow effectively. Part 4 of the hybrid workflow implementation. Co-authored-by: Claude --- .github/HYBRID_WORKFLOW.md | 198 +++++++++++++++++++++++++++++++++++++ 1 file changed, 198 insertions(+) create mode 100644 .github/HYBRID_WORKFLOW.md diff --git a/.github/HYBRID_WORKFLOW.md b/.github/HYBRID_WORKFLOW.md new file mode 100644 index 00000000..02d528dd --- /dev/null +++ b/.github/HYBRID_WORKFLOW.md @@ -0,0 +1,198 @@ +# Hybrid Workflow Guide + +This repository uses a hybrid workflow that balances automation with human oversight, optimized for Claude Code CLI development while maintaining best practices for collaborative work. + +## Overview + +The hybrid workflow uses two primary branches: +- **`main`** - Protected, stable branch for production-ready code +- **`dev`** - Active development branch with relaxed rules for rapid iteration + +## Key Principles + +1. **Incremental Development**: Small, focused commits and PRs +2. **Automated Synchronization**: Nightly rebases keep branches in sync +3. **Smart Automation**: Automate repetitive tasks, keep human oversight for critical decisions +4. **Clear Conventions**: Consistent naming and process standards + +## Branch Strategy + +### Main Branch +- **Purpose**: Stable, production-ready code +- **Protection**: Strict (requires reviews, all checks passing) +- **Merge Strategy**: Squash and merge +- **Who can push**: Nobody directly (PR only) + +### Dev Branch +- **Purpose**: Active development and integration +- **Protection**: Relaxed (no reviews required, allows force push) +- **Merge Strategy**: Regular merges or rebases +- **Who can push**: Developers after PR merge + +### Feature Branches +- **Naming**: `feat/`, `fix/`, `docs/`, `test/`, `chore/` prefixes +- **Base**: Usually `dev`, occasionally `main` for hotfixes +- **Lifecycle**: Create → Develop → PR → Merge → Delete + +## Workflows + +### 1. Starting New Work + +```bash +# Use the claude-branch script for easy branch creation +./scripts/claude-branch.sh my-new-feature + +# Or with a draft PR +./scripts/claude-branch.sh my-new-feature --pr + +# For fixes targeting main +./scripts/claude-branch.sh critical-fix --base main --pr +``` + +### 2. Development Process + +#### Commit Standards +- Maximum 30 files per commit +- Maximum 800 lines per commit +- Use conventional commit format: `type(scope): description` +- Commit frequently (approximately every 30 minutes of active work) + +#### Pushing Changes +- Auto-push is enabled for single source of truth +- Use `--force-with-lease` for safety when needed +- Pre-commit hooks ensure standards compliance + +### 3. Pull Request Process + +#### To Dev Branch +- No review required (but welcomed) +- Small PRs (<200 lines) auto-merge when approved +- Focus on rapid iteration +- CI must pass + +#### To Main Branch +- Requires 1 approval +- All conversations must be resolved +- Branch must be up-to-date +- More thorough review expected + +### 4. Automated Processes + +#### Nightly Rebase (3 AM UTC) +- Automatically rebases `dev` onto `main` +- Creates PR for conflicts requiring manual resolution +- Sends notifications on success/failure +- Cleans up old rebase branches after 7 days + +#### PR Management +- Auto-labels by size (XS to XL) +- Adds target branch labels +- Detects and warns about conflicts +- Manages stale PRs (7-day warning, 14-day close) + +#### Commit Enforcement +- Pre-commit hooks check size limits +- CI validates commit standards +- Protected files require PR review + +## Tools and Scripts + +### claude-branch.sh +Creates properly formatted branches with optional draft PRs. + +```bash +# Examples +./scripts/claude-branch.sh add-search # Creates feat/add-search +./scripts/claude-branch.sh fix-bug --pr # Creates fix/fix-bug with PR +./scripts/claude-branch.sh docs-update # Creates docs/docs-update +``` + +### apply-branch-protection.sh +Applies the correct protection rules to main and dev branches. + +```bash +# Dry run to see what would change +./scripts/apply-branch-protection.sh --dry-run + +# Apply protection +./scripts/apply-branch-protection.sh +``` + +## Best Practices + +### For Claude Code CLI Users +1. Work primarily with `dev` as your base branch +2. Use the `claude-branch.sh` script for consistency +3. Commit frequently within size limits +4. Let automation handle rebasing and synchronization + +### For Human Developers +1. Review PRs to `main` carefully +2. Use `dev` for experimental work +3. Leverage automation for routine tasks +4. Override automation when judgment is needed + +### Conflict Resolution +When the nightly rebase encounters conflicts: +1. A PR is automatically created with instructions +2. Check out the rebase branch locally +3. Resolve conflicts following the guide in the PR +4. Push the resolved branch +5. Merge the PR to update dev + +## Migration Guide + +For existing repositories adopting this workflow: + +1. **Create dev branch** (if doesn't exist): + ```bash + git checkout -b dev main + git push -u origin dev + ``` + +2. **Apply branch protection**: + ```bash + ./scripts/apply-branch-protection.sh + ``` + +3. **Update CI/CD** to recognize both branches + +4. **Configure team**: + - Set `dev` as default branch for new PRs + - Communicate new workflow to team + - Update documentation references + +## Troubleshooting + +### Common Issues + +**Commits rejected by pre-commit hook** +- Check file count and line count +- Split large changes into multiple commits +- Use `SKIP_CLAUDE_RULES=true git commit` for exceptions (use sparingly) + +**Nightly rebase failing repeatedly** +- Check for persistent conflicts +- Consider manually rebasing during work hours +- Review if dev has diverged too far from main + +**PR not auto-merging** +- Verify it's under 200 lines +- Ensure all checks are passing +- Confirm it targets dev branch +- Check for merge conflicts + +### Getting Help +- Check workflow status in Actions tab +- Review PR comments for automation feedback +- See individual workflow files for detailed configuration + +## Philosophy + +This hybrid workflow recognizes that: +- Automation should reduce toil, not replace judgment +- Different branches serve different purposes +- Both AI and human developers have unique strengths +- Flexibility and structure must be balanced + +By following this workflow, we maintain high code quality while enabling rapid development and experimentation. \ No newline at end of file