创建和处理问题

参与的一般准则

在报告问题或参与问题讨论时，请始终确保您的输入有助于项目的整体进展。请考虑您提出和评论的问题是否具有建设性和切中主题，而不仅仅是增加噪音。

请这样做

• 如果您有问题，可以在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 标签。