issue の作成と作業のガイドライン

参加に関する全般的なガイドライン

issue を報告するとき、あるいは issue の会話に参加するとき、自分の入力したものがプロジェクト全体の進展に寄与していることを常に確認してください。あなたが開いた issue とあなたのコメントは、建設的で話題に即したものであり、単なるノイズになっていないかどうか考えてみてください。

次のようにしてください。

• 質問がある場合は、 issue を提出するのではなく、 MDN Web Docs チャットルームを使用して質問してください。
• 問題を修正する方法がいくつもある場合は、スタッフやコミュニティとディスカッションを行う必要があるかどうかを検討してください。 ディスカッションを使用することで、様々な視点から意見を聞き、合意された行動方針に収束させることができます。そうすることで、issue を集中させ、生産的にすることができます。
• issue を提出した後は、自分で問題を修正してみてください。プルリクエストの提出とレビューに関するガイドがあり、貢献プロセスで必要となることがすべて網羅されています。

次のようなことは避けてください。

• 複数の話題についてディスカッションしようとしたり、本筋から外れたコメントをしたりして、issue を複雑にすること。
• 漠然とした質問をするために、たくさんの issue を開くこと。
• まず自分で問題を解決しようとせずに質問をすること。

新しいドキュメントやウェブサイトの改善方法をご提案いただける場合は、新しいコンテンツや機能の提案をご覧ください。

issue の報告に関するガイドライン

issue は、バグを追跡するために使用されます。 issue は、単一の実行可能なタスク、または関連のある実行可能なタスクの集合でなければならず、明確な結果がなければなりません。

issue を提出する前に

まず、発見した問題の種類に基づいて、適切な MDN の GitHub リポジトリーを特定し、担当者が適切に処理できるよう、そこで issue を作成してください。その後、issue を作成する前に、その問題がすでに報告されていないか調べてください。

issue の報告

issue を開くためのヒントをいくつか示します。

• 適切なカテゴリーを選んで、 issue を報告してください。例えば、コンテンツのバグを報告するには、mdn/content リポジトリーにある Content issue テンプレートを使用します。

• issue を報告するにあたって、十分な情報を提供してください。

  • issue のタイトルは、必要なアクションを簡潔に伝えるものでなければなりません。

  • issue の説明は、バグと、できればその解決に必要なアクションを明確に記述する必要があります。

    解決に複数の段階が必要な複雑な issue については、タスクリスト を使用して、作業を小さなタスクに分割してください。issue のステータスを更新する際は、issue にコメントするのではなく、 issue の description 欄に直接記載してください。これにより、それ以外にも他のメンバーが各 issue の進捗状況を確認するために issue のコメントをスクロールして探す必要が省けます。issue へのコメントは、issue の解決に役立つ詳細情報やコンテキストに限定してください。

• 以下のような状況に陥った場合は、GitHub の MDN のディスカッションに会話を移動してください。

  • その issue が正当なものなのか、またどのような措置が要求されるのか、確信が持てない場合。
  • この issue について、解決に向けた明確な合意が得られていない場合。

• 軽微で小さなバグについては、自分自身で変更を行い、プルリクエストを送信してください。

issue に指定された情報が不完全な場合、issue のトリアージプロセスの途中で、詳細情報の提供を依頼されることがあります（needs info というラベルにご注意ください）。

タスクリストの issue の作成

開く issue がバグ報告ではなく、一連のタスクの実行である場合、 issue をタスクリストとして作成することができます。説明文には、タスクを実行するための背景や理由を記述します。実行可能なタスクがすべてチェックリストとして掲載されていることを確認してください。

例を示します。

// issue のタイトル
節が CSS プロパティテンプレートで定義された順序に従っていることを確認する。

### 説明

CSS プロパティページのテンプレートは[こちら](/ja/docs/MDN/Writing_guidelines/Page_structures/Page_types/CSS_property_page_template)で定義されています。
この issue のタスクリストは、文書化された CSS プロパティをテンプレートと比較し、準拠のためにプロパティページの変更を追跡するために使用されます。

### チェックするページの一覧

