本記事では、「OSS応援企画」として記事末に「応援ボタン」を設置しています。1回の応援につき、Findyが100円をOSS団体などへ寄付し、エンジニアの成長とOSSの発展を応援する取り組みです。開発者の想いや取り組みに共感した気持ちが、OSSの支援にもつながっていく、そんな前向きな循環をFindyは目指しています。「応援ボタン」は、1日1回まで押すことができます。記事を読んで「いいな」と感じたら、ぜひボタンを押してあなたの応援の気持ちを届けてください。
こんにちは、翠と申します。フロントエンドの開発ツールであるViteのコアチームメンバーとして、3年くらい活動しています。
さて、OSSに関わる中で、「どう書けばうまく伝わるのか」「どうすれば素早く対応してもらえるのか」といった悩みを抱く人は少なくないでしょう。
- バグを見つけたけど、Issueに何を書けばよいか分からない
- 修正コードは書いたけど、プルリクエストの説明をどう書けばよいか自信がなく、提出をためらっている
こうした壁を感じることは、決して珍しいことではありません。 実は、メンテナーが何を求めているかを知ることが、自信を持って貢献するための第一歩となります。
この記事は、月に70件以上のIssueやプルリクエストに目を通している筆者が、メンテナー視点で、｢すぐ対応したくなる｣Issueやプルリクエストにどのような特徴があるかを説明していきます。 すぐに対応されるものと、そうでないものの違いは一体どこにあるのでしょうか。 その鍵は、メンテナーの視点を理解し、単なる「依頼者」から「協力者」へと立場を変えることにあると考えています。
もちろん、OSSにおけるやりとりは、必ずしもすぐに対応されるとは限りません。 だからこそ、伝え方を工夫して対話をスムーズに進めることが、あなたの貢献をしっかりと届けるための近道になります。 この記事では、そのための具体的な方法を紹介していきます。
Issueの書き方：「個人」から「全体」の課題へ
まずはIssueの書き方についてです。 Issueには大きく分けて「バグ報告」と「機能改善要望」があります。 それぞれの目的を見据えることで、伝えるべき内容や構成が変わってきます。
バグ報告：「個人の問題」を「みんなの問題」に変換する
バグ報告で一番大切なのは、あなたが遭遇した問題を、他の誰でも再現できる形にすることです。 メンテナーはもちろん、他のコントリビューターが対応できるかどうかは、この点にかかっていると言っても過言ではありません。
そのためには、Minimal Reproducible Example（最小の再現コード）の提供が極めて有効です。 これはMinimal Reproductionとも呼ばれ、多くのOSSプロジェクトでIssueを立てる際の必須要件となっています。 なぜなら、これが提供されることで、あなた個人の環境だけで起こる特殊な問題ではなく、「誰の環境でも再現できる、プロジェクトが解決すべき共通の問題」へと昇華させることができるからです。 再現手順は、手動操作を極力減らし、リポジトリをクローンして数個のコマンドを実行するだけで済むように自動化されているのが理想です。 これにより、手順の解釈のズレなく正確な問題の確認が可能になります。
さらに理想的なのは、再現テストをプルリクエストとして送ることです。
たとえば、vitejs/vite#18244 では、テストコードを添えたIssueが投稿され、後の修正プルリクエスト（vitejs/vite#18246）でそのまま活用できました。
このようにプルリクエストでそのままテストが使われた場合は、Co-Authored-By をコミットに記載してもらうことで、コミットログにもアイコンが表示されます。
機能改善要望：「解決したい課題」そのものを共有する
機能改善のIssueでは、「こういう機能が欲しい」だけでなく、「その機能がなぜ必要か」を明確にすることが重要です。
ありがちなのは、提案者自身が「機能」の形で要望を出してしまい、実はそれが「本質的な問題の解決になっていない」というパターンです（いわゆるXY問題）。
このような事態を避けるために、以下の情報を内容に含めるとよいでしょう。
- あなたが実際に直面している課題
- 既存の回避策とそれが不十分な理由
- 機能追加以外の選択肢も含めた検討余地
背景が丁寧に説明されていれば、仮に提案がそのまま採用されなくても、メンテナーが代替案を提示したり、議論を深めることができます。
加えて、情報量が豊富で背景が分かりやすい要望は、それ自体が「この課題は深刻かつ汎用的だ」という証明にもなります。 そのようなIssueは、後から参照されたり、他の人の賛同を得やすくなります。
例えば、vitejs/vite#19273やvitejs/vite#15850は、背景とともに複数の解決案を提示しています。
また、メンテナーは常にプロジェクト全体のバランスを考えています。 各々の要望に応えるために次々と固有の機能を追加していては、プロジェクトの肥大化は避けられません。 そのため、最小のインターフェースで最大限の価値を生み出すことが重要になります。 したがって、単に自分の欲しい機能を提案するだけでなく、「この機能は、自分の課題を解決すると同時に、他の多くのユーザーが抱えるであろう類似の問題もカバーできます」と説明できると、提案の説得力は格段に増します。 こういったIssueはもはや単なる「要望」ではなく、プロジェクトの未来を考えた「提案」と言えるでしょう。 このような「ともに作り上げる」姿勢こそが、メンテナーやコミュニティの協力を引き出す鍵となります。
プルリクエストの書き方：「一度きり」から「未来」の資産へ
次に、プルリクエストの書き方です。 プルリクエストで最も大切なのは、「この変更が安全で、かつ妥当である」とレビュアーに納得してもらい、マージされることです。
なぜこの方針なのか？を明確に
まず重要になるのが、「この修正をなぜこの形で実装したのか？」という理由の説明です。
- 他の選択肢（方針）と比較して、なぜこの方法が最適だと思ったのか
- バグ修正の場合は、原因がどこにあり、どう修正したのか
例えば、vitejs/vite#19010を上げてみます。
このプルリクエストではEmscriptenの出力したコードをViteで利用したいという背景のもと、new Worker(new URL('./path.js', import.meta.url))の記法に動的なnameオプションを許可するように変更しています。
このプルリクエストの説明文と関連するコメントには、Emscripten側の要件とほかのアプローチとの比較が記載されています。
もう一つ例としてvitejs/vite#19646を上げてみます。
このプルリクエストでは、Array::filterのコールバックに渡される第二引数のせいで発生していたバグを修正しています。
もし説明がなければ、このコードを見ただけではこの変更の意図をすぐに理解するのは難しかったでしょう。
このように実装の背景や理由が丁寧に説明されていれば、レビュアーが意図を汲み取るためのコストが大幅に減り、結果としてレビューが迅速に進む可能性が高まります。
なぜこの変更は安全なのか？を示す
次に、プルリクエストがマージされやすくなる条件は、「この変更は安全です」と根拠を持って伝えることです。
- 該当箇所に対してユニットテストや統合テストを追加しているか
- 既存の挙動に影響を与えない設計になっているか
- ドキュメントや型定義など、周辺影響も確認されているか
修正の正しさを主観ではなく客観的な証拠（テストなど）で示せると、マージのハードルは格段に下がります。 例えば、vitejs/vite#19476 では適切なテストが追加されています。
メンテナーはレビュー時に「壊れないか」「他に影響しないか」という点に注意を払っています。 その不安を先回りして解消できるプルリクエストは、それだけで非常にありがたい存在です。
これらの点がカバーされていれば、レビュアーは変更の意図を理解し、安全性を確認した上で、意思決定とコードの細部の確認に集中できます。 これによりレビューコストが劇的に下がり、マージまでの時間が短縮されるでしょう。
さらに、説得力のある説明には、なぜこの変更が将来にわたって有効かという見通しが含まれていることも少なくありません。 そうした視点は、あなたが単に目の前の課題を解決したいだけの「部外者」ではなく、プロジェクトの未来をともに考える「コミュニティの一員」であるという信頼を生み、マージへのハードルをさらに下げてくれます。
信頼される貢献の共通点：「ともに作る」意識
ここまで、Issueやプルリクエストを受け入れられやすくする具体的なポイントを見てきました。 背景を丁寧に説明する、再現可能なコードを提供する、変更の意図を明確にするなど、一見すると面倒な作業に思えるかもしれません。 しかし、そのひと手間が、結果的にメンテナーやコミュニティの協力を引き出し、解決の道のりをスムーズにしてくれます。
これらのポイントに共通しているのは、「OSSを一緒に作っていく」という考え方です。
OSSは誰かのサービスではなく、みんなで作り上げる共同の成果物に近いものです。「使う人」と「作る人」を区別するのではなく、「ともに解決する仲間」としてコミュニケーションをとる姿勢が、信頼に繋がります。 そうして築かれた良好な関係は、目の前の課題解決を早めるだけでなく、将来あなたが別の貢献をしたいと思ったときにも、心強い土台となるでしょう。
次に何かを報告したり、コードを共有したいと思ったりしたときには、この記事で紹介した視点を少しだけ意識してみてください。 それだけで、コミュニケーションの質が変わり、あなたの貢献がより多くの人に届きやすくなるはずです。