变更请求¶

MkDocs材料是一个强大的工具，用于创建美观和功能 文档。拥有20000多名用户，我们了解我们的项目 服务于广泛的用例，这就是为什么我们创建了以下内容 导游。

设身处地为我们着想——对于如此规模的项目，这可能是一个挑战 在保持现有功能的同时，不断添加新功能 同时。我们高度重视社区的每一个想法或贡献，以及 我们恳请您在之前花时间阅读以下指南 在我们的公共[问题跟踪器]中提交您的更改请求。这将有助于我们 更好地了解拟议的变更以及它将如何使我们的社区受益。

本指南是我们为解释我们的标准和推理所做的最大努力 评估变更请求并考虑变更请求时的决策 实施。

在创建问题之前¶

在您投入时间填写和提交变更请求之前，我们敬请 请你通过回答一些问题来做一些初步工作，以确定 你的想法非常适合MkDocs材料，与项目相匹配 [哲学]和语气。

在创建问题之前，请执行以下操作。

这不是bug，这是一个特性¶

变更请求旨在建议进行细微调整，提出新的想法 或者善意地影响项目的方向和愿景。它是 需要注意的是，更改请求不是为了报告错误，因为 它们缺少调试所需的重要信息。

如果您想报告错误，请参阅我们的[错误报告指南]。

寻找灵感来源¶

如果你已经看到你的想法在另一个静态站点生成器中实现，或者 主题，确保在实施之前收集足够的信息 提交，因为这使我们能够更快地评估潜在的契合度。解释 你喜欢和不喜欢这个实现。

与我们的社区联系¶

我们的[讨论板]是与社区联系的最佳场所。什么时候？ 在评估新想法时，必须征求其他用户的意见并加以考虑 另一种观点。这种方法有助于以某种方式实现新功能 这使大量用户受益。

Keep track of all search terms and relevant links, you'll need them in the change request.¹

  Start a discussion

问题模板¶

现在你已经花时间做了必要的准备工作，并确保 如果您的想法符合我们的要求，我们邀请您进行更改 请求。以下指南将引导您完成所有必要的步骤 帮助您提交一个全面而有用的问题：

• Title
• Context optional
• Description
• Related links
• Use cases
• Visuals optional
• Checklist

名称¶

一个好的标题应当简短且富有描述性。它应该是一句话的执行 对想法进行总结，以便为我们的社区带来潜在的影响和利益 从标题中可以推断出来。

Context optional¶

在描述你的想法之前，你可以为我们提供额外的背景信息 了解你想要实现什么。解释情况 您在其中使用MkDocs的Material，以及您的想法可能是什么 相关。不要在这里写更改请求。

为什么这可能有帮助: 有些想法可能只对特定的人有益 设置、环境或边缘情况，例如，当您的文档 包含数千个文档。有一点上下文，更改请求 可以更准确地确定优先级。

描述¶

接下来，详细而清晰地描述你的想法。解释为什么你 这个想法与MkDocs的材料有关，必须在这里实施，而不是 在其依赖关系之一中：²

• Explain the what, not the why – 不要解释 [你的想法的好处][用例]在这里，我们正在实现。 专注于尽可能准确地描述拟议的变更请求。

• Keep it short and concise – 描述时要简明扼要 你的想法，没有必要过度描述。维护者和未来 用户会感激不得不少读书。

• One idea at a time – 如果你有多个不属于你的想法 请一起为每个想法单独提出更改请求。

Stretch goal – 如果你有定制或其他 要添加建议的更改，您可以通过在此处共享来帮助其他用户 在我们维护人员将其添加到我们的代码库之前。

为什么我们需要这个: 为了了解和评估您提出的变更，我们 需要清楚地了解你的想法。通过提供详细和 精确的描述，可以帮助您和我们节省讨论时间 在评论中进一步澄清你的想法。

相关链接¶

请提供问题、讨论或文档的相关链接 与您的更改请求相关的部分。如果你（或其他人）已经 在我们的讨论板上与我们的社区讨论了这个想法，请包括 与讨论的链接也是如此。

