OpenSourceArk/mkdocs-material
1
0
Fork 0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-06-14 11:52:32 +03:00
Code Issues Packages Projects Releases Wiki Activity
268c5066ba
mkdocs-material/docs/contributing/index.md
katharinalisalin 268c5066ba Updated guides
2023-04-04 14:58:40 +02:00

8.5 KiB
Raw Blame History

Contributing

Material for MkDocs is an actively maintained and constantly improved project that serves a diverse user base with varying backgrounds and needs. In order to effectively address the needs of all our users, evaluate requests, and fix bugs, we maintainers need to put in a lot of work.

Our community is pretty big and includes many active users who open new discussions or issues multiple times a day, filling the issue tracker or the discussion board with a lot of valuable knowledge. As such, we consider our issue tracker and discussion board to be a knowledge base that is an important addition to our documentation, and brings value to both new and experienced users of Material for MkDocs.

How to contribute

We've invested time and effort into making our issue tracker and discussion board as user-friendly as possible. We understand that reporting bugs, requesting features, and engaging with our community can be challenging, so we've optimized our templates and added guidelines to improve all overall interaction within this project.

Our goal is to ensure that our platform is well-structured, easy to navigate, and searchable, so you can find what you need quickly and efficiently. We've also optimized our templates to help us understand your needs better, so we can provide you with faster and more effective support. In this documentation section, we'll give you an overview of each process and guide you to the detailed subpages.

Creating an issue

Contributing to this project

!!! warning "Issues, discussions, and comments are permanent"

Please note that everything you write is permanent and will remain 
for everyone to read in this project forever. Therefore, be nice, follow
our contribution guidelines, and comply with our Code of Conduct.

Before contributing

Before interacting within this project, please take a moment to consider the following questions. By doing so, you can ensure that you are using the correct issue template or provide all necessary information when interacting with the community:

Before submitting an issue, review:

  • Am I using the right issue template for my request, report, or contribution?
  • Have I checked if a similar issue or request has already been submitted?
  • Did I fill out every field as requested?
  • Did I provide all additional information others might need to comprehend my request?

Before asking a question, reconsider:

  • Is there an open discussion on the topic of my request?
  • Does my question fit the direction of the discussion, or should I open a new discussion?
  • Is my topic a question for the discussion boards, or is it a bug report or idea request that requires a new issue?
  • Did I provide the community with all the necessary information to comprehend my question?
  • Have I checked if my question has been answered before?

Before leaving a comment, rethink:

  • Is my comment directly related to the topic of this page, e.g., blog post or discussion?
  • Is it a comment or a request?
  • Should I use the discussion board for my request or comment instead?
  • Does my comment add value to the conversation?
  • Is my comment respectful and constructive?

Code of Conduct (CoC)

With a large community like ours, it's essential to follow the rules of our Code of Conduct and value the standards of acceptable behavior. Please take a moment to read through our Code of Conduct, which can always be found in full on our documentation. Please pay particular attention to our key values and keep them in mind when participating in any interactions within this project.

Our key values

:material-handshake: Treat the community and the maintainers with respect

:material-comment-text-multiple: Use welcoming, inclusive, and respectful language

:material-account-group: Embrace and understand different viewpoints and experiences

:material-checkbox-multiple-marked-circle: Accept decisions from the maintainers, even if things are not going your way

:material-heart-multiple: Focus on what's best for the community and show empathy towards other community members

Rights and responsibilities

As maintainers, we reserve the right and have the responsibility to close, remove, reject, or edit contributions, such as issues, comments, or commits, that do not align with our contribution guidelines and our Code of Conduct.

Incomplete issues

We have invested significant time in reviewing our contribution process and carefully assessed the information that is crucial to us when reviewing and responding to issues. Each field in our issue templates has been thoughtfully curated, requesting only the necessary information to understand your report or request. Therefore, it is mandatory for you to fill out every field as requested to the best of your knowledge without questioning the issue template. Trust us, we need this information because it ensures that every user and project maintainer, regardless of experience, can understand the content and severity of your report or request.

Please note that we reserve the right to close issues missing essential information, such as minimal reproductions, or that do not comply with the quality standards and requirements stated in the issue template. Issues can be reopened once the missing information has been provided.

CoC violations

As stated in our Code of Conduct, we expect all members of our community to treat each other with respect and use inclusive and welcoming language. We strive to create a positive and supportive environment and consider any inappropriate, threatening, offensive, or harmful behavior violating our Code of Conduct. We take such violations seriously and will take appropriate action in response.

Please note that we reserve the right and have the responsibility to remove, edit, or reject any contributions, including comments, commits, and issues, that violate our Code of Conduct. We may also temporarily or permanently ban users found to be violating of the CoC from contributing to or interacting in the project.