- [x] [accent-color](/ja/docs/Web/CSS/Reference/Properties/accent-color) - チェック済み、OK
- [ ] [backdrop-filter](/ja/docs/Web/CSS/Reference/Properties/backdrop-filter)
- [ ] [letter-spacing](/ja/docs/Web/CSS/Reference/Properties/letter-spacing) - `アクセシビリティの考慮` と `国際化の考慮` の節を `仕様書` の節の前に移動するプルリクエストを開いた

issue を作業するためのガイドライン

issue を受け持った場合、これはきちんと時間内に作業を完了することが期待されていることを忘れないでください。 報告された issue の作業が進まない場合は、メンテナーが状況を把握できるよう、また他の協力者がその issue を引き継げるよう、コメントを追加してください。

これは、 issue に対して作業するための全般的な手順です。

1. issue を探します。 協力を検討されてる方は、優先度ラベル p2 または p3 がついた issue を検索してください（これらの優先度ラベルの意味についてはこちらをご覧ください）。あるいは、コミュニティからのプルリクエストを募集していることを示すラベルのいずれか (good first issue, accepting PR, help wanted) が付いた issue を見てみてください。ほとんどのリポジトリーにこのようなラベル付けの issue があります。あなたのスキルセットに適した issue を選んでみてください。

   作業する issue を探すのに有益なもう一つの場所は、MDN Contributor Board です。このプロジェクトビューは、複数のリポジトリーから開いている issue を一覧表示します。この一覧は、あなたが興味を持っているトピック（Labels 列）をもとにフィルタリングすることができます。興味があれば、issue のトリアージプロセス中に取得されるラベルの意味を確認してみてください。

   メモ: needs triage ラベルの付いた issue は、MDN チームがまだその issue をレビューしていないので、作業を始めない方がよいことを示します。

2. その issue について、すでに誰かが対応していないか調べます。

   issue の作業が始まる前に、まずその issue に割り当てられているユーザーがいないことを調べてください（Assignees フィールドが "Unassigned" になっている必要があります）。

   次に、関連付けられたプルリクエストがないか調べてください。これらが存在する場合、別の協力者がその issue を割り当てられ、作業を開始している可能性があるためです。

3. 調査を行います。

   ほとんどの issue は、作業を始める前に何らかの調査を必要とします。

   • 行う必要がある作業を調べてください。 issue の記述が不十分だったり、必要となるものがよくわからない場合は、遠慮なく issue を開いた人に（@username を使用して）言及し、詳細な情報を要求してください。
   • もし質問が必要なら、 MDN Web Docs チャットルームで助けを求めてください。

4. issue を処理します。

   以下の手順に従うことで、未割り当てかつ未処理の issue を「処理」することが可能です。

   1. リポジトリーをフォークし、作業用ブランチを作成してください。

   2. issue を修正してから、リポジトリーでプルリクエスト (PR) を開いてください。

   3. プルリクエストの description には、「Fixes #<issue_番号>」という文言を記載してください（プルリクエストでその issue が部分的にしか修正されていない場合は、「Related to #<issue_番号>」という文言を追加してください）。

      このテキストを追加することで、そのissue と PR の間に相互参照が作成され、暗黙的にその issue をあなたが担当するものとマークされます。

      メモ: 必要な権限を持っている場合は、明示的にその issue を自分に割り当てるするようにしてください。

   プルリクエストで更新したファイルに応じて、レビュー担当者が自動的に割り当てられます。（トピック分野ごとのチームは、CODEOWNERS ファイルで定義されています）。

   警告: プルリクエストを開いた後、変更を加えたりレビューのフィードバックを反映させたりする時間がなくなった場合は、できるだけ早くプルリクエストのコメント欄でチームにその旨を伝えてください。 これにより、チームは別の関心のある協力者を割り当て、プルリクエストの作業を完了させ、関連する issue をクローズすることができるようになります。

5. issue を「完了」としてクローズする

   description 欄に Fixes #<issue> と記載してプルリクエストを開いた場合、そのプルリクエストがマージされると、その issue は自動的に閉じられます。それ以外の場合は、その issue に、それを修正する 1 つ以上のプルリクエストへのリンクを記載したコメントを追加してください。そうすれば、メンテナーがその issue を「完了」として閉じます。

issue を自分で修正する

