Skip to content

变更请求

¥Change requests

Material for MkDocs 是一款功能强大的工具，可用于创建美观实用的文档。我们拥有超过 20,000 名用户，深知该项目能够满足各种用例的需求，因此我们创建了以下指南。

¥Material for MkDocs is a powerful tool for creating beautiful and functional documentation. With more than 20,000 users, we understand that our project serves a wide range of use cases, which is why we have created the following guide.

设身处地地为我们着想——对于如此规模的项目，在不断添加新功能的同时维护现有功能可能颇具挑战性。我们高度重视来自社区的每一个想法或贡献，并恳请您在向我们的公共问题跟踪器提交变更请求之前，花点时间阅读以下指南。这将帮助我们更好地理解拟议的变更及其将如何惠及社区。

¥Put yourself in our shoes – with a project of this size, it can be challenging to maintain existing functionality while constantly adding new features at the same time. We highly value every idea or contribution from our community, and we kindly ask you to take the time to read the following guidelines before submitting your change request in our public issue tracker. This will help us better understand the proposed change and how it will benefit our community.

本指南是我们尽力解释评估变更请求并考虑实施时我们做出的决策背后的标准和理由。

¥This guide is our best effort to explain the criteria and reasoning behind our decisions when evaluating change requests and considering them for implementation.

我们如何管理变更请求

¥How we manage change requests

在提交新想法之前，请花点时间阅读我们如何管理变更请求

¥Before submitting a new idea, please take a moment to read how we manage change requests

在创建问题之前

¥Before creating an issue

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

¥Before you invest your time to fill out and submit a change request, we kindly ask you to do some preliminary work by answering some questions to determine if your idea is a good fit for Material for MkDocs and matches the project's philosophy and tone.

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

¥Please do the following things before creating an issue.

这不是一个错误，而是一个功能

¥It's not a bug, it's a feature

变更请求旨在提出细微调整、新功能构想，或善意地影响项目的方向和愿景。需要注意的是，变更请求不适用于报告错误，因为它们缺少调试所需的必要信息。

¥Change requests are intended to suggest minor adjustments, ideas for new features, or to kindly influence the project's direction and vision. It is important to note that change requests are not intended for reporting bugs, as they're missing essential information for debugging.

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

¥If you want to report a bug, please refer to our bug reporting guide instead.

寻找灵感来源

¥Look for sources of inspiration

如果您的想法已在其他静态网站生成器或主题中实现，请务必在提交前收集足够的相关信息，以便我们更快地评估潜在的匹配度。请说明您对该实现的满意之处和不满之处。

¥If you have seen your idea implemented in another static site generator or theme, make sure to collect enough information on its implementation before submitting, as this allows us to evaluate potential fit more quickly. Explain what you like and dislike about the implementation.

与我们的社区联系

¥Connect with our community

我们的讨论区是与社区沟通的最佳平台。评估新想法时，务必征求其他用户的意见并考虑不同的观点。这种方法有助于以惠及广大用户的方式实现新功能。

¥Our discussion board is the best place to connect with our community. When evaluating new ideas, it's essential to seek input from other users and consider alternative viewpoints. This approach helps to implement new features in a way that benefits a large number of users.

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

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

开始讨论

¥  Start a discussion

问题模板

¥Issue template

既然您已花时间完成必要的前期工作，并确保您的想法符合我们的要求，我们诚邀您创建变更请求。以下指南将引导您完成所有必要步骤，以帮助您提交全面且实用的问题：

¥Now that you have taken the time to do the necessary preliminary work and ensure that your idea meets our requirements, you are invited to create a change request. The following guide will walk you through all the necessary steps to help you submit a comprehensive and useful issue:

标题

¥Title

好的标题应该简短且具有描述性。它应该用一句话概括该想法，以便从标题中推断出它对社区的潜在影响和益处。

¥A good title is short and descriptive. It should be a one-sentence executive summary of the idea, so the potential impact and benefit for our community can be inferred from the title.

例子

¥Example

清除

¥ Clear

在搜索中索引自定义前置内容

¥Index custom front matter in search

罗嗦

¥ Wordy

添加一个功能，允许作者定义自定义封面内容以便在搜索中被索引

¥Add a feature where authors can define custom front matter to be indexed in search

不清楚

¥ Unclear

改进搜索

¥Improve search

无用

¥ Useless

帮助

¥Help

上下文可选

¥Context optional

在描述您的想法之前，您可以提供一些额外的背景信息，以便我们了解您想要实现的目标。请解释您使用 Material for MkDocs 的具体情况，以及您认为可能相关的内容。请勿在此处撰写变更请求。

¥Before describing your idea, you can provide additional context for us to understand what you are trying to achieve. Explain the circumstances in which you're using Material for MkDocs, and what you think might be relevant. Don't write about the change request here.

