建立和處理問題

參與的一般準則

在報告問題或參與問題討論時，請始終確保您的輸入有助於專案的整體進展。請考慮您提出和評論的問題是否具有建設性和切中主題，而不僅僅是增加噪音。

請這樣做

• 如果您有問題，可以在MDN Web Docs 聊天室中提問，而不是提出問題。
• 如果解決問題的方法有很多，請考慮是否需要與工作人員/社群討論。利用討論來獲取不同的觀點，並就商定的行動方案達成一致。這有助於使問題保持專注和高效。
• 提出問題後，嘗試自己解決問題。有關拉取請求提交和審查的指南涵蓋了您需要了解的有關貢獻過程的一切。

避免這樣做

• 透過討論多個主題或發表偏離主題的評論使問題複雜化。
• 提出許多模糊的問題。
• 不首先嚐試自己解決問題就提問。

如果您想建議新的文件或改進網站的方法，請參閱提出新內容或功能。

報告問題的準則

問題用於跟蹤錯誤。問題必須是單個可操作的任務或一組相關的可操作任務，並且必須有一個明確的結果。

在提出問題之前

如果您認為您在 MDN Web Docs 的內容或網站的外觀和感覺方面發現了錯誤，請在相關儲存庫中搜索當前開放的問題，並確保沒有其他人報告該問題。

報告問題

根據您發現的問題型別，您可以透過在其中一個主要MDN GitHub 儲存庫中提出問題來報告它。如果您在問題中提供的資訊不完整，在問題分類過程中可能會要求您提供更多詳細資訊。

以下是一些提出問題的提示

• 選擇適當的類別來報告問題。例如，要報告內容錯誤，請使用 mdn/content 儲存庫中的內容問題模板。
• 在報告問題時提供足夠的資訊
  • 問題標題必須簡潔地傳達所需操作。
  • 問題描述必須清楚地描述錯誤以及解決問題所需的操作。它還必須列出為解決問題而要完成的任務或子任務。其他一些準則包括
    • 使用描述欄位透過清單指示任務或子任務的狀態。
    • 更新問題描述中的任務狀態，而不是在問題上發表評論。如果一個問題有多個部分，請在描述中使用任務列表。這有助於其他可能需要滾動瀏覽問題上的評論以確定各種任務狀態的人。
    • 問題中的評論應僅限於有助於解決問題的詳細資訊或上下文。
• 如果您發現自己處於以下情況之一，請將對話轉移到MDN 在 GitHub 上的討論
  • 需要進行討論以澄清問題。
  • 討論在問題開放後開始。
  • 問題在其解決方案上沒有明確共識。
  • 在解決任務或工作不明確時，完成任務的要求會擴大。
• 對於小錯誤，您可以自己進行更改並提交拉取請求。

建立任務列表問題

如果您要提出的問題不是為了報告錯誤，而是為了執行一系列任務，您可以將其建立為任務列表。在描述中解釋執行這些任務的背景或原因。確保將所有可操作的任務列為清單。

例如

// Issue title
Ensure sections follow the order defined in the CSS property template

### Description

The CSS property page template is defined [here](/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/CSS_property_page_template).
The task list in this issue will be used to compare the documented CSS properties with the template and track changes to the property pages for compliance.

### List of pages checked

- [x] [accent-color](/en-US/docs/Web/CSS/accent-color) - checked, okay
- [ ] [backdrop-filter](/en-US/docs/Web/CSS/backdrop-filter)
- [ ] [letter-spacing](/en-US/docs/Web/CSS/letter-spacing) - open pull request to move `Accessibility concerns` and `Internationalization concerns` sections before the `Specifications` section.

處理問題的準則

請記住，如果您承擔了一個問題，期望是及時完成工作。如果您在被分配後一週內無法取得任何進展，或者無法再完成所需的任務，請留言並取消分配自己。

以下是處理問題的一般步驟

1. 查詢問題： 如果您想做出貢獻，請搜尋帶有good first issue、help wanted 或p3 標籤的問題。大多數儲存庫都有帶有這些標籤的問題。歡迎您瀏覽並選擇適合您技能集的問題。另一個尋找可處理問題的好地方是MDN 貢獻者任務板。此專案檢視列出了來自多個儲存庫的開放問題。您可以根據您感興趣的主題（“標籤”列）過濾列表。請參閱問題分類過程中應用的一些標籤的描述。

   注意： 帶有 needs triage 標籤的問題表示 MDN Web Docs 核心團隊尚未審查該問題，您不應開始處理它。

2. 將問題分配給自己： 找到您想處理的問題後，請確保該問題未分配給其他人。新增評論說明您想處理該問題，如果可以，請將問題分配給自己。

3. 進行研究： 大多數問題在開始工作之前都需要進行一些調查。

   • 確定需要完成的工作範圍。如果您需要提問，請在MDN Web Docs 聊天室中提問。
   • 如果問題描述清楚，並且工作非常明顯，請繼續執行。
   • 如果問題描述不清楚，並且/或者您不確定需要什麼，請隨意 @提及發帖人並請求更多資訊。

4. 進行更改： 分叉並分支儲存庫。完成您的工作並在儲存庫中開啟拉取請求。在拉取請求描述中引用問題。根據您在拉取請求中更新的檔案，審閱者將自動分配給您的拉取請求。（按主題領域劃分的團隊在CODEOWNERS檔案中定義）。

   開啟拉取請求後，如果您發現自己不再有時間進行更改或採納審閱反饋，請儘快在拉取請求的評論中告知團隊。這將有助於團隊將另一位感興趣的貢獻者分配給完成拉取請求上的工作並關閉連結的問題。

