open-source-contributions

オープンソース貢献スキル

バージョン: 1.1.0 | 最終確認日: 2025-11-06 | 本番環境でのテスト済み: ✅

---

概要

オープンソースプロジェクトに貢献するには、エチケットや慣習、メンテナーが何を期待しているかを理解する必要があります。このスキルは、時間を浪費して却下につながるよくあるミスを避けながら、プロフェッショナルでメンテナーに配慮したプルリクエストを作成するのに役立ちます。

主な焦点: 個人的な開発用ファイルの整理、適切な PR 説明の作成、プロジェクトの慣習の遵守、プロフェッショナルなコミュニケーション。

---

このスキルを使う場面

次のような場合に、このスキルを使ってください：

• 公開リポジトリにプルリクエストを作成する
• コミュニティのオープンソースプロジェクトに貢献する
• 自分がメンテナーではないプロジェクトにコードを提出する
• 新しいプロジェクトに初めて貢献する
• PR の受理率を上げたい
• PR のベストプラクティスについてガイダンスが必要

自動トリガーとなるフレーズ: 「submit PR to」、「contribute to」、「pull request for」、「open source contribution」

---

プルリクエストに含めてはいけないもの

個人的な開発用ファイル（絶対に含めない）

計画・メモのドキュメント:

❌ SESSION.md              # Session tracking notes
❌ NOTES.md                # Personal development notes
❌ TODO.md                 # Personal todo lists
❌ planning/*              # Planning documents directory
❌ IMPLEMENTATION_PHASES.md # Project planning
❌ DATABASE_SCHEMA.md      # Unless adding new schema to project
❌ ARCHITECTURE.md         # Unless documenting new architecture
❌ SCRATCH.md              # Temporary notes
❌ DEBUGGING.md            # Debugging notes
❌ research-logs/*         # Research notes

スクリーンショット・ビジュアル素材:

❌ screenshots/debug-*.png     # Debugging screenshots
❌ screenshots/test-*.png      # Testing screenshots
❌ screenshot-*.png            # Ad-hoc screenshots
❌ screen-recording-*.mp4      # Screen recordings
❌ before-after-local.png      # Local comparison images

✅ screenshots/feature-demo.png   # IF demonstrating feature in PR description
✅ docs/assets/ui-example.png     # IF part of documentation update

テストファイル（状況による）:

❌ test-manual.js          # Manual testing scripts
❌ test-debug.ts           # Debugging test files
❌ quick-test.py           # Quick validation scripts
❌ scratch-test.sh         # Temporary test scripts
❌ example-local.json      # Local test data

✅ tests/feature.test.js   # Proper test suite additions
✅ tests/fixtures/data.json # Required test fixtures
✅ __tests__/component.tsx  # Component tests

ビルド・依存関係:

❌ node_modules/           # Dependencies (in .gitignore)
❌ dist/                   # Build output (in .gitignore)
❌ build/                  # Build artifacts (in .gitignore)
❌ .cache/                 # Cache files (in .gitignore)
❌ package-lock.json       # Unless explicitly required by project
❌ yarn.lock               # Unless explicitly required by project

IDE・OS のファイル:

❌ .vscode/                # VS Code settings
❌ .idea/                  # IntelliJ settings
❌ .DS_Store               # macOS file system
❌ Thumbs.db               # Windows thumbnails
❌ *.swp, *.swo            # Vim swap files
❌ *~                      # Editor backup files

シークレット・機密データ:

❌ .env                    # Environment variables (NEVER!)
❌ .env.local              # Local environment config
❌ config/local.json       # Local configuration
❌ credentials.json        # Credentials (NEVER!)
❌ *.key, *.pem            # Private keys (NEVER!)
❌ secrets/*               # Secrets directory (NEVER!)

一時ファイル・デバッグファイル:

❌ temp/*                  # Temporary files
❌ tmp/*                   # Temporary directory
❌ debug.log               # Debug logs
❌ *.log                   # Log files
❌ dump.sql                # Database dumps
❌ core                    # Core dumps
❌ *.prof                  # Profiling output

含めるべきもの

✅ Source code changes      # The actual feature/fix
✅ Tests for changes        # Required tests for new code
✅ Documentation updates    # README, API docs, inline comments
✅ Configuration changes    # If part of the feature
✅ Migration scripts        # If needed for the feature
✅ Package.json updates     # If adding/removing dependencies
✅ Schema changes           # If part of feature (with migrations)
✅ CI/CD updates            # If needed for new workflows

---

PR 作成前のクリーンアップ手順

ステップ 1：PR 作成前チェック用スクリプトを実行する

同梱の scripts/pre-pr-check.sh を使って、不要なファイルをスキャンします：

./scripts/pre-pr-check.sh

チェック内容:

• 個人用ドキュメント（SESSION.md、planning/*、NOTES.md）
• PR の説明で参照されていないスクリーンショット
• 一時的なテストファイル
• 大きなファイル（>1MB）
• ファイルの内容に含まれる可能性のあるシークレット
• PR のサイズ（>400 行の場合に警告）
• 未コミットの変更

ステップ 2：Git のステータスを確認する

git status
git diff --stat

自問してください:

• この機能・修正に、すべてのファイル変更が必要ですか？
• 無関係な変更はありませんか？
• 開発中に追加したものの、不要なファイルはありませんか？

ステップ 3：個人的なファイルを整理する

手動で削除する場合:

git rm --cached SESSION.md
git rm --cached -r planning/
git rm --cached screenshots/debug-*.png
git rm --cached test-manual.js

または、クリーンアップ用スクリプトを使う場合:

./scripts/clean-branch.sh

ステップ 4：.gitignore を更新する

個人用のパターンを .git/info/exclude に追加します（自分のチェックアウトにのみ適用されます）：

# Personal development artifacts
SESSION.md
NOTES.md
TODO.md
planning/
screenshots/debug-*.png
test-manual.*
scratch.*

---

効果的な PR 説明の書き方

What/Why/How の構成を使う

テンプレート（references/pr-template.md を参照）：

## What?
[Brief description of what this PR does]

## Why?
[Explain the reasoning, business value, or problem being solved]

## How?
[Describe the implementation approach and key decisions]

## Testing
[Step-by-step instructions for reviewers to test]

## Checklist
- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] CI passing
- [ ] Breaking changes documented

## Related Issues
Closes #123
Relates to #456

良い PR 説明の例

## What?
Add OAuth2 authentication support for Google and GitHub providers

## Why?
Users have requested social login to reduce friction during signup.
This implements Key Result 2 of Q4 OKR1.

## How?
- Implemented OAuth2 flow using passport.js
- Added provider configuration in environment variables
- Created callback routes for each provider
- Updated user model to link social accounts

## Testing
1. Set up OAuth apps in Google/GitHub developer consoles
2. Add credentials to `.env` (see `.env.example`)
3. Run `npm start`
4. Click "Login with Google" and verify flow
5. Verify user profile merges correctly

## Breaking Changes
None - this is additive functionality

## Related Issues
Closes #234
Relates to #156 (social login epic)

タイトル：Conventional Commits に従う

形式: <type>(<scope>): <description>

種類:

• feat: - 新機能
• fix: - バグ修正
• docs: - ドキュメントのみ
• style: - 書式変更（コードの変更なし）
• refactor: - コードの再構成（動作の変更なし）
• perf: - パフォーマンスの改善
• test: - テストの追加・更新
• build: - ビルドシステムの変更
• ci: - CI 設定の変更
• chore: - その他の変更（src/test の変更なし）

例:

✅ feat(auth): add OAuth2 support for Google and GitHub
✅ fix(api): resolve memory leak in worker shutdown
✅ docs(readme): update installation instructions for v2.0
✅ refactor(utils): extract validation logic to separate module

❌ Fixed stuff
❌ Updates
❌ Working on authentication (too vague)

---

コミットメッセージのベストプラクティス

構成

詳しくは references/commit-message-guide.md を参照してください。

<type>(<scope>): <subject>

[optional body]

[optional footer]

件名のルール:

• 最大 50 文字
• 命令形を使う（「Added」ではなく「Add」）
• 最初の単語を大文字にする
• 末尾にピリオドを付けない
• 何を変更したかを説明する

本文のルール（任意）:

• 1 行あたり 72 文字
• なぜ変更したかを説明する（何を変更したかはコードで分かります）
• 件名との間に空行を入れる

フッター（任意）:

• Issue を参照する: Closes #123
• 破壊的変更を記載する: BREAKING CHANGE: ...

例

良い例:

fix: prevent race condition in cache invalidation

The cache invalidation logic wasn't thread-safe, causing
occasional race conditions when multiple workers tried to
invalidate the same key simultaneously.

Added mutex locks around the critical section and tests
to verify thread-safety.

Fixes #456

悪い例:

Fixed bug                          # Too vague
WIP                               # Not descriptive
asdf                              # Meaningless
Updated auth.js                   # Describes file, not change
Fixed the issue with the thing    # No specifics

---

PR のサイズに関するベストプラクティス

理想的なサイズ

調査に基づくガイドライン:

• 理想: コード 50 行
• 良好: 200 行未満
• 最大: 400 行
• 400 行を超える場合: 不具合の検出率が大幅に低下します

小さな PR が重要な理由:

• レビューが速い（メンテナーが一度に確認できます）
• バグを見つけやすい
• 必要に応じて簡単に取り消せる
• マージコンフリクトが減る
• 議論の焦点を絞りやすい

PRを小さく保つ方法

1. 1つの変更につきPRは1つ

❌ BAD: Refactor auth module + add OAuth + fix bug + update docs (800 lines)

✅ GOOD:
  PR #1: Refactor auth module (150 lines)
  PR #2: Add OAuth support (200 lines)
  PR #3: Fix authentication bug (50 lines)
  PR #4: Update authentication docs (80 lines)

2. リファクタリングと機能追加を分ける

❌ BAD: Add feature X + refactor related code (500 lines)

✅ GOOD:
  PR #1: Refactor to prepare for feature X (200 lines)
  PR #2: Add feature X (150 lines)

3. 機能フラグを使う 未完成の機能はフラグで無効化した状態でリリースし、早めに、頻繁にマージします。

if (featureFlags.newAuth) {
  // New OAuth flow (incomplete but behind flag)
} else {
  // Existing flow
}

4. レイヤーごとに分割する

For "User Authentication" feature:
  PR #1: Database schema + migrations (100 lines)
  PR #2: API endpoints (150 lines)
  PR #3: Frontend components (200 lines)
  PR #4: Tests + documentation (150 lines)

大きなPRが許容される場合

• プロジェクトの初期セットアップ
• 生成コード（生成コードであることを明確に記載）
• 分割できない大規模なリファクタリング（説明欄に理由を記載）
• ドキュメントの全面的な書き直し
• 依存関係の更新（自動化されたもの）

避けられない場合：レビューしやすいように、PRの説明欄に明確なセクション見出しを追加します。

---

プロジェクトの規約に従う

ステップ 1：CONTRIBUTING.md を読む

必ず最初に読みましょう。これはプロジェクトの規則です。一般的な場所は次のとおりです。

• /CONTRIBUTING.md
• /.github/CONTRIBUTING.md
• /docs/CONTRIBUTING.md

確認すべき主なセクション：

• 開発環境のセットアップ
• テスト要件
• コードスタイルのガイドライン
• コミットメッセージの形式
• PR の手順
• レビューに関する期待事項

ヒント：リポジトリの URL に /contribute を追加すると、初心者向けの課題を見つけられます。

ステップ 2：スタイルガイドを確認する

確認するファイル：

• .eslintrc、.eslintrc.js（JavaScript/TypeScript のリント）
• .prettierrc（コードのフォーマット）
• .editorconfig（エディター設定）
• STYLE.md（スタイルガイドのドキュメント）
• rustfmt.toml（Rust のフォーマット）
• pyproject.toml（Python のフォーマット）

コミット前にフォーマッターを実行します：

npm run lint                # Check for style issues
npm run lint:fix            # Auto-fix style issues
npm run format              # Format code (Prettier, Black, etc.)

ステップ 3：既存のパターンに合わせる

最近マージされた PR を確認します：

• ファイルはどのように整理されていますか？
• どのような命名規則が使われていますか？
• コメントはどのくらい詳しく書かれていますか？
• どのようなテストパターンがありますか？
• インポートはどのような順序になっていますか？

黄金律：「プロジェクトのメンテナーが望む方法で作業すること。」

ステップ 4：テスト要件

提出前に：

# Run full test suite
npm test                    # Node projects
cargo test                  # Rust projects
pytest                      # Python projects
go test ./...               # Go projects

# Check coverage (if required)
npm run test:coverage

# Run linters
npm run lint

# Build the project
npm run build

次の状態で PR を提出してはいけません：

• テストが失敗している
• リントが失敗している
• ビルドエラーがある
• 新しいコードをテストしていない（テストが必須の場合）

---

コミュニケーションのベストプラクティス

作業を始める前に

課題にコメントします：

Hi! I'd like to work on this issue. My approach would be to:
1. [Brief outline of approach]
2. [Key implementation detail]

Does this sound good? Any guidance before I start?

これが重要な理由：

• 重複作業を防げる
• アプローチについて早い段階でフィードバックを得られる
• メンテナーの時間を尊重していることを示せる
• コミュニケーションのきっかけになる

大きな変更に時間をかける前に、確認を待ちましょう。

PR コメントを書く

提出時：

@maintainer I've implemented the feature as discussed in #123.
I went with approach A instead of B because [reason].

Ready for review when you have time. Happy to make changes!

フィードバックへの返信時：

Good catch! I've updated this in commit abc1234.

I considered that approach, but went with X because Y.
Happy to discuss alternatives if you prefer a different direction.

Could you elaborate on what you mean by Z?
I want to make sure I understand correctly.

レビューコメントへの返信

主な原則：

1. すべてのコメントに対応する - 「対応しました」や「確認しました」だけでも返信します
2. 怒って返信しない - 必要ならいったん離れ、落ち着いてから返信します
3. GitHub のレビュー機能を使う：
   • 対応した会話を解決済みとしてマークする
   • 変更後に再レビューを依頼する
   • 手早く修正するには「suggestion」機能を使う
4. 議論を本題に沿ったものにする - 脱線した話題は別の場所で扱います
5. 感謝の気持ちを示す - レビューは価値があり、時間のかかる作業です

返信のテンプレート：

• 対応済み：「よいアイデアです！[commit hash] で実装しました」
• 質問：「ご質問ありがとうございます。Y のため X を行いました。どう思いますか？」
• 意見の相違：「ご指摘の点は理解しています。Y のため X を選びました。強いご希望があれば、別の案も検討します」
• 説明が必要：「Z の意味を理解するため、もう少し詳しく教えていただけますか？」

PR が却下された場合

心構え：

• 個人的な失敗ではなく、学びの機会です
• 却下はよくあることで、誰にでも起こります
• プロジェクトのビジョンが、あなたのアプローチと異なる場合もあります

取るべき手順：

1. 理由を確認する - 丁寧に PR が却下された理由を尋ねます
2. フィードバックを慎重に確認する - 具体的な懸念点を特定します
3. そこから学ぶ - 次回は何を変えられるでしょうか？
4. 選択肢：
   • フィードバックに基づいて作り直す
   • フォークして変更を保守する
   • 別の貢献に取り組む

してはいけないこと：

• 却下された PR にコメントし続けない
• 個人的なこととして受け止めない
• 攻撃的に反論しない
• プロジェクト全体を放棄しない（本当に合わない場合を除く）

辛抱強く待ちましょう（ただし、催促するタイミングも見極めましょう）

メンテナーはボランティアであることがよくあります：

• 本業や家族、生活があります
• 数十件もの PR をレビューしている場合があります
• 複雑なプロジェクトの問題に対処している場合があります

所要期間の目安：

• 小規模な PR：1〜7 日
• 大規模な PR：1〜2 週間
• 複雑な変更や意見が分かれる変更：数週間〜数か月

催促するタイミング：

• 小規模な PR は 1 週間後
• 大規模な PR は 2 週間後
• 外部の変更により CI が失敗している場合（リベースが必要）

催促の方法：

Hi! Just wanted to gently ping this PR.
No rush at all, just making sure it's on your radar.
Happy to answer any questions or make changes!

---

メンテナーを困らせるよくあるミス

よくある 16 のミス

詳しくは「重要なワークフロールール」のセクションで、ルール 1〜3 を確認してください

1. CONTRIBUTING.md を読まない

• 影響：作業が無駄になり、PR が却下され、メンテナーの不満を招きます
• 対策：必ず最初にこのファイルを読み、指示に正確に従ってください

2. 個人的な開発用ファイルを含める

• 影響：PR が雑然とし、内部のワークフローが露呈し、プロ意識に欠ける印象を与えます
• 対策：PR 提出前のチェック用スクリプトを使い、提出前に不要なファイルを削除してください
• 例：SESSION.md、planning/*、スクリーンショット、一時的なテストファイル

3. 非常に大規模なプルリクエストを提出する

• 影響：レビューが大変になり、バグを見つけにくくなり、マージが遅れます
• 対策：小さな PR に分割してください（理想は 200 行未満です）

4. 提出前にコードをテストしない（ルール 2 に違反）

• 影響：CI が失敗し、本番環境でバグが発生し、メンテナーが修正することになり、信頼を失います
• 対策：ルール 2 を確認してください。テストスイート全体を実行し、手動でテストし、証拠（スクリーンショット／動画）を記録して、CI が通ることを確認してください

5. すでに担当者が割り当てられているイシューに取り組む

• 影響：作業が重複し、貢献者双方の時間が無駄になります
• 対策：イシューの担当者を確認し、作業を担当する旨をコメントしてください

6. 変更について事前に話し合わない（大規模な変更の場合）

• 影響：望まれていない機能を作ることになり、PR が却下され、開発時間が無駄になります
• 対策：コーディングを始める前に、イシューを作成するかコメントして話し合ってください

7. 急かしたり、返答しなかったりする

• 影響：PR が停滞し、メンテナーが対応を中断し、貢献が放棄されます
• 対策：迅速に返答しつつ辛抱強く待ち、1〜2 週間後に丁寧に催促してください

8. ドキュメントを更新しない

• 影響：変更点が文書化されておらず、ユーザーや開発者が混乱します
• 対策：必要に応じて README、API ドキュメント、コード内コメントを更新してください

9. コードスタイルの標準を無視する

• 影響：コードベースが雑然とし、メンテナーが書式を修正することになります
• 対策：プロジェクトのリンター／フォーマッターを使い、既存のスタイルに合わせてください

10. CI の失敗を無視する

• 影響：マージできず、進行が妨げられ、メンテナーが調査することになります
• 対策：CI を監視し、失敗をすぐに修正してください。行き詰まった場合は助けを求めてください

11. 無関係な変更を含める（ルール 3 に違反）

• 影響：レビューが難しくなり、変更を取り消しにくくなり、スコープが膨らみ、Git の履歴が分かりにくくなります
• 対策：ルール 3 を確認してください。1 つの PR には 1 つの機能だけを含めます。焦点を絞り、無関係な変更は別々のブランチ／PR に分けてください

12. イシューを適切にリンクしない

• 影響：文脈が失われ、手動でイシューを閉じる必要が生じ、追跡が難しくなります
• 対策：PR の説明に「Closes #123」または「Fixes #456」を使ってください

13. シークレットや機密データをコミットする

• 影響：セキュリティリスクが生じ、緊急対応が必要になり、情報漏えいにつながる可能性があります
• 対策：.gitignore を使い、シークレットをスキャンし、.env ファイルは絶対にコミットしないでください

14. 警告なしに強制プッシュする

• 影響：レビュアーのローカルコピーが壊れ、コメントが失われます
• 対策：レビュー開始後の強制プッシュは避け、必要な場合は事前に警告してください

15. ローカルでビルド／テストを実行しない

• 影響：明らかな問題でも CI が失敗し、CI リソースが無駄になります
• 対策：プッシュ前に必ず npm run build と npm test を実行してください

16. main/master ブランチで直接作業する（ルール 1 に違反）

• 影響：Git の履歴が雑然とし、上流と競合し、複数の機能を並行して開発できず、フォークの同期が難しくなります
• 対策：ルール 1 を確認してください。必ず機能ブランチ（git checkout -b feature/my-feature）を作成し、main には絶対にコミットしないでください

---

GitHub 固有のベストプラクティス

フォークワークフロー（オープンソースで標準的な方法）

初期設定：

# 1. Fork repository on GitHub (click Fork button)

# 2. Clone YOUR fork
git clone https://github.com/YOUR-USERNAME/project-name.git
cd project-name

# 3. Add upstream remote
git remote add upstream https://github.com/ORIGINAL-OWNER/project-name.git

# 4. Verify remotes
git remote -v
# origin    https://github.com/YOUR-USERNAME/project-name.git (fetch)
# origin    https://github.com/YOUR-USERNAME/project-name.git (push)
# upstream  https://github.com/ORIGINAL-OWNER/project-name.git (fetch)
# upstream  https://github.com/ORIGINAL-OWNER/project-name.git (push)

機能ブランチの作成：

# NEVER work on main/master directly!
git checkout -b feature/add-oauth-support

# Make changes...
git add .
git commit -m "feat(auth): add OAuth2 support"

# Push to YOUR fork
git push origin feature/add-oauth-support

フォークを最新の状態に保つ：

git fetch upstream
git checkout main
git merge upstream/main
git push origin main

---

重要なワークフロールール（絶対に省略しないでください）

ルール 1：必ずフィーチャーブランチで作業する

# ❌ NEVER DO THIS
git checkout main
# make changes directly on main
git commit -m "add feature"  # BAD!

# ✅ ALWAYS DO THIS
git checkout main
git pull upstream main  # Sync first
git checkout -b feature/add-oauth-support  # Descriptive branch name
# make changes on feature branch
git commit -m "feat(auth): add OAuth support"

これが重要な理由：

• main をクリーンな状態に保ち、upstream と同期できます
• 複数の機能を同時に作業できます
• 作業を簡単に中止したり、やり直したりできます
• ほとんどのオープンソースプロジェクトで必須です
• コンフリクトや煩雑な Git 履歴を防げます

ブランチの命名規則：

feature/descriptive-name    # New features
fix/issue-123               # Bug fixes
docs/update-readme          # Documentation
refactor/extract-utils      # Refactoring
test/add-unit-tests         # Test additions

---

ルール 2：PR を提出する前に十分にテストする

次のことを行わずに PR を提出しないでください。

1. ローカルでテストスイート全体を実行する：

   npm test              # Node.js
   cargo test            # Rust
   pytest                # Python
   go test ./...         # Go
   

2. 手動でテストする（実際に動作を確認する）：

   • アプリケーションを実行する
   • 追加した機能をテストする
   • エッジケースやエラー条件をテストする
   • 意図したとおりに動作することを確認する

3. 証拠を記録する（視覚的な変更や UI の変更の場合）：

   • 機能が動作していることを示すスクリーンショットを撮る
   • 複雑な場合は短いデモ動画を録画する
   • 機能を実証するため、PR の説明に含める

4. CI が成功することを確認する：

   npm run lint          # Linting
   npm run build         # Build succeeds
   npm run type-check    # TypeScript checks
   

新しい OAuth 機能のテストチェックリストの例：

## Testing Performed

### Automated Tests
- ✅ All existing tests pass
- ✅ Added 12 new tests for OAuth flow
- ✅ Coverage increased from 85% to 87%

### Manual Testing
- ✅ Tested Google OAuth flow end-to-end
- ✅ Tested GitHub OAuth flow end-to-end
- ✅ Verified error handling (invalid tokens, network failures)
- ✅ Confirmed user profile merging works correctly
- ✅ Tested on Chrome, Firefox, Safari

### Evidence
See screenshots below showing successful login flow.

これが重要な理由：

• メンテナーの時間を無駄にする CI の失敗を防げます
• コードの品質を大切にしていることを示せます
• 機能が実際に動作することを実証できます
• メンテナーとの信頼関係を築けます
• レビュー前にバグを発見できます

PR の説明に添付するスクリーンショット：

✅ Include: Working feature demonstration
✅ Include: Before/after comparisons for changes
✅ Include: Error state handling

❌ Don't include: Debug screenshots in code commits
❌ Don't include: Personal testing screenshots in repo
❌ Don't include: Unrelated screenshots

Location: Add to PR description on GitHub, NOT as files in commits

---

ルール 3：PR の対象を絞り、まとまりを保つ

1 つの PR = 1 つの機能または修正

✅ GOOD: Single PR adding OAuth support
  - OAuth provider configuration
  - Login/callback routes
  - User model updates
  - Tests for OAuth flow
  - Documentation for setup

❌ BAD: PR with multiple unrelated changes
  - OAuth support
  - + Unrelated bug fix in validation
  - + Random formatting changes
  - + Update to README for different feature

まとまりのある PR が重要な理由：

• レビューや理解が容易になります
• 個別にマージまたは却下できます
• 問題が見つかった場合に、より簡単に元に戻せます
• レビューのサイクルを短縮できます
• Git 履歴が明確になります

PR の対象を絞る方法：

1. コーディングの前に計画する：

   • この PR が行うことは何ですか？
   • この機能のために変更が必要なファイルはどれですか？
   • 必要な変更を最小限にすると、どのような内容になりますか？

2. 開発中：

   • 無関係なバグに気づいたら、別のブランチを作成する
   • フォーマットを修正したくなったら、別の PR で行う
   • 1 つの目標に集中する

3. コミットする前に：

   • 変更を確認する：git diff
   • 「このファイルの変更は、この機能に必要か？」と自問する
   • 無関係な変更は stash に移す：git stash

4. サイズの目安：

   • 理想：変更行数 200 未満
   • 許容範囲：200～400 行
   • 大規模：400～800 行（理由の説明が必要）
   • 大きすぎる：800 行超（分割するべき）

大規模な機能の分割：

機能が本質的に大規模な場合は、段階に分けます。

PR #1: Database schema and models
PR #2: API endpoints
PR #3: Frontend components
PR #4: Integration and tests

各 PR は次の条件を満たす必要があります。

• 前の PR を基盤としている
• 個別にレビューできる
• 動作する機能を追加する（または WIP／基盤となる変更であることを明確に示す）

意図せず対象範囲が広がった場合の対処：

# You added OAuth + accidentally fixed a bug
# Split them into separate commits and PRs:

# 1. Create bug fix branch from main
git checkout main
git checkout -b fix/validation-bug

# 2. Cherry-pick just the bug fix commits
git cherry-pick <commit-hash-of-bug-fix>

# 3. Submit bug fix PR separately
git push origin fix/validation-bug

# 4. Continue with OAuth PR
git checkout feature/add-oauth-support
# Remove bug fix commits if needed
git rebase -i main

---

Draft PR の使用

使用する場面：

• コードが作業中で、レビューの準備ができていない
• アプローチについて早い段階でフィードバックを得たい
• 実装について話し合いを始めたい
• 共同作業のために未完成のコードを共有したい

メリット：

• 誤ってマージされるのを防ぎます
• レビュアーへの通知を抑制します
• 「まだ準備ができていない」ことを明確に示します

Draft PR を作成する：

gh pr create --draft --title "WIP: Add OAuth support"

次の条件を満たしたらレビュー可能にする：

• コードが完成し、テスト済みである
• CI が成功している
• ドキュメントが更新されている
• 正式なレビューを受ける準備ができている

gh pr ready

イシューを適切にリンクする

自動クローズキーワード（PR の説明またはコミットで使用）：

Closes #123
Fixes #456
Resolves #789

# Also works:
Close #123
Fix #123
Resolve #123

# Case insensitive:
CLOSES #123
fixes #123

# Multiple issues:
Fixes #10, closes #20, resolves #30

# Cross-repo:
Fixes owner/repo#123

重要：DEFAULT ブランチ（通常は main）にマージする場合にのみ機能します。

GitHub CLI の使用

効率的な PR の作成：

# Interactive (prompts for title/body)
gh pr create

# Auto-fill from commits
gh pr create --fill

# Complete non-interactive
gh pr create \
  --title "feat(auth): add OAuth support" \
  --body "$(cat <<'EOF'
## What?
Add OAuth2 authentication

## Why?
User request for social login

## Testing
1. Set up OAuth apps
2. Run npm start
3. Test login flow
EOF
)"

# With reviewers
gh pr create --reviewer username1,username2

# Draft PR
gh pr create --draft

その他の便利なコマンド：

gh pr status              # See your PRs
gh pr checks              # View CI status
gh pr view                # View current PR
gh pr diff                # See PR diff
gh pr ready               # Mark draft as ready
gh pr merge               # Merge PR (when approved)

---

提出前チェックリスト

プルリクエストを提出する前に、このチェックリストを使用してください（references/pr-checklist.md を参照）。

コントリビューションを始める前に

• CONTRIBUTING.md をよく読む
• CODE_OF_CONDUCT.md がある場合は読む
• 先にイシューを作成すべきか確認する
• イシューにコメントして作業を担当することを伝える
• メンテナーから作業の了承を得る（重要な変更の場合）
• リポジトリをフォークする（書き込み権限がない場合）
• upstream リモートを設定する
• フィーチャーブランチを作成する（main では絶対に作業しない）

開発

重要なワークフロールール（上記の詳細セクションを参照）：

• ルール 1：フィーチャーブランチで作業している（main/master ではない）
• ルール 2：十分にテスト済みで、すぐに提示できる証拠がある
• ルール 3：PR が単一の機能または修正に絞られている

コード品質：

• コードがプロジェクトのスタイルガイドラインに従っている
• リンターとフォーマッターを実行した
• すべてのテストがローカルで成功する（npm test、cargo test など）
• 新しい機能のテストを追加した
• 手動テストを実施した（アプリを起動し、機能をテストした）
• 証拠を記録した（視覚的な変更についてはスクリーンショット／動画）
• 関連するドキュメントを更新した
• コミットメッセージが規約に従っている
• ベースブランチとのマージコンフリクトがない
• プロジェクトのビルドに成功した（npm run build など）

クリーンアップ

• PR 前チェック用スクリプト（./scripts/pre-pr-check.sh）を実行した
• 個人的なファイルを削除した：
  • SESSION.md やメモファイルがない
  • planning/* のドキュメントがない
  • デバッグ用スクリーンショットがない
  • 一時的なテストファイルがない
  • 個人的なワークフローファイルがない
• git status で不要なファイルがないか確認した
• シークレットや機密データがない
• IDE／OS 固有のファイルがない
• ビルド成果物や依存関係が含まれていない

PR の品質

• PR が 1 つの変更／課題に絞られている
• PR の規模が適切である（理想は 200 行未満、最大 400 行未満）
• 無関係な変更が含まれていない
• 意図しない変更がないか、自分の差分を確認した
• タイトルが規約（Conventional Commits）に従っている
• 説明が「内容／理由／方法」の構成になっている
• テスト手順が含まれている
• 関連する課題へのリンクがある（Closes #123）
• 視覚的な変更を示す場合、スクリーンショットがある
• 破壊的変更について記載されている
• レビュアーが質問しなくても内容を理解できる

提出

• CI／チェックが成功している
• フォーク上のフィーチャーブランチにプッシュした
• 適切な説明を添えて PR を作成した
• ラベルを割り当てた（許可されている場合）
• レビュアーを依頼した（心当たりがある場合）
• プロジェクト／マイルストーンにリンクした（該当する場合）

提出後

• CI の失敗を監視している
• フィードバックに迅速に対応している
• レビューコメントに速やかに対応している
• 会話を解決済みとしてマークしている
• 変更後に再レビューを依頼している
• レビュアーに感謝している
• 待つ間、辛抱強くしている

---

コマンド早見表

Git ワークフロー

# Setup
git clone https://github.com/YOUR-USERNAME/project.git
git remote add upstream https://github.com/ORIGINAL/project.git

# Create feature branch
git checkout -b feature/my-feature

# Make changes and commit
git add .
git commit -m "feat: add new feature"

# Push to your fork
git push origin feature/my-feature

# Keep fork synced
git fetch upstream
git checkout main
git merge upstream/main
git push origin main

# Rebase feature branch if needed
git checkout feature/my-feature
git rebase main
git push origin feature/my-feature --force-with-lease

GitHub CLI

# Create PR
gh pr create --title "feat: ..." --body "..."

# Check status
gh pr status
gh pr checks

# View PR
gh pr view
gh pr diff

# Manage PR
gh pr ready              # Mark draft as ready
gh pr review --approve   # Approve (if reviewer)
gh pr merge             # Merge (when approved)

PR 前の検証

# Run checks
npm run lint
npm test
npm run build

# Use skill script
./scripts/pre-pr-check.sh

# Check git status
git status
git diff --stat

# Review changes
git diff
git log --oneline -5

---

例

変更前と変更後の比較全体については、同梱の例を参照してください：

• assets/good-pr-example.md - 構成の整った PR
• assets/bad-pr-example.md - 避けるべきよくある間違い

---

要点

1. PR をクリーンにする - 提出前に個人的な開発用ファイルをすべて削除する
2. CONTRIBUTING.md を読む - まず必ず読み、指示に正確に従う
3. PR を小さく保つ - 理想は 200 行未満、PR ごとに 1 つの変更
4. すべてをテストする - 提出前にローカルでテストし、CI の失敗にはすぐに対処する
5. 規約に従う - スタイル、コミット、テスト、ドキュメント
6. 適切にコミュニケーションする - 敬意を持ち、迅速に対応し、辛抱強く、プロフェッショナルに振る舞う
7. 課題にリンクする - 関連する課題を自動的にクローズするには「Closes #123」を使う
8. 辛抱強く待つ - メンテナーは多くの場合、限られた時間で活動するボランティアである
9. フィードバックから学ぶ - すべてのレビューが学びの機会である
10. 自動化を活用する - スクリプト、テンプレート、チェックリストでミスを防ぐ

---

リソース

同梱リソース：

• scripts/pre-pr-check.sh - 提出前にアーティファクトをスキャンします
• scripts/clean-branch.sh - よくある個人的なアーティファクトを削除します
• references/pr-template.md - PR の説明テンプレート
• references/pr-checklist.md - 提出前の完全なチェックリスト
• references/commit-message-guide.md - Conventional Commits ガイド
• references/files-to-exclude.md - 除外対象の包括的なリスト
• assets/good-pr-example.md - 適切に構成された PR の例
• assets/bad-pr-example.md - 避けるべきよくある間違い

外部リソース：

• GitHub オープンソースガイド：https://opensource.guide/
• 貢献方法：https://opensource.guide/how-to-contribute/
• Conventional Commits：https://www.conventionalcommits.org/
• GitHub CLI：https://cli.github.com/manual/

---

本番環境で検証済み：✅ 実際のオープンソースへの貢献とメンテナーからのフィードバックに基づいています

トークン効率：試行錯誤による学習と比べて約 70% 削減できます

防止できるエラー：解決策とともに、よくある 15 の間違いを記載しています

最終確認日：2025-11-05