プルリクエストの提出とレビューのガイドライン

私たちは MDN Web Docs が、誰もが誇りに思えるような、歓迎され、友好的なコミュニティであることを望んでいます。 すべての参加者は、私たちの行動規範に従う必要があり、それは Mozilla コミュニティ参加ガイドラインを遵守することを意味します。 プルリクエストを開くため、レビューコメントを書くため、プルリクエスト作成者や他のコミュニティメンバーと対話するときは、礼儀正しく、建設的であるべきです。 あなたや他の誰かが、違法である可能性のある行動を経験したり、安全でない、歓迎されていない、または不快に感じたりした場合は、報告する ことをお勧めします。

MDNで作業を始める前に、下記の一覧にある推奨事項とガイドラインに目を通してください。

プルリクエストは、既存の課題 (issue) を解決するか、部分的に修正するものにしてください。 このような制約があるのは、他の誰かがすでに作業している可能性のある種類の作業を始めることを避けるためです。 協力したい MDN リポジトリー の課題やプルリクエストを検索し、始めたい作業がすでに作業されていないことを確認してください。 MDN プロジェクトに協力しようとするとき、あなたは以下のようないずれかの状況に置かれるでしょう。

• プロジェクトに協力したい場合、MDN GitHub リポジトリー（例: mdn/content の issues）と私たちの public GitHub project boards にある 'Issues' でタスクを探すことができます。 その課題が誰かに割り当てられていないこと、誰もそのタスクのためのプルリクエストを開いていないことを確認してください。 good first issue とラベル付けされた課題は、手始めに良いものです。

• MDN で問題を見つけた場合、まず課題を開いてください。課題は、作業を始める前にメンテナーからのレスポンスが必要です。これにより、プルリクエストで対処した問題が有効であり、プルリクが受け入れられることがわかるからです。その課題に関するより詳しい情報は、GitHub の課題に関するコミュニティのページで見つけることができます。

• 新しいコンテンツや機能を提案したい場合は、 'New content or feature suggestion' という GitHub の課題テンプレートから送信してください。

どこから始めたらいいかわからない場合は、 Discord サーバーで私たちに声をかけてフィードバックを求めてください。

プルリクエストを開くための準備ができたら、以下のガイドラインに従ってください。

• プルリクエストは短く、1 つの課題に焦点を当てたものであるべきです。 可能であれば、関連のある一連の変更を複数の小さなプルリクエストにまとめてください。 プルリクエストが大きすぎた場合、レビュアーはそのプルリクエストを閉じ、一緒になっている論理的な変更の集合ごとにプルリクエストを送信するように要求することがあります。
• 変更点の説明を追加してください。 プルリクエストのコンテキストと根拠をできるだけ多く指定されたものを提供します。
• 閉じる課題へのリンクを追加してください。 プルリクエストの説明文に、その課題を完全に解決する場合は 'Fixes' を、関連する課題である場合は 'Relates to' を追加します。 プルリクエストの課題へのリンクに関する詳しい情報は、GitHub のドキュメントにあります。
• 先にマージしなければならないプルリクエストがある場合、依存関係へのリンクを持つ 'depends on' を追加してください（例：他のリポジトリーにあるコードの例など）。
• サンプルコードの変更は、コンテンツの変更と一緒に行ってください。 これは、更新された例が正しく提供されることを確実にするために重要です。 例が使用される方法に影響を与えるようなコンテンツの変更を行う場合、関連するサンプルコードも更新する必要があります。
• レビュアーを追加します。 チームメンバーやトピックオーナーなど、プルリクエストをレビューすべき人が既に決まっている場合、レビュアーを追加することができます。
• 文法だけの変更はしないでください。 MDN Web Docs は技術ドキュメントです。文法が間違っている場合を除いて、文のスタイルの変更を提案すべきではありません。
• 特定の書式設定に従ったページでは、むやみに改行を追加したり削除したりしないようにしましょう。
• auto-merge を有効にしないでください。

