open-source-contributions

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

バージョン: 1.2.0 | 最終確認日: 2026-01-09 | 本番環境でのテスト済み: ✅

---

このスキルを使うタイミング

自動トリガー: 「submit PR to」、「contribute to」、「pull request for」、「open source contribution」

却下につながるよくある16のミスを避けながら、メンテナーに配慮したPRを作成します。

---

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

個人の開発作業で作成したファイル（絶対に含めない）

計画・メモ文書:

❌ 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

コミットメッセージの形式

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

種類: feat、fix、docs、refactor、test、ci、chore

例: feat(auth): add OAuth2 support for Google and GitHub

詳しくはreferences/commit-message-guide.mdをご覧ください。

---

PRの規模に関するベストプラクティス

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

• 理想: 50行
• 適切: 200行未満
• 最大: 400行
• 400行超: 不具合の検出率が大幅に低下します

PRを小さく保つ:

• 1つのPRにつき変更は1つ
• 未完成の作業にはフィーチャーフラグを使います:

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

• レイヤーごとに分割します: スキーマ → API → フロントエンド → テスト

---

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

貢献する前に:

1. CONTRIBUTING.mdを読みます（/、/.github/、/docs/を確認）
2. フォーマッターを実行します: npm run lint、npm run format
3. 既存のパターンに合わせます（最近マージされたPRを確認）
4. 提出前にテストします:

   npm test && npm run lint && npm run build
   

---

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

返信テンプレート:

• 実装済み: 「良いアイデアです！[commit hash]で実装しました」
• 異なる意見の場合: 「ご指摘のとおりです。Yという理由でXを選びました。他の案も歓迎します」
• 確認したい場合: 「Zの意味をもう少し詳しく教えていただけますか？」
• 催促（1〜2週間後）: 「このPRについて、念のためご連絡します。変更が必要であれば対応します！」

---

メンテナーを困らせるよくある間違い（防止される16のエラー）

詳細なガイダンスについては、「重要なワークフロールール」セクションを参照してください（ルール1～3）

