External/SuperClaude
1
0
Fork 0
mirror of https://github.com/SuperClaude-Org/SuperClaude_Framework.git synced 2025-12-29 16:16:08 +00:00
Code Issues Packages Projects Releases Wiki Activity

refactor: consolidate documentation directories

Browse Source 
Merged claudedocs/ into docs/research/ for consistent documentation structure.

Changes:
- Moved all claudedocs/*.md files to docs/research/
- Updated all path references in documentation (EN/KR)
- Updated RULES.md and research.md command templates
- Removed claudedocs/ directory
- Removed ClaudeDocs/ from .gitignore

Benefits:
- Single source of truth for all research reports
- PEP8-compliant lowercase directory naming
- Clearer documentation organization
- Prevents future claudedocs/ directory creation

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

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
kazuki
2025-10-17 04:16:44 +09:00
parent b23c9cee3b
commit ce51fb512b
25 changed files with 5996 additions and 62 deletions
Download Patch File Download Diff File Expand all files Collapse all files

409
docs/research/research_oss_fork_workflow_2025.md Normal file
View File

@@ -0,0 +1,409 @@
# 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 (一度だけ)
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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"を廃止（推奨）
```bash
# 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"にリネーム
```bash
# 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
```bash
# 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
```bash
# 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](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork)
- [Atlassian: Merging vs. Rebasing](https://www.atlassian.com/git/tutorials/merging-vs-rebasing)
- [Atlassian: Forking Workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/forking-workflow)
### 2025 Best Practices
- [DataCamp: Git Merge vs Rebase (June 2025)](https://www.datacamp.com/blog/git-merge-vs-git-rebase)
- [Mergify: Rebase vs Merge Tips (April 2025)](https://articles.mergify.com/rebase-git-vs-merge/)
- [Zapier: Git Rebase vs Merge (May 2025)](https://zapier.com/blog/git-rebase-vs-merge/)
### Community Resources
- [GitHub Gist: Standard Fork & Pull Request Workflow](https://gist.github.com/Chaser324/ce0505fbed06b947d962)
- [Medium: Git Fork Development Workflow](https://medium.com/@abhijit838/git-fork-development-workflow-and-best-practices-fb5b3573ab74)
- [Stack Overflow: Keeping Fork in Sync](https://stackoverflow.com/questions/55501551/what-is-the-standard-way-of-keeping-a-fork-in-sync-with-upstream-on-collaborativ)
---
## 💡 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貢献における標準ワークフロー。