contributor

コントリビューター

GitHub リポジトリの URL から PR のマージまでを実現する、オープンソースへの自動コントリビューションワークフローです。よくあるコントリビューションの失敗を防ぐ安全策が組み込まれています。

このスキルが必要な理由

オープンソースへのコントリビューションは、予測可能な理由で失敗します。修正する場所を間違える（メンテナーが上流での修正を優先したため PR がクローズされる）、他のコントリビューターと作業が重複する、プロジェクトの規約に従わない、あるいは単純な修正を過剰に作り込む、といったことです。このワークフローでは、体系的な事前確認によって、こうした失敗をそれぞれ防ぎます。

フェーズ 1：事前調査

コードを書く前に、プロジェクトとコントリビューションの状況を調べます。

1.1 対象を特定する

ユーザーに次の情報を尋ねます。

• GitHub リポジトリの URL（例：pydantic/pydantic-ai）
• コミットに使う GitHub ユーザー名とメールアドレス
• 取り組みたい特定の issue（または、対応可能な issue の検索を依頼する）

1.2 対応可能な issue を検索する

gh CLI を使って、コントリビューションに適した issue を見つけます。

# Get open issues with metadata
gh issue list -R <owner>/<repo> --state open --limit 50 \
  --json number,title,labels,assignees,comments

# Check for competing PRs on each candidate
gh pr list -R <owner>/<repo> --state open \
  --search "<issue_number> in:title,body"

絞り込み条件（次の順に適用）：

1. 担当者が割り当てられていない
2. すでに修正中のオープン PR がない（リンクされた PR と、タイトル／本文の検索の両方を確認）
3. 競合する PR が 5 件未満
4. 次のラベルが付いた issue を優先：bug、good first issue、help wanted
5. メンテナーが修正方針を示すコメントをしている issue を優先

1.3 issue のコメントを詳しく読む

候補となる issue ごとに、コメントスレッド全体を読みます。

gh issue view <number> -R <owner>/<repo> --json body,comments

次の点を確認します。

• メンテナーの修正方針：このリポジトリで修正することを希望していますか、それとも上流の依存関係で修正することを希望していますか？
• 推奨される方法：コードへのポインター、ファイルの参照、アーキテクチャに関する指針はありますか？
• 阻害要因：別の PR やリリースを待っていますか？
• 作業中の人：担当者が割り当てられていなくても、「対応します」とコメントした人がいる場合があります。

1.4 上流への差し戻しがないか確認する

これは最もよくある失敗パターンです。どの修正に取り組むか決める前に、必ず確認します。

# Check if maintainers reference another repo
gh issue view <number> -R <owner>/<repo> --json comments \
  | grep -i "upstream\|genai-prices\|separate repo\|other repo"

# Check related repos for recent PRs mentioning this issue
gh pr list -R <owner>/<related-repo> --state open --limit 10 \
  --json title,body | grep -i "<issue_number>\|<issue_keywords>"

修正が別の場所に属する可能性を示す兆候が少しでもあれば、作業を止めて、先にユーザーに確認します。

フェーズ 2：事前の連絡

事前の連絡なしに PR を提出してはいけません。必ず最初に意図を伝えます。

2.1 issue に解決方針の概要を投稿する

コードを書く前に、提案する方法を issue にコメントします。これには 2 つの目的があります。丁寧に作業を引き受けることを伝え、時間を無駄にする前にメンテナーが方針を変更できるようにすることです。

テンプレート：

Hi, I've been looking into this and traced the root cause to <X>.

Before I open a PR, I wanted to confirm the preferred approach:
A) <approach A — e.g., fix in this repo by modifying X>
B) <approach B — e.g., upstream fix in related-repo>

I can implement either direction. Happy to adjust based on your preference.

コードに進む前に、メンテナーからの返答を待ちます。活動中のプロジェクトで 24～48 時間経っても返答がない場合は、最も保守的な方法（現在のリポジトリ内で最小限の範囲を修正する方法）で進めます。

2.2 PR の進め方を計画する

最初はドラフト PR として作成します。次の条件を満たした後にのみ、レビュー可能な状態に変更します。

• CI が成功している
• メンテナーが issue のコメントまたは PR レビューで方針を了承している

フェーズ 3：リポジトリのセットアップ

3.1 フォークしてクローンする

gh repo fork <owner>/<repo> --clone --remote
cd <repo>

3.2 開発ブランチを特定する

main と決めつけてはいけません。最近マージされた PR の対象ブランチを確認します。

gh pr list -R <owner>/<repo> --state merged --limit 10 \
  --json baseRefName,mergedAt

最近マージされた PR で、最も多く使われている baseRefName を使用します。

3.3 コントリビューションガイドラインを読む

次のファイルを順番に確認します（存在するものを読みます）。

CONTRIBUTING.md
.github/CONTRIBUTING.md
.github/PULL_REQUEST_TEMPLATE.md
.github/PULL_REQUEST_TEMPLATE/

次の点を確認します。

• 必須のコミットメッセージ形式
• テスト要件
• コミット前フックまたはリンティング要件
• DCO／CLA 要件
• ブランチの命名規則

3.4 CI を把握する

ls .github/workflows/

CI 設定を読み、PR で実行されるチェックを把握します。次の項目のコマンドを確認します。

