MDN Web Docs におけるプルリクエストのエチケットとプロセス

この章では、協力者が MDN Web Docs に変更を加える方法と、変更がどのようにレビューされサイトに掲載されるかを説明します。

MDN Web Docs で行われるコンテンツの変更は、様々な作業の流れに関連するもので、その中には次のようなものが含まれます。

• 日々のコンテンツ改善作業: これには、新しい API、新しい CSS プロパティ、その他の重要なコンテンツの追加に関する文書化があります。これは通常、Mozilla、Google、Open Web Docs、Samsung などで作業している MDN Web Docs スタッフによって行われますが、コミュニティのボランティアによって行われることもあります。
• 「通りがかり」の修正: これには、誤字脱字、文法的な課題、技術的に不正確な点などを修正するためにサイトに行われる小さな更新があります。これらの課題は、通常 MDN Web Docs のユーザーが見つけます。
• コンテンツのバグ修正: これらは通常、有志によってMDN/コンテンツリポジトリーの課題を閉じるために行われます。

コンテンツの変更がどのように行われるかに関わらず、このリポジトリにプルリクエスト (PR) として送信されるため、サイトが古くならないように確実に保持するために、迅速なレビューとマージが必要となります。これは以下のような形で管理されています。

1. レビュアーの割り振り: さまざまな MDN スタッフやボランティアが「トピックレビューオーナー」として割り当てられています。つまり、サイトの特定のトピック領域（例えば CSS リファレンスや学習領域）に関連するプルリクエストが開かれると、その領域のトピックレビューオーナーに割り当てられることになります。これは CODEOWNERS ファイルを使用して処理され、特定のコンテンツディレクトリーがそれぞれのレビューチームに割り当てられます。
2. レビュー、承認、マージ: レビューが行われ、プルリクエストが承認されると、割り当てられたレビュアーがプルリクエストをマージします。
3. サイトでのコンテンツの更新: コンテンツが古くなりすぎないように、24 時間に一度、サイトが再構築されます。そのため、ボランティアは 24 時間後に自分の変更が反映されるのを見ることができます。

これらのガイドラインは MDN Web Docs に変更を加えるために PR を開く人に適用されます。

• PR を開く前に課題またはディスカッションを開く: もし PR がいくらか複雑なものを含んでいる場合（例えば、技術的な変更を含み、単なる誤字脱字の修正や文法的な改善、フォーマットや構造の変更ではない場合）、課題またはディスカッションを開き、変更を行う理由、その変更がどのようにコンテンツを改善するか、その他その内容について我々が知る必要があることすべてを記述してください。特にコンテンツの提案や機能の提案については、従うべきしっかりとした文書化のプロセスがあります。
• PR を短くする（PR あたり課題 1 つ): それぞれの PR には、単一の論理的な変更、あるいは一緒に送信するのが意味のある関連する変更の集合を収めるべきです。PR が大きくなりすぎたり、関係のない変更が多く収められていたりすると、レビューが困難になり、怪しく見えてくるかもしれません（大きな PR には悪意のある変更を隠すことが容易です）。このような場合、レビュー担当者は PR を閉じ、論理的にまとまった変更点ごとに別個の PR を送信するよう要求される権利があります。また、PR の説明で GitHub の特別な構文 を使用して関連する課題を参照することもよい習慣です。これはメンテナンスの助けになります。 PR がマージされると、 GitHub はリンクされた課題を自動的に閉じます。
• 文法を更新するための PR: PR では、大量の文法の更新を行ってはいけません。一見些細な変更でも、技術的な内容の意味を変えてしまう可能性があるため、これらは慎重なレビューが必要です。MDN Web Docs は技術的な文書化であることに留意してください。基本的な文法の改善は報告せず、明らかに文法が間違っている場合のみ報告するようにしてください。
• demo リポジトリーを更新するための PR: API の使用法を更新する PR の場合、対応する関連文書を更新するための mdn/content リポジトリーへの PR も必要になります。対応するコンテンツの PR がない場合、そのような PR は拒否されることがあります。
• 承認された PR のみ自動マージを有効にする: レビューや承認待ちの PR に対して、 "Enable auto-merge (squash)" チェックボックスを選択することは推奨されません。

PR を開いた後に何をすべきか、何を期待するかについての一般的なガイドラインがあります。これらのガイドラインを参照してください。

このガイドラインは、MDN コンテンツの PR をレビューする役割を担っているすべての人に適用されます。

自分が割り当てられたレビュアーである場合

• 開始するコメントを追加する: できるだけ早く、その PR を承知していて、すぐにレビューを始めるというコメントを追加してください。これは、あなたと同じ時刻に他の誰かがその PR をレビューするのを避けるため、また、あなたがその PR をレビューするために注目していることを他の人に知ってもらうための重要な手順です。
• PR の作成者に情報を要求する: もし PR 作成者がこの変更を行う理由を説明していない場合は、レビューのためにさらに情報をリクエストすることができます。理想的には、この PR で修正しようとしている課題を参照することです。
• 支援を依頼する: もし、技術的な支援が必要である場合は、review-help-needラベルを追加してください。

自分がレビューするよう選択されたコンテンツの変更について理解できない場合、またはその変更が自分にとって大きすぎ、複雑すぎると感じた場合でも、慌てないでください。同僚やトピックレビューオーナーグループの誰か（誰か知っている場合）など、他の人に助けを求めてもかまいません。もし、誰に助けを求めたらいいかわからない場合は、私たちの @mdn/core-yari-content グループに ping を送って、助けを求めてください。

この点に関連して、ページの完全な書き換えや、いくつかの新しい参照ページやチュートリアルの追加など、大規模で複雑なコンテンツの変更を予告なしにレビューする必要があることは稀です。通常、このような変更は、コンテンツの追加が承認され、レビュアーがすでに割り当てられている、特定の作業の流れの中で行われるものです。このような場合、PRは、それだけの詳細を説明する課題にリンクされるべきです。よくわからない場合は、PRの作成者にコンテンツのレビューが必要かどうか、また変更の根拠が説明されている場所を尋ねてください。それでもわからない場合や、コンテンツが疑わしいと思う場合は、MDN Web Docs chat rooms で私たちのチームに Ping を送って、支援を依頼してください。

• 関係ない変更の PR は閉じる: あなたには、 PR があまりにも複雑であったり、複数の無関係な変更を含んでいたりする場合、PR を閉じ、PR 作成者に変更をより小さな基本的な単位の塊として送信するよう依頼する権利があります。
• 負荷分散の支援を依頼する: もし、現在あなたの仕事がいっぱいで、時間内にレビューを完了できそうにない場合は、 @mdn/core-yari-content チームにコピーして、他の人にレビューを引き継いでもらえないか依頼してください。