为什么我们需要这个: 相关链接帮助我们获得全面 通过提供额外的上下文来理解您的变更请求。 此外，链接到以前的问题和讨论可以让我们 快速评估我们社区已经提供的反馈和意见。

用例¶

解释作者和用户的更改请求将如何处理 观点——预期的影响是什么，为什么它不仅对你有益， 但其他用户呢？他们有多少人？此外，它是否有可能破裂 现有功能？

为什么我们需要这个: 了解一个想法的用例和好处是 对于评估其对项目的潜在影响和有用性至关重要，以及 其用户。这些信息有助于我们了解 以及它如何与项目目标保持一致。

Visuals optional¶

我们现在对你的想法有了清晰详细的描述，包括信息 关于其潜在用例和上下文相关链接。如果你有 视觉效果，如草图、截图、模型或外部资产，您可以 在本节中介绍它们。

您可以将文件拖放到此处，也可以包含指向外部资源的链接。

此外，如果您在 其他静态网站生成器或主题，请通过展示来提供示例 并描述了它是如何实现和整合的。

为什么这可能有帮助: 插图和视觉效果可以帮助我们 维护人员更好地理解和设想你的想法。截图、草图、， 或者模型可以为文本创造额外的细节和清晰度 单独可能无法传达。另外，看看你的想法怎么样 在其他项目中实施可以帮助我们了解其潜在影响和 MkDocs材料的可行性，这有助于我们的维护人员评估和 对变更请求进行分类。

清单¶

感谢您遵循指南并创建高质量的变更请求——您 几乎完成了。检查表确保您已阅读本指南并 尽您所能为我们提供每一条信息 回顾一下你对MkDocs材料的想法。

我们从这里开始。

我们如何管理变更请求¶

变更请求作为问题提交到我们的公共[问题跟踪器]上。自从 他们经常提出新的功能或增强功能，我们会对其进行审查和管理 与bug报告不同。

为了保持清晰，确保我们的路线图保持重点突出且可实现， 我们引入了一个结构化的流程，并使用了一个专用的[待办事项列表] 跟踪和组织变更请求，以及它们如何融入我们的路线图。

以下是我们如何处理新的变更请求：

1. 我们阅读并审查了请求，以了解这个想法。
2. 我们可能会发表评论以澄清意图或提出替代方案。
3. 如果想法超出范围，我们将关闭请求并解释原因。
4. 如果这个想法与项目的愿景相一致，我们将把它归类为一种变化 请求，并将其添加到我们的[待办事项列表]中。
5. 在任何一种情况下，我们都会关闭请求以保持问题跟踪器的干净 专注于开放的bug。

注意：虽然问题可能已经解决，但这并不意味着它被遗忘了—— 添加到项目委员会的变更请求仍然是我们长期计划的一部分 规划。

这种方法的好处: - 随着变化，用户可以更清晰、更快地了解已知的问题和错误 请求是分开管理的，可以更好地了解这个项目的活跃程度 保持。 - 相关想法被分组在待办事项列表中，使我们能够更多地跟踪进度 并且更容易地看到哪些更改请求是相关的。

被拒绝的请求¶

您的更改请求被拒绝了吗？我们对此深感抱歉。 我们知道它可以 当你的想法没有被接受时，你会感到沮丧，但作为一个 非常受欢迎的项目，我们总是需要考虑整个项目的需求 社区，有时迫使我们做出艰难的决定。

在评估变化时，我们总是要考虑和平衡许多因素 我们会尽可能地解释我们的决定背后的原因。 如果您不确定更改请求被拒绝的原因，请不要犹豫 要求澄清。

以下原则（没有特别的顺序）构成了我们的基础 决定：

• 与项目的愿景和基调保持一致
• 与现有功能和插件的兼容性
• 与所有屏幕尺寸和浏览器兼容
• 实施和维护工作
• 对大多数用户有用
• 简单易用
• 可访问性

但这并不是你想法的终点——你总是可以自己实现它 通过[定制]。如果你不确定如何做到这一点，或者想知道 有人已经这样做了，请随时与我们的社区联系 [讨论板]。