Skip to content

贡献

¥Contributing

Material for MkDocs 是一个积极维护且不断发展的项目，服务于拥有不同背景和需求的多元化用户群体。为了高效地满足所有用户的需求、评估变更请求并修复错误，我们投入了大量精力。

¥Material for MkDocs is an actively maintained and constantly evolving project serving a diverse user base with versatile backgrounds and needs. In order to efficiently address the requirements of all our users, evaluate change requests, and fix bugs, we put in a lot of work.

我们不断壮大的社区包括许多活跃用户，他们每天多次提出新问题和进行讨论，将我们的问题跟踪器和讨论板发展成为知识库 - 这是我们文档的重要补充 - 为新用户和有经验的用户带来价值。

¥Our ever-growing community includes many active users, who open new issues and discussions several times a day, evolving our issue tracker and discussion board into a knowledge base – an important addition to our documentation – yielding value to both new and experienced users.

如何贡献

¥How you can contribute

我们深知报告错误、提出变更请求以及参与讨论可能非常耗时，因此我们精心优化了问题模板并制定了指南，以提升项目的整体互动体验。我们投入了大量的时间和精力，致力于使问题跟踪器和讨论区尽可能高效。

¥We understand that reporting bugs, raising change requests, as well as engaging in discussions can be time-consuming, which is why we've carefully optimized our issue templates and defined guidelines to improve the overall interaction within the project. We've invested a lot of time and effort into making our issue tracker and discussion board as efficient as possible.

我们的目标是确保我们的文档、问题跟踪器和讨论区结构合理、易于浏览且易于搜索，以便您快速高效地找到所需内容。因此，如果您遵循我们的指南，我们可以更快地为您提供帮助。

¥Our goal is to ensure that our documentation, as well as issue tracker and discussion board, are well-structured, easy to navigate, and searchable, so you can find what you need quickly and efficiently. Thus, when you follow our guidelines, we can help you much faster.

在本节中，我们将指导您完成我们的流程。

¥In this section, we guide your through our processes.

创建问题

¥Creating an issue

贡献

¥Contributing

  • 缺少对您所用语言的支持？添加或改进新语言或已支持语言的翻译添加翻译

  • 想要创建拉取请求？学习如何创建全面实用的拉取请求 (PR)创建拉取请求

清单

¥Checklist

在项目内进行互动之前，请花点时间思考以下问题。这样做可以确保您使用了正确的问题模板，并在与我们的社区互动时提供了所有必要的信息。

¥   Something is not working?

问题、讨论和评论永远存在

¥Report a bug in Material for MkDocs by creating an issue with a reproduction

请注意，您所写的所有内容都将永久保留，供所有人阅读——永远如此。因此，请始终保持友善和建设性，遵循我们的贡献指南，并遵守我们的行为准则。

¥ Report a bug

在创建问题之前

¥Before creating an issue

  • 您是否使用了适当的问题模板，或者是否有其他更适合您的请求内容的问题模板？

  • 您是否检查过是否已经创建了类似的错误报告或变更请求，或者您是否偶然发现了可能相关的内容？

  • 您是否按照要求填写了每个字段，并且是否提供了我们维护人员理解您的请求所需的所有其他信息？

在提问之前

¥Before asking a question

  • 该主题是我们讨论板上的问题吗？还是应该在我们的问题跟踪器上提出的错误报告或变更请求？

  • 你的请求主题是否有公开讨论？如果答案是肯定的，你的问题是否符合讨论的方向？或者你应该另开一个讨论？

  • 您是否向我们的社区提供了所有必要的信息，以便我们了解您的问题并快速为您提供帮助，或者您是否可以更轻松地为您提供帮助？

在发表评论之前

¥Before commenting

  • 您的评论是否与当前页面、帖子、问题或讨论的主题相关，或者创建新问题或讨论是否更好？

  • 您的评论对讨论有价值吗？它是否具有建设性，并且尊重我们的社区和维护者？您可以直接回复吗？

权利和责任

¥Rights and responsibilities

