变更请求¶

Material for MkDocs 是一个强大的工具，用于创建美观且实用的文档。我们拥有超过 20,000 名用户，深知我们的项目服务于广泛的使用案例，因此我们创建了以下指南。

设身处地为我们考虑——对于这样一个规模的项目，维护现有功能的同时不断添加新特性可能会很具挑战性。我们非常重视来自社区的每一个想法或贡献，并恳请您在提交变更请求之前花时间阅读以下指南，以便我们更好地理解所提议的变更及其对社区的益处。

本指南是我们努力解释评估变更请求时的标准和理由的最佳尝试，并考虑它们的实施。

创建问题之前¶

在您投入时间填写并提交变更请求之前，我们恳请您先做一些初步工作，通过回答一些问题来确定您的想法是否适合 Material for MkDocs，并与项目的 理念 和语调相匹配。

请在创建问题之前完成以下事项。

这不是一个错误，这是一个特性¶

变更请求旨在建议小的调整、新特性的想法，或温和地影响项目的方向和愿景。重要的是要注意，变更请求并不用于报告错误，因为它们缺少调试所需的基本信息。

如果您想报告一个错误，请参考我们的 错误报告指南。

寻找灵感来源¶

如果您在其他静态网站生成器或主题中看到过您的想法被实现，请确保在提交之前收集足够的信息，以便我们能够更快地评估潜在的适配性。解释您喜欢和不喜欢该实现的地方。

与我们的社区联系¶

我们的 讨论区 是与社区联系的最佳场所。在评估新想法时，寻求其他用户的意见并考虑替代观点至关重要。这种方法有助于以有利于大量用户的方式实施新特性。

记录所有 搜索词 和 相关链接，您将在变更请求中需要它们。¹

  开始讨论

问题模板¶

现在您已经花时间完成必要的初步工作，并确保您的想法符合我们的要求，您可以创建变更请求。以下指南将引导您完成提交全面且有用的问题所需的所有步骤：

• 标题
• 背景 可选
• 描述
• 相关链接
• 使用案例
• 视觉效果 可选
• 检查清单

标题¶

一个好的标题简短且具有描述性。它应该是对想法的一句话执行摘要，以便可以从标题中推断出对我们社区的潜在影响和益处。

背景 可选¶

在描述您的想法之前，您可以提供额外的背景信息，以便我们理解您想要实现的目标。解释您使用 Material for MkDocs 的情况，以及您认为可能相关的内容。请不要在这里写关于变更请求的内容。

为什么这可能有帮助: 一些想法可能仅对特定设置、环境或边缘案例有益，例如，当您的文档包含数千个文档时。有了背景信息，变更请求的优先级可以更准确地评估。

描述¶

接下来，提供您想法的详细且清晰的描述。解释为什么您的想法与 Material for MkDocs 相关，并且必须在这里实施，而不是在其某个依赖项中：²

• 解释 什么，而不是 为什么 – 不要在这里解释 您想法的好处，我们会讨论这个。专注于尽可能准确地描述所提议的变更请求。

• 保持简短和简洁 – 描述您的想法时要简明扼要，无需过多描述。维护者和未来的用户会感激您减少阅读量。

• 一次一个想法 – 如果您有多个不相关的想法，请为每个想法单独打开变更请求。

扩展目标 – 如果您有自定义或其他方式来添加所提议的变更，您可以在我们维护者能够将其添加到代码库之前，先在这里与其他用户分享。

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

相关链接¶

请提供与您的变更请求相关的任何问题、讨论或文档部分的链接。如果您（或其他人）已经在我们的讨论区与社区讨论过这个想法，请包含该讨论的链接。

我们为什么需要这个: 相关链接通过提供额外的背景信息，帮助我们全面理解您的变更请求。此外，链接到之前的问题和讨论使我们能够快速评估社区已经提供的反馈和意见。

使用案例¶

解释您的变更请求将如何从作者和用户的角度工作——预期的影响是什么，为什么它不仅对您有益，对其他用户也有益？有多少用户会受益？此外，这是否可能破坏现有功能？

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

视觉效果 可选¶

我们现在有了您想法的清晰和详细的描述，包括其潜在使用案例的信息和相关链接的背景。如果您有任何视觉效果，例如草图、屏幕截图、模型或外部资产，您可以在此部分展示它们。

您可以将文件拖放到这里或包含外部资产的链接。

此外，如果您在其他静态网站生成器或主题中看到过这个变更、特性或改进，请通过展示它并描述其实现和整合方式来提供一个示例。

为什么这可能有帮助: 插图和视觉效果可以帮助我们维护者更好地理解和设想您的想法。屏幕截图、草图或模型可以提供额外的细节和清晰度，而单靠文本可能无法传达。此外，看到您的想法在其他项目中的实现方式可以帮助我们理解其在 Material for MkDocs 中的潜在影响和可行性，从而帮助我们维护者评估和分类变更请求。

检查清单¶

感谢您遵循指南并创建高质量的变更请求——您快完成了。检查清单确保您已阅读本指南，并尽力提供我们审查您在 Material for MkDocs 中的想法所需的每一条信息。

接下来我们会处理。

我们如何管理变更请求¶

变更请求作为问题提交到我们的公共 issue tracker。由于它们通常建议新特性或增强功能，因此我们以不同于错误报告的方式进行审核和管理。

为了保持清晰并确保我们的路线图保持专注和可实现性，我们引入了结构化的流程，并使用专门的 待办事项 来跟踪和组织变更请求，以及它们如何适应我们的路线图。

以下是我们处理新变更请求的方式：

1. 我们阅读并审核请求，以理解该想法。
2. 我们可能会留下评论以澄清意图或建议替代方案。
3. 如果该想法超出范围，我们将关闭请求并解释原因。
4. 如果该想法与项目愿景一致，我们将其分类为变更请求，并将其添加到我们的 待办事项 中。
5. 无论哪种情况，我们都会关闭请求，以保持问题跟踪器的整洁，并专注于未解决的错误。

注意：虽然问题可能被关闭，但这并不意味着它被遗忘——添加到项目板的变更请求仍然是我们长期规划的一部分。

这种方法的好处： - 用户可以更清晰、更快速地了解已知问题和错误，因为变更请求是单独管理的，从而更好地了解该项目的维护活跃程度。 - 相关想法在待办事项中分组，使我们能够更有效地跟踪进展，并更容易看到哪些变更请求是相关的。

被拒绝的请求¶

您的变更请求被拒绝了？我们对此感到抱歉。 我们理解当您的想法未被接受时可能会感到沮丧，但作为一个非常受欢迎项目的维护者，我们始终需要考虑整个社区的需求，有时不得不做出艰难的决定。

在评估变更请求时，我们始终必须考虑和平衡许多因素，并尽可能解释我们决策背后的理由。如果您不确定为什么您的变更请求被拒绝，请随时询问以获得澄清。

以下原则（无特定顺序）构成我们决策的基础：

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

但这并不是您想法的终点——您始终可以通过 自定义 自行实现它。如果您不确定如何做到这一点或想知道是否有人已经完成了，请随时与我们的社区联系。