5. 您的拉取請求經過審查和合並後，您可以將連結的問題標記為已關閉。如果您使用 Fixes #<issue> 語句開啟拉取請求，則在拉取請求合併時，問題將自動關閉。

自己解決問題

如果您發現了一個錯誤——無論是網站外觀和感覺的問題還是文件中的錯誤——您可以嘗試在拉取請求中自行修復它。如果錯誤很小（例如拼寫錯誤或輕微的句子改進）或涉及快速修復，您可以提交包含適當更改的拉取請求。

對於任何其他型別的錯誤，請首先開啟一個問題。新增評論說明您打算處理該問題，如果可能，請描述您提議的解決方案或修復步驟。

使用處理問題的準則，嘗試透過更新適當的來源來解決問題，例如

• mdn/content 儲存庫中的 MDN Web Docs 內容（英文）
• mdn/translated-content 儲存庫中的 MDN Web Docs 翻譯內容
• mdn/fred 儲存庫中的 MDN Web Docs 前端

每個儲存庫都包含有用的資訊，可指導您如何貢獻。有關更多資訊，請參閱我們的主要 GitHub 儲存庫。

分類問題的準則

如果您是 MDN Web Docs GitHub 組織中的維護者或所有者，您將負責在一個或多個 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 標籤。

  • 檢查仍然開放的已分配問題，看看被分配者是否正在取得進展。如果在被分配後一週內沒有進展，請詢問他們是否仍有時間處理該問題。如果再過一週沒有進展，請取消分配他們並留下評論，表明您正在將該問題提供給其他感興趣的貢獻者。
  • 如果已開啟拉取請求以修復問題，但一週內未進行審查，請輕輕提醒審查者，詢問他們是否可以處理。
  • 如果修復問題的拉取請求在一週後等待審查評論處理，請詢問作者是否可以回覆他們的審查。如果再過一週，如果您有時間，請自行修復審查評論，否則關閉拉取請求並取消分配相關問題。

特定於問題的分類任務

這些是分類每個問題時要遵循的準則。

審查問題是否有效

在審查問題的有效性時需要記住以下幾點

• 檢查提出的問題是否有效，以及修復是否會改善讀者和網站的內容。
• 評估修復的影響是小還是全站範圍。
• 評估問題的修復是否需要先進行討論，在這種情況下，請引導作者改為開啟討論。
• 檢查問題是否符合我們的編寫指南和模板。
• 檢查新增連結的建議是否符合我們的外部連結政策。

審查問題資訊的完整性

對照以下清單審查每個問題，以確保問題包含所述資訊，以便有人可以開始處理錯誤

• 出現問題的 MDN Web Docs 頁面的 URL 或如果問題存在於多個頁面上，則為示例 MDN Web Docs 頁面的 URL
• 在 MDN Web Docs 頁面上發現問題的特定標題或部分
• 對不正確、無用、不完整或缺失資訊的清晰描述

如果缺少上述任何資訊，您應該要求問題作者提供這些詳細資訊，併為問題新增 needs info 標籤。僅在提供這些詳細資訊後（之後，您可以刪除 needs info 標籤）才恢復分類問題。等待作者回復長達一週是可以的。

設定優先順序標籤

對於每個錯誤，根據問題的嚴重性設定優先順序標籤，以幫助想要處理最重要問題或領域的人。

• 關鍵問題：這種型別的問題需要儘快修復，無論它出現在網站的何處。這種型別的問題可能會嚴重損害 MDN 的聲譽和/或傷害使用者。此問題的示例包括不正確的程式碼片段，如果在生產中使用，可能會造成嚴重的安全性問題，以及不需要的內容，如惡意軟體、褻瀆、色情、仇恨言論或指向此類內容的連結。

  • 標籤：p0（將立即處理）

• 主要問題：這種型別的問題可能會嚴重影響頁面的有用性。例如，大量過時資訊、一個複雜且重要的程式碼示例無法工作、大量糟糕且難以理解的散文，或者大量斷開的連結。

  • 標籤：p1（將很快處理）和 p2（將很快處理，但優先順序更高的專案將優先）

• 次要問題：這是一種改進問題，可以使現有內容更好，但不影響學習或僅對學習有輕微影響。由於不積極計劃解決這些型別的問題，因此歡迎並非常感謝貢獻者幫助解決這些問題。修復其中一些問題還可以為開始熟悉貢獻過程的初學者貢獻者提供必要的實踐。示例包括拼寫錯誤、語法錯誤、斷開的連結、少量過時資訊或糟糕的散文，或無法工作的程式碼片段。

  • 標籤：p3（無法確定何時處理問題）

一般來說，關鍵問題應立即修復，並且很可能由 MDN Web Docs 員工和同行處理。

新增有用資訊

如果可能，新增可以幫助貢獻者修復問題的資訊。資訊可以以步驟、一般方法、指向其他類似已修復問題的連結或閱讀資源的形式提供。特別是在標記為 good first issue 的問題中需要一個佈局良好的計劃或步驟，這可以幫助新貢獻者快速上手。您可以將此任務的時間限制在 5-10 分鐘。

例如，作為分類者，您可以將以下資訊新增到您正在分類的問題中

To whoever fixes this issue, it looks like the following is needed:

- Update the first paragraph below heading X to correct the problem with Y
- Add a description of X
- Update the compatibility data at Link-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 標籤。