課題の作成と作業のガイドライン

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

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

• 課題を提出する前に、スタッフやコミュニティとディスカッションを行う必要があるかどうかを検討してください。ディスカッションを使用することで、様々な視点から意見を聞き、合意された行動方針に収束させることができます。そうすることで、問題を集中させ、生産的にすることができます。
• 問題を提出した後は、自分で問題を修正してみてください。詳しくは、協力ガイド（英語）をご覧ください。
• 質問がある場合は、問題を提出するのではなく、 MDN Web Docs チャットルームを使用して質問してください。

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

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

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

MDN Web Docs のコンテンツやウェブサイトの外観に関するバグを見つけたと思ったら、関連するリポジトリーで現在開かれている問題を検索して、他に誰もその問題を報告していないことを確認してください。

• 発見した問題の種類に応じて、以下のいずれかに課題を提出して報告してください。

  • ドキュメント
  • 翻訳
  • ウェブサイトのルック＆フィール
  • 「試してみる」のインタラクティブな例の節
  • DOM 例外
  • 学習領域
  • ブラウザーの互換性情報

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

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

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

  • 課題の説明は、バグとその解決に必要なアクションを明確に記述している必要があります。また、その問題を解決するために完了すべきタスクやサブタスクが掲載されていなければなりません。他にも、以下のようなガイドラインがあります。

    • 説明フィールドを使用して、チェックリストを使用してタスクやサブタスクの状態を示しましょう。
    • 課題へのコメントではなく、課題の説明でタスクの状態を更新しましょう。課題に複数の部分がある場合、説明文の中でタスクリストを使用してください。これは、様々なタスクの状態を判断するために課題のコメントをスクロールする必要がなくなるので、他のユーザーにとって便利です。
    • 課題のコメントは、課題解決に役立つ詳細や文脈に限定すべきです。

• 課題で提供された情報に不備がある場合、課題のトリアージプロセスで後日連絡することがあります。

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

  • 課題を明確にするためにディスカッションが必要になった場合。
  • 課題を開いた後にディスカッションが始まった場合。
  • この課題について、解決に向けた明確な合意が得られていない場合。
  • 対処中にタスクの完了のための要件が増えたり、作業が不明確になったりした場合。

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

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

例を示します。

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

### 説明

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

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

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

課題を受け持った場合、これはきちんと時間内に作業を完了することが期待されていることを忘れないでください。代入されてから1週間経っても作業が進まなかったり、必要な作業ができなくなったりした場合は、コメントを残し、課題の割り当てを解除してください。

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

1. 課題を探します。 協力する課題を探しているなら、good first issue, help wanted または p3 ラベルのついた課題を探してみてください。ほとんどのリポジトリーにこのようなラベル付けの課題があります。あなたのスキルセットに適した課題を選んでみてください。作業する課題を探すのに有益なもう一つの場所は、MDN Contributors Task Boardです。このプロジェクトビューは、複数のリポジトリーから開いている課題を一覧表示します。この一覧は、あなたが興味を持っているトピック（Labels 列）をもとにフィルタリングすることができます。課題のトリアージ過程で取得されるいくつかの ラベル の説明を参照してください。

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

2. 課題を自分に割り当てます。 作業したい課題を見つけたら、その課題が他の人に割り当てられていないことを確認します。その課題に作業したい旨をコメントで追加し、もし可能であれば、その課題を自分自身に割り当ててください。

3. 調査を行います。 ほとんどの課題は、作業を始める前に何らかの調査を必要とします。

   • 行う必要がある作業を調べてください。もし質問が必要なら、 MDN Web Docs チャットルームで助けを求めてください。
   • その課題がよく説明されていて、作業がかなり明白であるなら、先に進んで実行してください。
   • その課題が十分に説明されていない場合や、何が必要なのかわからない場合は、遠慮なく投稿者を @ メンションして、より詳細な情報を依頼してください。

4. 変更を行います。 リポジトリーをフォークし、ブランチを作成します。自分の作業を行って、リポジトリーでプルリクエストを開いてください。プルリクエストの説明でその課題を参照してください。プルリクエストで更新したファイルに応じて、プルリクエストにレビュアーが自動的に割り当てられます（トピック領域ごとのチームは、CODEOWNERS ファイルで定義されています）。

   プルリクエストを開いた後、変更を加えたりレビューのフィードバックを取り入れたりする時間がもうないことに気づいた場合、できるだけ早くプルリクエストのコメントでチームに知らせてください。これは、チームが他の興味を持っている協力者を割り当てて、プルリクエストの作業を完了させ、リンクされた課題を閉じさせるのに役立ちます。

5. プルリクエストがレビューされ、マージされた後、そのリンクされた課題を閉じられたとマークすることができます。プルリクエストを開いた際に Fixes #<issue> という文言を入れると、プルリクエストがマージされた際に、その課題は自動的に閉じられます。

もしバグを見つけたら — それがウェブサイトのルック＆フィールの問題であれ、文書の誤りであれ — 自分自身で修正することができます。どのように協力できるかは、協力ガイドを読んでください。

誤字脱字やちょっとした文の改善など、小さなバグであったり、議論の余地のない修正が含まれる場合は、変更点を添えてプルリクエストを送信してください。

その他の種類のバグについては、その課題を開くことから始めてください。その課題に取り組む意思を示すコメントを追加し、可能であれば、提案する解決策や問題を修正するための手順を記述してください。 MDN Web Docs チームがその課題が正当なものであることを確認し、提案された解決策を承認するために、その課題がトリアージされるのを待ちましょう。

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

• MDN Web Docs のコンテンツ（英語）は content リポジトリー
• MDN Web Docs の翻訳コンテンツは translated-content リポジトリー
• MDN Web Docs ウェブサイトのルック＆フィールは yari リポジトリー

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

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

トリアージの全体的なプロセスには、全般的なタスクと課題特有のタスクがあります。

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

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

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

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

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

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

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

課題が有効かどうか検討する

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

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

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

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

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

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

優先度ラベルを設定する

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

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

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

• 重要な課題。その種類の課題は、ページの有用性に深刻な影響を与える可能性があります。例えば、相当量の古くなった情報、複雑で重要なサンプルコードが動作しない、文章が悪く理解しにくい文、大量のリンク切れなどがあります。

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

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

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

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

有用な情報を追加する

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

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

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

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

他のラベルを設定する

次に、以下のラベルを適宜設定します。

• effort: small, effort: medium, effort: large: 協力者の中には、バグを修正するのに必要な時間と労力に基づいてバグを検索したい人もいます。ですから、できれば、必要な労力の見積もりを提供するようにしてください。

• good first issue: その課題の修正が実に単純で、その課題を修正することが、プロセスを習得しつつある新人にとって良い練習になる場合、その課題にこのラベルを設定ししてください。

• help wanted: その課題が、そのトピックについて知っている人、または慣れることができる人からの助けを必要とする場合、このラベルを設定します。このラベルはよく使用されるもので、自分の慣れることや専門分野のオープンソースプロジェクトで作業するための課題を検索するために、このラベルを使用する協力者もいます。

• broken link external: 外部ページへのリンク切れが課題である場合、このラベルを設定してください。

• document not written: 課題がまだ書かれていない必要な文書に関係している場合、通常はリンクがその文書を指しているため、このラベルを設定します。

• needs content update: mdn/content リポジトリーと同様の修正を他のリポジトリーに行う必要がある場合の課題に、このラベルを設定してください。

  メモ: トリアージプロセスが完了したら、 needs triage のラベルを剥がしてください。