• CI の失敗を処理してください。 GitHub Actions として自動テストが行われます。（.github/workflows を参照） これらのテストのうち 1 つ以上が失敗した場合、問題を解決するのはあなたの責任です。 もし、問題を解決する方法がわからなければ、助けを求めることができます。
• マージの競合を解決してください。メインブランチとの競合が発生した場合、解決するのはあなたの責任です。 これを行うには、mdn/main ブランチを自分のブランチにマージしてください。 詳しくは、GitHub ドキュメントの pull request の同期を維持する方法についてを参照してください。
• フィードバックに対応してください。 これは、レビューに基づいてプルリクエストに変更を加える準備をしておくということです。 レビューが行われ、変更が行われなかった場合、そのプルリクエストは閉じられるかもしれません。
• レビュー中は忍耐強く。 MDN の組織は大量のプルリクエストを受け取っており、チームがあなたの協力をレビューするのに時間を必要とする場合があります。
• 閉じられたプルリクエストを再開しないでください。 新しいプルリクエストを作成する必要がある場合は、閉じたプルリクエストを参照させてください。

プルリクエストを開くと、レビュアーが CODEOWNERS ファイルに基づいて自動的に割り当てられますが、レビューを依頼したい特定の人物がいる場合は、手動でレビューを依頼することができます。 また、私たちはプルリクエストのトリアージに役立つように、プルリクエストに自動ラベル付けを使用します。 メンテナーはプルリクエストをさらにトリアージし、コンテキストに基づいて必要であれば、needs-info や on-hold のような追加のラベルを追加することができます。

もしあなたがプルリクエストをレビューしたいが、レビュアーとして掲載されていない場合、あなた自身をレビュアーとして追加することができます。 レビューを始めるつもりであることをプルリクエストにコメントすることによって、最初に既存のレビュアーに確認するのが礼儀です。

MDN Web Docs チームは、レビュアーと担当者 (assignee) を使用して、プルリクエストの状態を追跡しています。

• レビュアーとは、プルリクエストの変更点を評価し、作成者にフィードバックを提供する人たちです。
• 担当者 は、プルリクエストがブロックされないようにするための責任者です。 すべてのプルリクエストに担当者がいるわけではありませんが、もしいれば、彼らはプルリクエストの進行を確認する責任があります。 担当者は、マージも、クローズも、ブロックもされていない作業を自分自身で引き受けることによって、作業を完結させることを助けます。

プルリクエストのレビュアーや担当者は、変更点をマージする責任を負います。

レビューを始めるには、プルリクエストの説明を調べて、特定の誰もレビューすべきではないことを確認してください。 すべての継続的インテグレーション (CI) タスクが完全に完了し、マージの競合がないことを確認してください。

もしタスクが失敗したり、マージの競合があったりした場合は、作成者にそのことを伝えてください。作成者が責任をもって対処する必要があります。 作成者を 担当者 に設定すると、レビューを始める前に作成者に対してプルリクエストに注意を促すことができます。 作成者が助けを求めるためのドアを開けておいてください。特にプロジェクトに新しく参加した協力者の場合です。

プルリクエストの変更点に関して言えば、コンテンツと文章は MDN 執筆スタイルガイドに、サンプルコードはコードスタイルガイドに従わなければなりません。

プルリクエストをレビューするときは、次のようにしてください。

• プルリクエストにコメントを追加して、作者にあなたがプルリクエストに気づき、レビューを始めることを知らせてください。 これは、他の誰かが不必要に同時にプルリクエストのレビューを始めるようなケースを避けるためです。
• プルリクエストに含まれる変更点のみにレビューの範囲を限定してください。 プルリクエストに含まれていない他の改善点を解決するためには、その課題またはプルリクエストを開いてください。
• レビューに技術的な支援が必要な場合は、助けを求めて review-help-need ラベルを追加してください。
• 複雑すぎる、あるいは無関係な変更が複数格納されている場合、無関係な変更を含むプルリクエストを閉じてください。 そのような場合、プルリクエストの作成者に、変更をより小さく分割して送信するよう依頼してください。
• あなたの仕事が手一杯で、レビューのための余裕がない場合は、負荷分散をリクエストしてください。 @core-yari-content チームにタグ付けして、他の誰かが手順を踏めるかどうか依頼してください。
• 'depends on' で示されたプルリクエストが先にマージされていない状態で、 マージを行わないでください。
• テストに失敗したプルリクエストをマージしないでください。 オープンソースのエチケット として、 main ブランチを安定に保つことは、協力者やメンテナー、自動化されたプロセスの混乱を避けるために良いことです。 不安定な main ブランチは、他のすべてのプルリクエストをブロックし、他の貢献者のレビューやマージが困難になります。 さらに、リポジトリーを見ている協力者は大量の通知を受け取り、テストの失敗によって発生させられる不要なノイズに苛立つことになります。 失敗したテストを修正する方法がわからない場合は、助けを求めるか、プルリクエストを他の人に割り当ててください。