• リンティング／フォーマット
• 型チェック
• ユニットテスト
• 統合テスト
• コミット前フック

3.5 環境をセットアップする

プロジェクトに記載されたセットアップ手順に従います。変更を加える前に、テストスイート全体を一度実行し、テストが成功するベースラインを確認します。

フェーズ 4：コードの修正

4.1 issue ごとにブランチを作成する

git checkout -b fix/issue-<number>-<short-desc> <base-branch>

4.2 実装の原則

• 課題のコメントでメンテナーが推奨する方法が示されている場合は、それに従います
• 最小限の修正：課題の解決に必要な変更だけを行います。周辺コードのリファクタリング、機能の追加、ついでの「改善」は行いません
• プロジェクトのスタイルに合わせます：既存のコードパターン、命名規則、アーキテクチャに従います
• ハードコードしません：プロジェクトが同じ状況ですでに使用している場合を除き、値のハードコードは避けます
• テストを追加します：すべての修正に、バグを検出できるテストを対応させます。プロジェクト既存のテストパターンに従います

4.3 変更をテストする

プロジェクトのテストスイートを実行します。既存のテストはすべて合格する必要があります。追加したテストも合格する必要があります。プロジェクトで型チェックやリンティングを行っている場合は、それらも実行します。

言語ごとの検証：

• Python：pytest、mypy、ruff（またはプロジェクトで使用しているツール）
• TypeScript：npx tsc --noEmit、プロジェクトのテストコマンド
• Rust：cargo check && cargo test
• Go：go build ./... && go test ./...

フェーズ 5：コミットと提出

5.1 コミット前のチェック

プロジェクトで pre-commit フックを使用している場合：

pre-commit run --all-files

コミットする前に問題を修正します。

5.2 コミットの規約

# Configure author
git config user.name "<user's name>"
git config user.email "<user's email>"

# Commit with DCO sign-off
git commit -s -m "<type>: <description>

Fixes #<issue-number>"

ルール：

• プロジェクトのコミットメッセージ形式に従います（最近のコミットを確認して例を参考にしてください）
• 自動リンクされるように、Fixes #<number> または Closes #<number> を含めます
• Generated by Claude、Co-Authored-By: claude、その他 AI のクレジット表記は含めません
• 履歴を整理するためにリベースを使用し、強制プッシュは決して行いません

5.3 プッシュして PR を作成する

git push -u origin fix/issue-<number>-<short-desc>

プロジェクトのテンプレートに従って Draft PR を作成します：

gh pr create --draft --title "<type>: <short description>" \
  --body "$(cat <<'EOF'
## Summary
<1-2 sentences describing the fix>

Fixes #<issue-number>

## Changes
- <bullet points of what changed>

## Test plan
- <how this was tested>
EOF
)"

5.4 CI の結果に対応する

• CI に合格：PR にレビューの準備ができたことをコメントし、ドラフトを解除します
• コードが原因で CI に失敗：修正して新しいコミットをプッシュします。コミットの amend はしません
• インフラが原因で CI に失敗（ネットワークのタイムアウト、不安定なテスト、サービス停止）：失敗は変更と無関係であることを説明するコメントを投稿し、再実行を依頼します

フェーズ 6：提出後

6.1 PR がマージされずにクローズされた場合

慌てないでください。よくある理由と対応方法は次のとおりです：

理由	対応
修正が上流に取り込まれた	代わりに上流のリポジトリへの貢献を申し出ます
方法が却下された	どのような方法を希望するか尋ね、やり直しを申し出ます
重複	了承し、もう一方の PR のレビューを手伝うことを申し出ます
範囲が大きすぎる	より小さな PR に分割することを申し出ます

クローズされた PR 用のテンプレート：

Thanks for the feedback. I understand the fix direction has shifted to <X>.
Would it be helpful if I submitted a PR to <upstream-repo> instead?
Happy to contribute wherever it's most useful.

6.2 変更を依頼された場合

レビューのフィードバックには速やかに対応します。修正のたびに新しいコミットを作成します（レビュー中は squash しません。メンテナーが変更の経緯を確認したい場合があります）。メンテナーから依頼された場合にのみ squash します。

避けるべきアンチパターン

これらは実際の本番環境での貢献から確認された失敗例です：

1. 誤ったレイヤーで修正する：リポジトリ A で修正している間に、メンテナーがあなたの PR をクローズする数分前にリポジトリ B で PR を作成します。予防策：フェーズ 1.4 の上流チェックとフェーズ 2 の事前連絡。

2. PR の乱立：同じ課題に対して 5 人が PR を提出します。予防策：フェーズ 1.2 の競合する PR の確認とフェーズ 2 の作業の申告。

3. 過剰な設計：修正の範囲を超えて、エラー処理、型注釈、リファクタリング、「改善」を追加します。予防策：フェーズ 4.2 の最小限の修正の原則。

4. CI のインフラ障害を混同する：CI で不安定なテストやネットワークのタイムアウトが発生し、コードの問題だと誤解されます。予防策：フェーズ 5.4 で CI の失敗を明確に切り分けます。

5. 連絡なしで提出する：課題について事前に何も連絡せずに PR を提出します。予防策：フェーズ 2 の事前連絡は必須です。

6. ベースブランチを間違える：プロジェクトが dev で開発されているのに、main を対象に PR を作成します。予防策：フェーズ 3.2 でブランチを確認します。