为什么这可能有用：有些想法可能只适用于特定的设置、环境或特殊情况，例如，当你的文档包含数千个文档时。通过一些背景信息，可以更准确地确定变更请求的优先级。

¥

Why this might be helpful: some ideas might only benefit specific settings, environments, or edge cases, for example, when your documentation contains thousands of documents. With a little context, change requests can be prioritized more accurately.

描述

¥Description

接下来，请详细清晰地描述你的想法。解释为什么你的想法与 Material for MkDocs 相关，并且必须在这里实现，而不是在其依赖项中实现：2

¥Why this might be helpful: some ideas might only benefit specific settings, environments, or edge cases, for example, when your documentation contains thousands of documents. With a little context, change requests can be prioritized more accurately.

  • 解释“是什么”，而不是“为什么” ——不要在这里解释你的想法的好处，我们正要开始讨论。重点是尽可能准确地描述拟议的变更请求。

  • 保持简洁明了——描述你的想法时，要简洁明了，无需过多描述。维护者和未来的用户会感激你阅读的更少内容。

  • 一次一个想法- 如果您有多个不属于一起的想法，请为每个想法打开单独的变更请求。

延伸目标——如果您有自定义或其他方式来添加建议的更改，您可以在维护人员将其添加到我们的代码库之前在此处分享它以帮助其他用户。

¥Next, provide a detailed and clear description of your idea. Explain why your idea is relevant to Material for MkDocs and must be implemented here and not in one of its dependencies:2

我们为什么需要这样做：为了理解和评估您提出的变更，我们需要清晰地理解您的想法。提供详细而准确的描述，可以节省您和我们在评论区进一步讨论和澄清您想法的时间。

¥

Why we need this: To understand and evaluate your proposed change, we need to have a clear understanding of your idea. By providing a detailed and precise description, you can help save you and us time spent discussing further clarification of your idea in the comments.

¥Related links

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

¥Explain the what, not the why – don't explain the benefits of your idea here, we're getting there. Focus on describing the proposed change request as precisely as possible.

为什么我们需要它：相关链接可以通过提供更多背景信息帮助我们全面了解您的变更请求。此外，链接到之前的问题和讨论，可以让我们快速评估社区提供的反馈和意见。

¥

Why we need this: Related links help us gain a comprehensive understanding of your change request by providing additional context. Additionally, linking to previous issues and discussions allows us to quickly evaluate the feedback and input already provided by our community.

用例

¥Use cases

从作者和用户的角度解释一下你的变更请求将如何运作——预期的影响是什么？为什么它不仅对你有利，还会惠及其他用户？有多少用户？此外，它是否会破坏现有功能？

¥Keep it short and concise – be brief and to the point when describing your idea, there is no need to over-describe it. Maintainers and future users will be grateful for having to read less.

为什么我们需要这样做：了解一个想法的用例和优势，对于评估其对项目及其用户的潜在影响和实用性至关重要。这些信息有助于我们了解该想法的预期价值，以及它如何与项目目标保持一致。

¥

Why we need this: Understanding the use cases and benefits of an idea is crucial in evaluating its potential impact and usefulness for the project and its users. This information helps us to understand the expected value of the idea and how it aligns with the goals of the project.

视觉效果可选

¥Visuals optional

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

¥One idea at a time – if you have multiple ideas that don't belong together, please open separate change requests for each of those ideas.

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

¥ Stretch goal – if you have a customization or another way to add the proposed change, you can help other users by sharing it here before we maintainers can add it to our code base.

此外，如果您看到其他静态站点生成器或主题中使用了此更改、功能或改进，请提供一个示例来展示它并描述它是如何实现和合并的。

¥Why we need this: To understand and evaluate your proposed change, we need to have a clear understanding of your idea. By providing a detailed and precise description, you can help save you and us time spent discussing further clarification of your idea in the comments.

为什么这可能有帮助：插图和视觉效果可以帮助我们维护人员更好地理解和设想您的想法。屏幕截图、草图或模型可以创建额外的细节和清晰度，而单靠文字可能无法传达这些细节和清晰度。此外，了解您的想法在其他项目中的实施情况，可以帮助我们了解其在 Material for MkDocs 中的潜在影响和可行性，这有助于我们维护人员评估和分类变更请求。

¥

Why this might be helpful: Illustrations and visuals can help us maintainers better understand and envision your idea. Screenshots, sketches, or mockups can create an additional level of detail and clarity that text alone may not be able to convey. Also, seeing how your idea has been implemented in other projects can help us understand its potential impact and feasibility in Material for MkDocs, which helps us maintainers evaluate and triage change requests.

清单

¥Checklist