1. CONTRIBUTING.mdを読まない - 必ず最初に読み、記載内容に正確に従ってください
2. 個人的な成果物を含める - SESSION.md、planning/*、スクリーンショット、一時的なテスト（PR前チェック用スクリプトを使用してください）
3. 大規模なプルリクエスト - 200行未満が理想、最大でも400行未満に分割してください
4. 提出前にテストしない - テストスイート全体を実行し、手動でテストし、証拠を記録してください（ルール2に違反します）
5. 割り当て済みのイシューに取り組む - 担当者を確認し、作業を引き受けるコメントを投稿してください
6. 大規模な変更について事前に相談しない - コーディングを始める前に、イシューを作成するかコメントしてください
7. 焦る／応答しない - 速やかに応答し、1～2週間後に状況を確認してください
8. ドキュメントを更新しない - README、APIドキュメント、インラインコメントを更新してください
9. コードスタイルを無視する - プロジェクトのリンター／フォーマッターを使用してください
10. CIの失敗を無視する - すぐに修正し、行き詰まったら助けを求めてください
11. 無関係な変更を含める - 1つのPRにつき1つの機能（ルール3に違反します）
12. イシューにリンクしない - 「Closes #123」または「Fixes #456」を使用してください
13. シークレットをコミットする - .envは絶対にコミットせず、シークレットをスキャンしてください
14. 警告なしに強制プッシュする - レビュー開始後は避けてください
15. ローカルでビルド／テストを実行しない - プッシュ前に必ず実行してください
16. main/masterで作業する - 必ずフィーチャーブランチを使用してください（ルール1に違反します）

---

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

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

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

# ✅ CORRECT
git checkout main
git pull upstream main
git checkout -b feature/add-oauth-support
# make changes on feature branch
git commit -m "feat(auth): add OAuth support"

ブランチの命名：feature/name、fix/issue-123、docs/update-readme、refactor/utils、test/add-tests

---

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

以下を行わずに提出しないでください：

1. テストスイート全体を実行する：npm test && npm run lint && npm run build
2. 手動でテストする（アプリを起動し、機能とエッジケースをテストする）
3. 証拠を記録する（画面に関わる変更はスクリーンショット／動画を用意し、コミットではなくPRの説明に追加する）
4. CIが通ることを確認する

テストチェックリストのテンプレート：

## 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/GitHub OAuth flows end-to-end
- ✅ Verified error handling
- ✅ Tested on Chrome, Firefox, Safari

---

ルール3：PRを目的に沿って一貫性のあるものにする

1つのPRにつき1つの機能／修正

• 理想：200行未満
• 許容範囲：200～400行
• 大規模：400～800行（理由の説明が必要）
• 大きすぎる：800行超（分割してください）

焦点を絞る：

• 計画：このPRで行うことは何ですか？
• 開発中：無関係なバグを見つけた場合は、別のブランチで対応してください
• コミット前：git diffを確認し、すべての変更がこの機能に必要かを確かめてください

大規模な機能は段階に分けてください：

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

---

ドラフトPRの使用

作成：gh pr create --draft レビュー可能にする：gh pr ready（コードが完成し、テストとCIが通ったとき）

イシューのリンク

自動クローズ用キーワード（PRの説明内）：

Closes #123
Fixes #456
Resolves #789

# Multiple: Fixes #10, closes #20, resolves #30
# Cross-repo: Fixes owner/repo#123

GitHub CLIの基本

gh pr create --fill                    # Auto-fill from commits
gh pr create --draft                   # Draft PR
gh pr status                           # See your PRs
gh pr checks                           # View CI status
gh pr ready                            # Mark draft as ready

---

提出前チェックリスト

完全版については、references/pr-checklist.mdを参照してください。

コントリビューション開始前：

• CONTRIBUTING.md、CODE_OF_CONDUCT.mdを読んだ
• 作業を引き受けるコメントをイシューに投稿した
• フィーチャーブランチを作成した（mainでは絶対に作業しない）

開発：

• ルール1：フィーチャーブランチで作業している
• ルール2：証拠を添えて十分にテストした
• ルール3：PRの対象を1つの機能に絞った
• すべてのテストが通る：npm test && npm run lint && npm run build
• ドキュメントを更新した

クリーンアップ：

• ./scripts/pre-pr-check.shを実行した
• 個人的な成果物がない（SESSION.md、planning/*、デバッグ用スクリーンショット、一時的なテスト）
• シークレットがない（.env、認証情報）

PRの品質：

• 変更を1つに絞った（200行未満が理想、最大でも400行未満）
• タイトル：Conventional Commits形式
• 説明：What／Why／Howの構成
• イシューへのリンク（Closes #123）
• 画面に関わる変更のスクリーンショット（PRの説明内）

提出後：

• CIを監視し、失敗をすぐに修正する
• フィードバックに速やかに対応する

同梱リソース

同梱されているサンプルとスクリプトをご覧ください。

• 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 ガイド
• assets/good-pr-example.md - 構成の整った PR の例
• assets/bad-pr-example.md - 避けるべきよくある間違い

---

重要なポイント

1. RULE 1：必ずフィーチャーブランチを使用してください（main は使用しないでください）
2. RULE 2：提出前に十分にテストしてください（自動テスト＋手動テスト＋証拠）
3. RULE 3：PR の対象を絞ってください（理想は200行未満、1つの PR につき1つの変更）
4. クリーンな PR：個人的なアーティファクト（SESSION.md、planning/*、デバッグ用スクリーンショット）を削除してください
5. CONTRIBUTING.md を読む：必ず最初に読み、記載内容に忠実に従ってください
6. Issue をリンクする：自動クローズするには「Closes #123」を使用してください
7. ./scripts/pre-pr-check.sh を使用する：提出前にアーティファクトをスキャンしてください

---

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

トークン効率：試行錯誤と比べて約70％削減

防止できるエラー：よくある16の間違い

最終検証日：2026-01-09