SuperClaude/docs/research/research_oss_fork_workflow_2025.md

OSS Fork Workflow Best Practices 2025

Research Date: 2025-10-16 Context: 2-tier fork structure (OSS upstream → personal fork) Goal: Clean PR workflow maintaining sync with zero garbage commits

---

🎯 Executive Summary

2025年のOSS貢献における標準フォークワークフローは、個人フォークのmainブランチを絶対に汚さないことが大原則。upstream同期にはmergeではなくrebaseを使用し、PR前にはrebase -iでコミット履歴を整理することで、クリーンな差分のみを提出する。

推奨ブランチ戦略:

master (or main): upstream mirror（同期専用、直接コミット禁止）
feature/*: 機能開発ブランチ（upstream/masterから派生）

"dev"ブランチは不要 - 役割が曖昧で混乱の原因となる。

---

📚 Current Structure

upstream: SuperClaude-Org/SuperClaude_Framework ← OSS本家
  ↓ (fork)
origin: kazukinakai/SuperClaude_Framework ← 個人フォーク

Current Branches:

• master: upstream追跡用
• dev: 作業ブランチ（❌ 役割不明確）
• feature/*: 機能ブランチ

---

✅ Recommended Workflow (2025 Standard)

Phase 1: Initial Setup (一度だけ)

# 1. Fork on GitHub UI
# SuperClaude-Org/SuperClaude_Framework → kazukinakai/SuperClaude_Framework

# 2. Clone personal fork
git clone https://github.com/kazukinakai/SuperClaude_Framework.git
cd SuperClaude_Framework

# 3. Add upstream remote
git remote add upstream https://github.com/SuperClaude-Org/SuperClaude_Framework.git

# 4. Verify remotes
git remote -v
# origin    https://github.com/kazukinakai/SuperClaude_Framework.git (fetch/push)
# upstream  https://github.com/SuperClaude-Org/SuperClaude_Framework.git (fetch/push)

Phase 2: Daily Workflow

Step 1: Sync with Upstream

# Fetch latest from upstream
git fetch upstream

# Update local master (fast-forward only, no merge commits)
git checkout master
git merge upstream/master --ff-only

# Push to personal fork (keep origin/master in sync)
git push origin master

重要: --ff-onlyを使うことで、意図しないマージコミットを防ぐ。

Step 2: Create Feature Branch

# Create feature branch from latest upstream/master
git checkout -b feature/pm-agent-redesign master

# Alternative: checkout from upstream/master directly
git checkout -b feature/clean-docs upstream/master

命名規則:

• feature/xxx: 新機能
• fix/xxx: バグ修正
• docs/xxx: ドキュメント
• refactor/xxx: リファクタリング

Step 3: Development

# Make changes
# ... edit files ...

# Commit (atomic commits: 1 commit = 1 logical change)
git add .
git commit -m "feat: add PM Agent session persistence"

# Continue development with multiple commits
git commit -m "refactor: extract memory logic to separate module"
git commit -m "test: add unit tests for memory operations"
git commit -m "docs: update PM Agent documentation"

Atomic Commits:

• 1コミット = 1つの論理的変更
• コミットメッセージは具体的に（"fix typo"ではなく"fix: correct variable name in auth.js:45"）

Step 4: Clean Up Before PR

# Interactive rebase to clean commit history
git rebase -i master

# Rebase editor opens:
# pick abc1234 feat: add PM Agent session persistence
# squash def5678 refactor: extract memory logic to separate module
# squash ghi9012 test: add unit tests for memory operations
# pick jkl3456 docs: update PM Agent documentation

# Result: 2 clean commits instead of 4

Rebase Operations:

• pick: コミットを残す
• squash: 前のコミットに統合
• reword: コミットメッセージを変更
• drop: コミットを削除

Step 5: Verify Clean Diff

# Check what will be in the PR
git diff master...feature/pm-agent-redesign --name-status

# Review actual changes
git diff master...feature/pm-agent-redesign

# Ensure ONLY your intended changes are included
# No garbage commits, no disabled code, no temporary files

Step 6: Push and Create PR

# Push to personal fork
git push origin feature/pm-agent-redesign

# Create PR using GitHub CLI
gh pr create --repo SuperClaude-Org/SuperClaude_Framework \
  --title "feat: PM Agent session persistence with local memory" \
  --body "$(cat <<'EOF'
## Summary
- Implements session persistence for PM Agent
- Uses local file-based memory (no external MCP dependencies)
- Includes comprehensive test coverage

## Test Plan
- [x] Unit tests pass
- [x] Integration tests pass
- [x] Manual verification complete

🤖 Generated with [Claude Code](https://claude.com/claude-code)
EOF
)"

Phase 3: Handle PR Feedback

# Make requested changes
# ... edit files ...

# Commit changes
git add .
git commit -m "fix: address review comments - improve error handling"

# Clean up again if needed
git rebase -i master

# Force push (safe because it's your feature branch)
git push origin feature/pm-agent-redesign --force-with-lease

Important: --force-with-leaseは--forceより安全（リモートに他人のコミットがある場合は失敗する）

---

🚫 Anti-Patterns to Avoid

❌ Never Commit to master/main

# WRONG
git checkout master
git commit -m "quick fix"  # ← これをやると同期が壊れる

# CORRECT
git checkout -b fix/typo master
git commit -m "fix: correct typo in README"

❌ Never Merge When You Should Rebase

# WRONG (creates unnecessary merge commits)
git checkout feature/xxx
git merge master  # ← マージコミットが生成される

# CORRECT (keeps history linear)
git checkout feature/xxx
git rebase master  # ← 履歴が一直線になる

❌ Never Rebase Public Branches

# WRONG (if others are using this branch)
git checkout shared-feature
git rebase master  # ← 他人の作業を壊す

# CORRECT
git checkout shared-feature
git merge master  # ← 安全にマージ

❌ Never Include Unrelated Changes in PR

# Check before creating PR
git diff master...feature/xxx

# If you see unrelated changes:
# - Stash or commit them separately
# - Create a new branch from clean master
# - Cherry-pick only relevant commits
git checkout -b feature/xxx-clean master
git cherry-pick <commit-hash>

---

🔧 "dev" Branch Problem & Solution

問題: "dev"ブランチの役割が曖昧

❌ Current (Confusing):
master ← upstream同期
dev ← 作業場？統合？staging？（不明確）
feature/* ← 機能開発

問題:
1. devから派生すべきか、masterから派生すべきか不明
2. devをいつupstream/masterに同期すべきか不明
3. PRのbaseはmaster？dev？（混乱）

解決策 Option 1: "dev"を廃止（推奨）

# Delete dev branch
git branch -d dev
git push origin --delete dev

# Use clean workflow:
master ← upstream同期専用（直接コミット禁止）
feature/* ← upstream/masterから派生

# Example:
git fetch upstream
git checkout master
git merge upstream/master --ff-only
git checkout -b feature/new-feature master

利点:

• シンプルで迷わない
• upstream同期が明確
• PRのbaseが常にmaster（一貫性）

解決策 Option 2: "dev" → "integration"にリネーム

# Rename for clarity
git branch -m dev integration
git push origin -u integration
git push origin --delete dev

# Use as integration testing branch:
master ← upstream同期専用
integration ← 複数featureの統合テスト
feature/* ← upstream/masterから派生

# Workflow:
git checkout -b feature/xxx master  # masterから派生
# ... develop ...
git checkout integration
git merge feature/xxx  # 統合テスト用にマージ
# テスト完了後、masterからPR作成

利点:

• 統合テスト用ブランチとして明確な役割
• 複数機能の組み合わせテストが可能

欠点:

• 個人開発では通常不要（OSSでは使わない）

推奨: Option 1（"dev"廃止）

理由:

• OSSコントリビューションでは"dev"は標準ではない
• シンプルな方が混乱しない
• upstream/master → feature/* → PR が最も一般的

---

📊 Branch Strategy Comparison

Strategy	master/main	dev/integration	feature/*	Use Case
Simple (推奨)	upstream mirror	なし	from master	OSS contribution
Integration	upstream mirror	統合テスト	from master	複数機能の組み合わせテスト
Confused (❌)	upstream mirror	役割不明	from dev?	混乱の元

---

🎯 Recommended Actions for Your Repo

Immediate Actions

# 1. Check current state
git branch -vv
git remote -v
git status

# 2. Sync master with upstream
git fetch upstream
git checkout master
git merge upstream/master --ff-only
git push origin master

# 3. Option A: Delete "dev" (推奨)
git branch -d dev  # ローカル削除
git push origin --delete dev  # リモート削除

# 3. Option B: Rename "dev" → "integration"
git branch -m dev integration
git push origin -u integration
git push origin --delete dev

# 4. Create feature branch from clean master
git checkout -b feature/your-feature master

Long-term Workflow

# Daily routine:
git fetch upstream && git checkout master && git merge upstream/master --ff-only && git push origin master

# Start new feature:
git checkout -b feature/xxx master

# Before PR:
git rebase -i master
git diff master...feature/xxx  # verify clean diff
git push origin feature/xxx
gh pr create --repo SuperClaude-Org/SuperClaude_Framework

---

📖 References

Official Documentation

• GitHub: Syncing a Fork
• Atlassian: Merging vs. Rebasing
• Atlassian: Forking Workflow

2025 Best Practices

• DataCamp: Git Merge vs Rebase (June 2025)
• Mergify: Rebase vs Merge Tips (April 2025)
• Zapier: Git Rebase vs Merge (May 2025)

Community Resources

• GitHub Gist: Standard Fork & Pull Request Workflow
• Medium: Git Fork Development Workflow
• Stack Overflow: Keeping Fork in Sync

---

💡 Key Takeaways

1. Never commit to master/main - upstream同期専用として扱う
2. Rebase, not merge - upstream同期とPR前クリーンアップにrebase使用
3. Atomic commits - 1コミット1機能を心がける
4. Clean before PR - git rebase -iで履歴整理
5. Verify diff - git diff master...feature/xxxで差分確認
6. "dev" is confusing - 役割不明確なブランチは廃止または明確化

Golden Rule: upstream/master → feature/* → rebase -i → PR これが2025年のOSS貢献における標準ワークフロー。