感谢您遵循指南并创建高质量的变更请求——您即将完成。这份清单确保您已阅读本指南，并已尽最大努力向我们提供所有信息，以便我们审核您对 Material for MkDocs 的构想。

¥Please provide any relevant links to issues, discussions, or documentation sections related to your change request. If you (or someone else) already discussed this idea with our community on our discussion board, please include the link to the discussion as well.

我们就从这里开始。

¥Why we need this: Related links help us gain a comprehensive understanding of your change request by providing additional context. Additionally, linking to previous issues and discussions allows us to quickly evaluate the feedback and input already provided by our community.

我们如何管理变更请求

¥How we manage change requests

变更请求会以问题的形式提交到我们的公共问题跟踪器中。由于变更请求通常涉及新功能或增强功能，因此我们采用与错误报告不同的方式审核和管理它们。

¥Explain how your change request would work from an author's and user's perspective – what's the expected impact, and why does it not only benefit you, but other users? How many of them? Furthermore, would it potentially break existing functionality?

为了保持清晰度并确保我们的路线图保持重点和可实现性，我们引入了结构化流程并使用专用积压来跟踪和组织变更请求，以及它们如何融入我们的路线图。

¥Why we need this: Understanding the use cases and benefits of an idea is crucial in evaluating its potential impact and usefulness for the project and its users. This information helps us to understand the expected value of the idea and how it aligns with the goals of the project.

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

¥We now have a clear and detailed description of your idea, including information on its potential use cases and relevant links for context. If you have any visuals, such as sketches, screenshots, mockups, or external assets, you may present them in this section.

  1. 我们阅读并审查了请求以了解这个想法。

    ¥We read and review the request to understand the idea.

  2. 我们可能会留下评论来澄清意图或提出替代方案。

    ¥We may leave comments to clarify intent or suggest alternatives.

  3. 如果该想法超出范围，我们将关闭请求并解释原因。

    ¥If the idea is out of scope, we will close the request and explain why.

  4. 如果该想法与项目愿景一致，我们将把它归类为变更请求，并将其添加到我们的待办事项中。

    ¥If the idea aligns with the project's vision, we'll categorize it as a change request, and add it to our backlog.

  5. 无论哪种情况，我们都会关闭请求，以保持问题跟踪器的清洁并专注于未解决的错误。

    ¥In either case, we close the request to keep the issue tracker clean and focused on open bugs.

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

¥

Note: While the issue may be closed, that doesn't mean it's forgotten – change requests added to the project board remain part of our long-term planning.

这种方法的好处： - 由于变更请求是单独管理的，因此用户可以更清晰、更快地了解已知问题和错误，从而更好地了解该项目维护的积极性。 - 相关想法在积压工作中分组，使我们能够更有效地跟踪进度，并更容易地看到哪些变更请求是相关的。

¥You can drag and drop the files here or include links to external assets.

被拒绝的请求

¥Rejected requests

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

¥Additionally, if you have seen this change, feature, or improvement used in other static site generators or themes, please provide an example by showcasing it and describing how it was implemented and incorporated.

在评估变更请求时，我们始终需要考虑并权衡诸多因素，并会尽可能解释我们做出决定的理由。如果您不确定变更请求被拒绝的原因，请随时寻求帮助。

¥Why this might be helpful: Illustrations and visuals can help us maintainers better understand and envision your idea. Screenshots, sketches, or mockups can create an additional level of detail and clarity that text alone may not be able to convey. Also, seeing how your idea has been implemented in other projects can help us understand its potential impact and feasibility in Material for MkDocs, which helps us maintainers evaluate and triage change requests.

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

¥Thanks for following the guide and creating a high-quality change request – you are almost done. The checklist ensures that you have read this guide and have worked to your best knowledge to provide us with every piece of information to review your idea for Material for MkDocs.

  • 与项目愿景和基调保持一致

  • 与现有功能和插件的兼容性

  • 兼容所有屏幕尺寸和浏览器

  • 实施和维护工作量

  • 对大多数用户有用

  • 简单易用

  • 无障碍设施

但这并不是您想法的终点——您随时可以通过定制来实现它。如果您不确定如何操作，或者想知道是否有人已经这样做过，欢迎随时在讨论区联系我们的社区。

¥We'll take it from here.

  1. 我们文档中使用的术语可能与您的不同，但我们的意思是一样的。如果您在变更请求中包含搜索词和相关链接，将有助于我们调整和改进文档。↩

  2. 有时，用户会在我们的问题跟踪器上提出一些与我们的上游依赖项（包括MkDocs 、 Python Markdown 、 Python Markdown 扩展或第三方插件）相关的建议。建议您考虑一下您的想法是否对其他主题有益，并将变更请求提交到上游以产生更大的影响。↩