もしバグを見つけたら — それがウェブサイトのルック＆フィールの issue であれ、文書の誤りであれ — 自分自身でプルリクエストで修正することができます。 バグが軽微なもの（タイプミスや文の改善など）である場合や、すばやく修正できる場合は、適切な変更点を添えてプルリクエストを送信してください。

その他の種類のバグについては、 issue を開くことから始めてください。 その issue に取り組む意思を示すコメントを追加し、可能であれば、提案する解決策や修正するための手順を記述してください。

issue に取り組む際のガイドラインを使用し、以下のように適切なソースを更新して、 issue を修正するようにしてください。

• MDN Web Docs のコンテンツ（英語）は mdn/content リポジトリー
• MDN Web Docs の翻訳コンテンツは mdn/translated-content リポジトリー
• MDN Web Docs のフロントエンドは mdn/fred リポジトリー

各リポジトリーには、どのように使用するかをガイドするための有益な情報が記載されています。 詳しい情報は、 GitHub の主なリポジトリーを参照してください。

issue のトリアージに関するガイドライン

MDN Web Docs の GitHub 組織のメンテナーまたはオーナーであれば、 1 つまたは複数の MDN Web Docs リポジトリーのその issue のトリアージに責任を負います。

トリアージの全体的なプロセスには、全般的なタスクと[ issue 特有のタスク](# issue 特有のトリアージタスク)があります。

全般的なトリアージ作業

• issue を開くと、その issue に needs triage ラベルが自動的に設定されます。このラベルを検索すると、[トリアージが必要な issue ](# issue 特有のトリアージタスク)を探すことができます。協力者およびその他メンバーは、 issue がトリアージされるまで、この issue に対して作業をしてはいけません。（トリアージ担当者は、その issue をトリアージした後、needs triage ラベルを削除することを忘れないでください。）

• mdn/content リポジトリーでは、追加の Content: ラベル、例えば Content:CSS や Content:WebAPI などが自動的に issue に設定されます。これは、その issue で言及されているMDN URLに基づいて設定されます。このコンテンツ特有のラベルを使用して、特定のトピック領域でトリアージすべき issue を探していくことができます。

• その issue が en-US 以外のアクティブなロケールに関するものであれば、 l10n-fr、l10n-zh、l10n-ja などの適切なラベルを設定してください。それらのロケールのチームがその issue をピックアップし、トリアージします。

• issue のトリアージは、常に積極的に行う必要はありません。毎週 30 分など、自分の担当領域で定期的に issue のトリアージを行うための補助的な時刻を設定してください。トリアージは会議の中で行う必要はありませんし、皆と同じ時刻に行う必要もありません が、トリアージされていないバグのバックログが多くなりすぎないように、定期的に行う必要があります。

• 毎週送られてくる issue のトリアージとは別に、古いバグのリストを見直して、停滞しているもの、閉じる必要のあるもの、もう関係のないものがないかどうかを確認しましょう。30 日間活動のないその issue には、自動的に idle ラベルが設定されます。

  • 割り当てられた issue で、開いたままのものがあれば、割り当てられた人が進捗しているかどうか調べてください。割り当てられてから 1 週間経っても進展がない場合は、まだその issue に取り組む時間があるのかどうか尋ねてみてください。さらに 1 週間経っても進展がない場合は、割り当てを解除し、その issue を他に関心を持つ協力者に利用できるようにすることを示すコメントを残してください。
  • その issue を修正するためのプルリクエストが開かれているにもかかわらず、1 週間レビューされていない場合は、レビュアーに優しく ping を打って、その issue に手を付けられるかどうか要請してみましょう。
  • もしその issue を修正するためのプルリクエストが 1 週間後にレビューコメントへの対応を待っているのなら、作者にレビューへの対応が可能かどうか依頼してください。さらに 1 週間が経過したら、時間があれば自分でレビューコメントを修正するか、プルリクエストを閉じて関連の issue の割り当てを解除するかしてください。

issue 特有のトリアージタスク

それぞれの issue をトリアージする際に従うべきガイドラインは以下のとおりです。

issue が有効かどうか検討する

issue に対して妥当性を検討する際には、次のような点に留意する必要があります。

• 提起されたその issue が妥当かどうか。
• 修正されることで読者やウェブサイトのコンテンツが改善されるかどうかを評価してください。
• 修正された場合の影響が小さいか、サイト全体に及ぶかを評価してください。
• その issue の修正がまずディスカッションを必要とするかどうかを評価し、その場合は代わりにディスカッションを開くように指摘してください。
• その issue が執筆ガイドラインやテンプレートに従っているかどうかを調べてください。例えば、リンクの追加に関する提案が、外部リンクポリシーに従っているかどうか調べてください。
• その issue が既存の issue と重複していないか調べてください。重複している場合は、重複として issue を閉じることが可能です。

情報の完全性について issue を検討する

それぞれの issue を以下のチェックリストに照らして検討し、その issue に、誰かがそのバグの作業を始めるための記述された情報が含まれていることを確認してください。

• issue がある MDN Web Docs ページの URL、または issue が複数のページに存在する場合は MDN Web Docs ページの URL の例。
• issue を見つけた MDN Web Docs ページの具体的な見出しまたは節。
• 不正確な情報、役に立たない情報、不完全な情報、または不足している情報の明確な説明。

上記の情報のいずれかが存在しない場合、その issue の作成者にこれらの情報を提供するよう依頼し、needs info ラベルをその issue に追加してください。その情報の詳細が提供された後に、 issue のトリアージを再開してください（その後、needs infoラベルを削除することができます）。作成者から回答を得るまで、最長で 1 週間ほど待っても issue ありません。

優先度ラベルを設定する

各バグについて、その issue の重要度に応じた優先度ラベルを設定し、最も重要な issue ・領域に作業したい人が作業しやすいようにしてください。

• 重大な issue 。その issue がサイトのどこに現れているかにかかわらず、できるだけ早く修正する必要があります。そのような issue は、MDN の評判に深刻なダメージを与えたり、ユーザーに危害を加えたりする可能性があります。その issue の例としては、不正なコードスニペットが記載されており、実運用で使用された場合、深刻なセキュリティ issue を引き起こす可能性があるものや、マルウェア、冒涜、ポルノ、ヘイトスピーチなどの好ましくないコンテンツ、またはそうしたコンテンツへのリンクが挙げられます。

  • ラベル: p0 （直ちに対応を行う）

• 重要な issue: この種類の issue は、ページの有用性に深刻な影響を与える可能性があります。例えば、大量の古い情報、動作しない複雑で重要なコード例、文章が稚拙で理解しにくい部分が大量にある、リンク切れが多数ある、などです。

  • ラベル: p1 （早めに対応を行う）または p2 （早めに対応を行うが、より優先度の高い issue を優先する）

• 軽微な issue: これは、既存のコンテンツをより良くすることができるが、学習に影響を与えないか、軽微な影響しか与えない、改善 issue の種類です。この種類の issue は積極的に計画されるものではないので、これらの issue を修正するための協力者の手助けは歓迎され、大いに感謝されます。その issue を修正することは、投稿プロセスに慣れ始めた初心者の協力者に、必要な練習を提供することにもなります。例としては、タイプミス、文法の間違い、リンク切れ、少量の古い情報や悪い文、うまく動作しないコードスニペットなどが挙げられます。

  • ラベル: p3 （いつ対応するか指定しない）

一般的に、重大な issue はすぐに修正されるべきであり、MDN Web Docs のスタッフや仲間によって処理される可能性が高いものです。

有用な情報を追加する

可能であれば、その issue を修正するために協力者の助けとなる情報を追加してください。情報は、手順や一般的な手法、修正された他の同様の issue へのリンク、参考資料などの形でかまいません。よく練られた計画や手順は、特に good first issue とラベル付けされている issue では必要で、新しい協力者をすばやく立ち上げるのに役立ちます。このタスクは5分から10分程度の時間に設定することができます。

例えば、トリアージする人は、トリアージしている issue に以下のような情報を追加することができます。

その issue を修正する人は、以下のことが必要です。

- 見出し X の下の最初の段落を更新し、 Y の issue を修正しましょう。
- X の説明を追加しましょう。
- リンク X で互換性データを更新しましょう。

種類、目標、作業量のラベルを適用する

次に、以下のラベルを可能な限り設定してください。

• 該当する場合、修正する必要がある「issue の種類」を示すラベル。

  • broken link external: この issue では、外部ページへのリンクが切れていることが報告されています。
  • document not written: この issue は、通常はリンクが参照先として指定されているために、まだ作成されていない必要なドキュメントについて報告するものです。なお、当チームにはすでに多くの未作成のリファレンスページを追跡している Web Docs Backlog プロジェクトがあります。そのため、この issue がそれらのページに関するものである場合は、closed: duplicate を指定して issue を閉じ、バックログへのリンクを記載してください。
  • screenshot: この issue では、スクリーンショットが欠落しているか、古いものであることが報告されています。
  • baseline: この issue では、ベースラインバナーに誤りがあることが報告されています。なお、ベースラインバナーに表示されるデータは mdn/content リポジトリーから決まるものではなく、 その代わりに、ブラウザー互換性データ、フロントエンドコード、web-platform-dx/web-featuresからの情報の組み合わせによって決定されます。常に、意図通りに動作していることを示すために issue を閉じるか、適切なリポジトリーに移管する必要があります。

• 修正によって何を達成しようとしているかを示す「目標」ラベル。

  • goal: accuracy: この issue では、誤った情報や不正確な情報が報告されています。コンテンツが投稿時点で正確であった場合は、代わりに goal: up-to-date を使用してください。
  • goal: clarity: この issue では、誤解を招く、あるいは不明確な情報が報告されています（ただし、技術的には正しいものです）。
  • goal: completeness: この issue では、通常は重要な注意点や説明といった情報が欠落していることが報告されています。
  • goal: consistency: この issue には、情報に不整合が見られます。このラベルは、サンプルコードとその説明など、編集上の整合性を保つ目的でのみ使用してください。技術的に誤っている場所が少なくとも 1 か所ある場合は、代わりに goal: accuracy ラベルを使用してください。
  • goal: up-to-date: この issue では、通常はウェブプラットフォームの変更が原因で、情報が古くなっていることが報告されています。
  • goal: best practices: この issue は、サンプルコードやコンテンツで使用されている良くないパターンについて報告するものです。
  • goal: discoverability: この issue では、関連コンテンツへのリンクが欠落しているか、検索エンジンがページを探すのに役立つキーワードが欠落していることが報告されています。

• 協力者が、自分が可能な時間や作業量と一致する issue を探せるように役立つ「作業量」ラベル。実際の作業量は最終的には協力者のスキルや経験に依存するため、適切なラベルを付ける際には、最善の判断を使用してください。実際には、投入された作業量が成果物の量よりも大きい場合（例：作業に事前の調査が相当要求される場合）もあれば、その逆（例：単一の変更で多くのページに影響が及ぶ場合）もあります。

  • effort: small: 修正コードは 50 行未満になる見込みです（xs または s サイズのプルリクエストに相当します）。
  • effort: medium: 修正するにはおそらく 50 行から 1000 行程度かかる見込みです（m または l サイズのプルリクエストに相当します）。
  • effort: large: 修正するにはおそらく 1000 行以上かかるでしょう（これは xl サイズのプルリクエストに相当します）。

• コミュニティからのプルリクエストを募集していることを示す、「協力を受け入れています」という種類のラベルです。

  • good first issue: このラベルは、issue の修正方法が実に単純で、協力プロセスに慣れようとしている初心者にとって良い実践例となる場合に追加してください。以下の条件がすべて当てはまる場合にのみ、このラベルを適用してください。
    • 作成者またはトリアージ担当者から、具体的に何を記述する必要があるかについての指示がある（できれば原文通りのテキスト、あるいは段階ごとのガイド）。
    • この修正は単一のページのみを対象としています（そのため、協力者はウェブインターフェイスから簡単に修正可能です）。
    • この修正では、高度な技術的知識を要求されるような、大規模な新しいコンテンツやコードの記述はありません。
  • help wanted: その issue について知識がある、あるいは詳しい人の助けが必要な場合は、このラベルを設定してください。これはよく使われるラベルであり、一部の協力者は、自分の得意分野や専門分野におけるオープンソースプロジェクトで作業するべき issue を探すために、このラベルを使用しています。
  • accepting PR: その issue が good first issue ほど単純ではないものの、 help wanted ラベルが要求されるほど複雑でもニッチでもない場合は、このニュートラルなラベルを追加してください。

  ある issue にこれらのラベルが一つも付いていない場合、その issue へのコミュニティからの協力は推奨されていないことを示しています。これは、さらなるディスカッションが必要な場合、MDN の編集規約に精通した人物による対応が要求される場合、あるいはチームメンバーが対応を意図している場合などに当てはまります。ただし、プロセスを十分に理解している協力者であれば、こうした issue に取り組むことも可能です。

• issue のステータス: issue に、プルリクエストを受け入れることや、作業が進行中であることを示すラベルが付いていない場合は、何が原因でブロックされているかを示すために、以下のラベルのいずれかを追加してください。

  • needs BCD update: この issue が新機能や動作に関するドキュメントに関連し、実装時期に関するデータをまず確認する必要がある場合は、このラベルを設定してください。
  • needs content update: 別のリポジトリーで issue を修正する際に、mdn/content リポジトリーでも同等の修正が必要になる場合は、このラベルを設定してください。
  • needs decision: その issue について、手法に関するチームの合意が得られている場合は、このラベルを設定してください。合意は、ディスカッションや社内でのリアルタイム会議を通じて到達する場合があります。
  • needs example update: この issue が、別のリポジトリーにあるサンプルコードの同期に関するものである場合は、このラベルを設定してください。そのリポジトリーが外部リポジトリーである場合は、おそらく内部のライブサンプルに変換するか、MDN に移行する必要があるでしょう。
  • needs info: 前述の通り、この issue を処理するために、issue の作成者、当該コンテンツの作成者、またはその他の関係者から何らかの情報のリクエストがあった場合は、このラベルを設定してください。
  • on hold: その issue については、現時点ではまだ着手すべきではないことを示す一般的なラベルです。
  • waiting for implementations: このラベルは、その issue がブラウザーにまだ実装されていない機能に関連しており、ドキュメント掲載基準を満たさない場合に設定してください。

issue を分析・検証し、適切なラベル（種類、目標、作業量、コミュニティへの公開）を付与したら、トリアージプロセスは完了となり、needs triage ラベルを除去できます。

予定なしとして issue を終了する

ある issue が具体的なタスクに対応していない場合は、その issue を「予定なし」としてクローズすることを考えてみてください。Close issue ボタンの横にあるドロップダウンをクリックし、Close as not planned を選択してください。 issue をクローズする理由を説明するコメントを投稿してください。また、以下のラベルのいずれかを追加してください。

• closed: browser bug: この issue は、報告者のコードまたは MDN のコードにおける予期しない動作を報告していますが、その原因はブラウザーのバグです。また、この issue は BCD メモに記載するほど重大なものではありません。
• closed: question: この issue は、報告者の誤りや誤解に起因するものであり、コンテンツはすでに正確かつ明確です。とはいえ、報告には応答し、今後同様の質問が出ないように、コンテンツをさらに明確化することが可能かどうか考えてみるべきです。
• closed: wontfix: この issue は正当な問題を報告していますが、MDN はこれを修正しないことを決定しました。一般的な理由としては、スコープ外である、必要な作業量が見合う成果を上回る、あるいはコンテンツやコードが意図通りに動作している、などが挙げられます。

重複として issue を閉じる

ある issue で、すでに別の場所で追跡されている問題が報告された場合は、その issue を閉じることができます。完全に同一である必要はありません。既存の issue と十分に類似している場合は、それらを単一の issue に統合し、まとめて修正することができます。

同じ問題を追跡している GitHub の issue がある場合は、Close issue ボタンの横にあるドロップダウンをクリックし、Close as duplicate を選択して、その issue の URL を貼り付けてください。重複が明らかな場合はコメントは不要ですが、そうでない場合は、なぜそれらの issue が重複しているのかを説明するコメントを投稿してください。

問題が追跡されているものの、GitHub の issue を通じてではない場合（ウェブドキュメントのバックログなど）は、予定なしとして issue を終了し、コメントを投稿して、closed: duplicate ラベルを追加してください。このラベルは、Close as duplicate オプションで閉じられた issue については任意ですが、後で重複する issue を検索する際に役立ちます。