打开和处理问题的指南
参与的一般指南
在报告问题或参与问题中的对话时,请始终确保您的输入有助于项目的整体进展。考虑您打开的问题以及您在问题中的评论是否具有建设性且与主题相关,而不是仅仅增加噪音。
执行以下操作
- 在提交问题之前,请考虑您是否需要与工作人员/社区 讨论 问题。使用讨论来获得不同的观点,并就一致的行动方案达成共识。这有助于使问题保持专注和高效。
- 提交问题后,请尝试自行解决问题。阅读我们的 贡献指南 以了解更多信息。
- 如果您有疑问,可以在 MDN Web 文档聊天室 中提问,而不是提交问题。
避免执行以下操作
- 通过尝试讨论多个主题或发表与主题无关的评论来使问题复杂化。
- 打开大量问题,提出含糊不清的问题。
- 在尝试自行解决问题之前提出问题。
报告问题的指南
问题 用于跟踪错误。问题必须是一个单独的可操作任务或一组相关可操作任务,并且必须具有明确的结果。
在提交问题之前
如果您认为您发现了 MDN Web 文档内容或网站外观和感觉方面存在错误,请搜索 相关存储库 中当前的开放问题,并确保没有其他人报告过该问题。
报告问题
- 根据您发现的问题类型,通过在以下其中一个位置提交问题来报告问题
- 选择合适的类别来报告问题。例如,要报告内容错误,请使用 内容问题 模板在
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.
处理问题的指南
请记住,如果您承担了一个问题,则期望在合理的时间内完成工作。如果您在被分配后一周内无法取得任何进展,或者无法再完成所需的任务,请发表评论并从问题中取消分配自己。
以下是一般处理问题的步骤
- 查找问题:如果您想做出贡献,请搜索带有
good first issue
、help wanted
或p3
标签的问题。大多数存储库都有带有这些标签的问题。欢迎您浏览并选择适合您的技能集的问题。另一个查找要处理的问题的实用地方是 MDN 贡献者任务板。此项目视图列出了来自多个存储库的开放问题。您可以根据您感兴趣的主题(标签
列)过滤列表。查看在问题分类过程期间应用的一些 标签 的描述。注意:带有
needs triage
标签的问题表示 MDN Web 文档核心团队尚未审核该问题,您不应该开始处理它。 - 将问题分配给自己:找到您想处理的问题后,请确保该问题尚未分配给任何人。添加一条评论,说明您想处理该问题,如果可以,请 将问题分配给自己。
- 进行研究:大多数问题在开始工作之前都需要一些调查。
- 确定需要完成的工作范围。如果您需要提问,请在 MDN Web 文档聊天室 中提问。
- 如果问题描述清楚,并且工作很明显,请继续进行。
- 如果问题描述不清楚,或者您不确定需要什么,请随时 @提及发帖人并索取更多信息。
- 进行更改:分支和复制存储库。完成您的工作并在存储库中打开一个 拉取请求。在拉取请求描述中 引用该问题。根据您在拉取请求中更新的文件,将自动为您的拉取请求分配审核者。(每个主题区域的团队在 CODEOWNERS 文件中定义)。打开拉取请求后,如果您发现您不再有时间进行更改或合并审核反馈,请尽快在拉取请求中发表评论,告知团队。这将有助于团队为拉取请求分配另一个感兴趣的贡献者,以完成该工作并关闭链接的问题。
- 在您的拉取请求被审查并合并后,您可以将关联的issue标记为已关闭。如果您使用 `Fixes #
` 的措辞打开了拉取请求,则在拉取请求合并时,issue会自动关闭。
自行修复issue
如果您发现了一个bug,无论是网站外观和感觉的问题还是文档中的错误,您都可以尝试自行修复。通过阅读我们的贡献指南了解如何贡献。
如果bug很小,例如拼写错误或轻微的句子改进,或者涉及无争议的修复,请提交包含更改的拉取请求。
对于所有其他类型的bug,请先打开issue。添加关于您打算处理该issue的评论,如果可能,描述您提出的解决方案或修复该issue的步骤。等待issue被分类,以便MDN Web Docs团队可以验证issue是否合法并批准您的建议解决方案。
**注意:**如果您在issue被分类之前打开了一个拉取请求,那么如果关联的issue被认为无效或解决方案与MDN Web Docs团队期望的解决方案不匹配,那么您的时间和精力可能会浪费。在issue被分类后,将该issue分配给自己。
使用关于处理issue的指南,尝试通过更新适当的源代码来解决问题,例如
- MDN Web Docs内容(英文)在content库中
- MDN Web Docs翻译后的内容在translated-content库中
- MDN Web Docs网站外观和感觉在yari库中
每个库都包含有用的信息来指导您如何贡献。
对问题进行分类的指南
如果您是MDN Web Docs GitHub组织中的维护者或所有者,您负责对一个或多个MDN Web Docs库中的issue进行分类。
分类的整个过程包括一些常规任务和一些特定于issue的任务。
常规分类任务
- 当打开一个issue时,`needs triage`标签会自动设置在issue上。您可以搜索此标签以查找需要进行分类的issue。贡献者或其他任何人都不应该处理该issue,直到该issue被分类。(分类人员应该记住在对issue进行分类后删除`needs triage`标签。)
- 在mdn/content库中,会自动在issue上设置一个额外的`Content:`标签,例如`Content:CSS`或`Content:WebAPI`。这是根据issue中提到的MDN URL设置的。您可以使用内容特定的标签来查找您特定主题领域中需要分类的issue。
- 如果一个issue涉及一个活跃的非英文语言环境,请设置相应的标签,例如`l10n-fr`、`l10n-zh`或`l10n-ja`。这些语言环境的团队将接手这些issue并进行分类。
- 您无需始终积极地对issue进行分类。每周抽出时间,例如30分钟,定期对您负责的领域中的issue进行分类。分类不需要作为同步会议的一部分,甚至不需要与所有人同时进行,但应该定期进行,以确保未分类bug的积压量不会过高。
- 除了每周对传入的issue进行分类之外,还可以查看旧bug列表,看看是否有任何bug停滞不前、需要关闭或不再相关。`idle`标签会自动设置在30天内没有活动的issue上。
- 检查已分配的仍然处于打开状态的issue,看看分配者是否取得进展。如果分配一周后没有进展,请询问他们是否有时间继续处理该issue。如果再过一周仍然没有进展,请取消分配并留下评论,表明您正在让其他感兴趣的贡献者处理该issue。
- 如果一个拉取请求已被打开以修复该issue,但一周内没有被审查,请轻轻地提醒审查者,询问他们是否可以审查。
- 如果修复issue的拉取请求等待审查评论的解决,则一周后,请询问作者是否可以回复审查。如果再过一周,您可以根据情况自行修复审查评论,或者关闭拉取请求并取消分配相关的issue。
特定于issue的分类任务
这些是您在对每个issue进行分类时应遵循的指南。
检查issue是否有效
在检查issue的有效性时,请记住以下几点
- 检查提出的issue是否有效,以及修复是否会改善内容对读者和网站的价值。
- 评估修复的影响是小的还是全站范围的。
- 评估修复issue是否需要先进行讨论,如果是,请引导作者打开一个讨论。
- 检查issue是否符合我们的写作指南和模板。
- 检查添加链接的建议是否符合我们的外部链接策略。
检查issue的信息完整性
根据以下清单检查每个issue,以确保issue包含某人开始处理bug所需的信息
- 出现问题的MDN Web Docs页面的URL,或者如果问题存在于多个页面上,则提供示例MDN Web Docs页面的URL
- MDN Web Docs页面上发现问题的具体标题或部分
- 对不正确、无用、不完整或缺失信息的清晰描述
如果上述信息中的任何信息缺失,您应该要求issue的作者提供这些详细信息,并在issue中添加`needs info`标签。只有在提供这些详细信息后(之后,您可以删除`needs info`标签),才能继续对issue进行分类。等待作者最多一周的时间进行回复是可以的。
设置优先级标签
对于每个bug,请根据issue的严重程度设置优先级标签,以帮助希望处理最重要issue或领域的人。
- 严重问题:无论该问题出现在网站的哪个位置,都需要尽快解决。这类问题可能会严重损害MDN的声誉,或损害用户。这类问题的示例包括不正确的代码片段,如果在生产环境中使用,可能会造成严重的安全问题,以及不良内容,例如恶意软件、亵渎、色情内容、仇恨言论或指向此类内容的链接。
- 标签:`p0`(将立即解决)
- 主要问题:这类问题可能会严重影响页面的实用性。例如,大量的过时信息、复杂且重要的代码示例无法运行、大量的文字写得很差并且难以理解,或者大量的链接失效。
- 标签:`p1`(将很快解决)和`p2`(将很快解决,但优先级更高的项目将优先考虑)
- 次要问题:这是一种改进问题,可以使现有内容更好,但不会影响学习或只会对学习产生轻微影响。由于这些类型的issue没有积极地计划,因此欢迎并感谢贡献者提供帮助来修复这些issue。修复其中一些issue还可以为刚开始熟悉贡献流程的初级贡献者提供必要的实践。示例包括拼写错误、语法错误、失效的链接、少量过时信息或写得很差的文字,或者无法运行的代码片段。
- 标签:`p3`(issue解决的时间没有可见性)
一般来说,严重问题应该立即解决,最有可能由MDN Web Docs员工和同行处理。
添加有用信息
如果可能,请添加可以帮助贡献者修复issue的信息。这些信息可以以步骤、通用方法、指向其他类似已修复issue的链接或阅读资源的形式提供。对于标记为`good first issue`的issue,尤其需要详细的计划或步骤,这可以帮助新贡献者快速上手。您可以将此任务限定在5-10分钟内。
例如,作为分类人员,您可以将以下信息添加到您正在分类的issue中
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
:一些贡献者喜欢根据修复bug所需的时间和精力来搜索bug。因此,在可能的情况下,您应该尝试提供所需工作量的估计。good first issue
:如果issue的修复非常简单,并且修复issue可以为刚开始使用该流程的新人提供良好的实践,请在issue上设置此标签。help wanted
:如果issue需要了解或熟悉该主题的人员的帮助,请设置此标签。这是一个流行的标签,一些贡献者使用它来搜索他们熟悉或擅长的领域中开源项目中需要处理的issue。broken link external
:如果issue涉及指向外部页面的失效链接,请设置此标签。document not written
:如果issue涉及尚未编写但通常由于链接指向它而需要编写的文档,请设置此标签。needs content update
:如果另一个库中的issue修复需要在`mdn/content`库中进行等效的修复,请设置此标签。**注意:**在分类流程完成后,请删除`needs triage`标签。