作为维护者，我们肩负着规范社区内部沟通的责任，包括关闭、移除、拒绝或编辑问题、讨论、评论、提交，以及屏蔽不符合我们贡献指南和行为准则的用户的权限。这一职责要求我们积极参与维护社区的诚信和积极氛围。坚持这些标准，能够确保所有成员都能享受到尊重和包容的环境。

¥   Missing information in our docs?

行为守则

¥Code of Conduct

我们的行为准则概述了我们对所有社区成员的期望，即彼此尊重，使用包容和友好的语言。我们致力于营造积极互助的环境，杜绝不当、冒犯或有害的行为。

¥Report missing information or potential inconsistencies in our documentation

我们严肃对待任何违规行为，并将采取适当行动来维护这些价值观。1

¥ Report a docs issue

不完整的问题和重复问题

¥Incomplete issues and duplicates

我们在构建贡献流程方面投入了大量的时间和精力，以确保我们能够评估有效审核和响应问题的基本要求。问题模板中的每个字段都经过精心设计，以帮助我们充分了解您的顾虑和问题的性质。我们鼓励所有成员在提交新问题或开始讨论之前使用搜索功能，以避免重复提交。您的合作对于确保我们社区的讨论富有建设性和条理性至关重要。

¥   Want to submit an idea?

  • 强制完成问题模板：我们需要问题模板中所需的所有信息，因为它可以确保每个用户和维护人员，无论他们的经验如何，都能理解您的错误报告或变更请求的内容和严重性。

  • 关闭不完整问题：我们保留关闭缺少必要信息的问题的权利，例如（但不限于）极少的复制品或不符合问题模板中规定的质量标准和要求的问题。在提供缺失信息后，可以重新打开此类问题。

  • 处理重复问题：为了在我们的问题跟踪器和讨论板内保持有序高效的沟通，我们保留关闭任何重复问题或锁定重复讨论的权利。在不同的论坛上开设多个渠道询问同一问题或报告同一问题会妨碍我们有效地管理和解决社区问题。这种方法对于有效的时间管理至关重要，因为重复的问题会同时耗费多名团队成员的时间。确保每个问题或讨论都是独一无二的并且随着新信息的出现而进展，有助于我们保持专注并支持我们的社区。我们还保留立即关闭未提供新信息或仅仅因为用户尚未收到对其问题/疑问的答复而重新开启的讨论或问题的权利，因为该问题被标记为不完整。

  • 自动化工具的局限性：虽然我们相信自动化工具在识别潜在问题（例如 Lighthouse、辅助功能工具等工具识别的问题）方面的价值和效率，但仅仅提交这些工具生成的问题并不构成完整的错误报告。这些工具有时会生成冗长的输出，并且可能包含误报，因此需要进行严格的评估。当然，欢迎您将生成的报告附加到您的问题中。但是，这并不能取代对结果进行最小化复现或进行全面讨论的要求。我们保留将这些问题标记为不完整并关闭的权利。这种做法确保我们能够准确、清晰地解决真正的问题，而不是在繁琐的自动化输出中摸索前进。

  1. 警告和屏蔽政策：鉴于我们项目日益增长的受欢迎程度以及我们对维护健康社区的承诺，我们制定了明确的违规处理准则：1.1.首次警告：反复出现不当、冒犯或有害行为的用户将收到首次警告。此警告正式通知用户其行为不符合我们的社区标准和行为准则。首次警告是永久性的。1.2.第二次警告和解决机会：如果该行为持续存在，我们将发出第二次警告。收到第二次警告后，用户将有5天的反思期，鼓励其公开解释或为其行为道歉。这段时间旨在提供一个公开澄清任何误解的机会。1.3.屏蔽：如果在第二次警告后用户仍未得到回应或行为改善，我们保留将该用户屏蔽在社区和代码库中的权利。屏蔽被视为最后手段，仅在绝对必要时使用，以维护社区的完整性和积极的氛围。在我们极其积极的社区中，屏蔽是极其罕见的必要行为，这凸显了我们重视建设性对话和相互尊重。这样做的目的是保护我们的社区成员和团队。↩