もしプルリクエストが、小さな誤字や他にも小さな課題を除けば良いものに見えたら、その問題を直接修正したいと思うかもしれません。 プルリクエストが変更を許可するように設定されている場合は、これを行うことができます。 小さな問題を修正するための提案としてコメントを使用すると、一括してコミットすることができるのでおすすめです。

レビューを送信する際には、 approve（承認）、 comment（コメント）、 request changes（変更リクエスト）の 3 つの オプションをつけることができます。 この章では、各オプションを使用するタイミングについて、以下の節で説明します。

Requesting changes

あなたが提供したフィードバックが作成者によって対処された後、プルリクエストを承認してマージする前にレビュアーが再レビューする必要がある場合、 Request changes オプションを使用してください。

Comment

Comment オプションは、フィードバックが重要ではなく、再レビューを必要としない場合に使用されます。 要するに、あなたは作成者や他のレビュアーが適切な判断を使用することを信頼している場合です。

Approve

あなたの視点から見てすべてが順調で、マージする準備ができたときに Approve オプションを使用します。 レビューを送信した後、他のレビュアーがいないか、未対応のレビューコメントがなければ、安全にプルリクエストをマージすることができます。

行き詰まったときの対処法

コンテンツの変更について理解できない場合、またはそれが自分には大きすぎ、複雑すぎると感じた場合でも、慌てないでください。 始めるには、プルリクエストの作成者に情報を要求することから始めると良いでしょう。

大規模で複雑なコンテンツの変更を、何の前触れもなくレビューするよう要求されることは、めったにありません。 しかし、もしそうなった場合は、プルリクエストの説明文に、背景となる情報を説明する課題へのリンクが張られているはずです。

それでもわからない場合、あるいはコンテンツが疑わしいと思われる場合は、MDN Web Docs チームに連絡を取り、助けを求めてください。

この節では、あなたがプルリクエストの作成者であればレビューコメントに返信する際に、あなたがレビュアーであればプルリクエストをレビューする際に、予想される応答時間の詳細を説明します。

• レビュー時: プルリクエストのレビュアーは、2 週間以内に変更点をレビューできるようにする必要があります。 プルリクエストが開かれた後の 2 週間で、レビュアーは以下のことができます。
  • いつからそのプルリクエストのレビューを始められるかコメントを残す。
  • 技術的または資源的な支援を依頼する。
• 変更リクエストへの対応: プルリクエスト作成者は、4 週間以内にコメントに対して返答または修正する必要があります。 もしプルリクエスト作成者がその時間内にレビューコメントに返答または修正することができない場合、レビュアーは以下のいずれかを行うことができます。
  • 変更をコミットし、プルリクエストをマージする
  • プルリクエストを閉じる

MDN content リポジトリーでのプルリクエストの中には、ブラウザーのベンダーや組織による、作成者とレビュアーが特定された特定の作業に関連するものがあります。 このような場合、作成者はプルリクエストの説明の一番下の行にレビュアーのユーザー名を記載してください。

reviewer: @jpmedley

あなたがレビュー要求を受け取ったとしても、上記の方法で他のレビュアーが指定されていた場合は、その変更をレビューしないでください。 説明で述べたレビュアーが変更を承認した後、CODEOWNERS に承認の要求を依頼することになります。

レビュアーは、以下の記事を読んで、よくある作業に役立ててください。

• The Art of Closing では、未完成または却下されたプルリクエストを閉じる方法について説明します。
• Kindness and Code Reviews: Improving the Way We Give Feedback は、フィードバックをするための有益なヒントを与えてくれます。
• Code Review Guidelines for the Reviewer は、良いフィードバックと悪いフィードバックの例を提供しています。