mkdocs-material/docs/contributing/index.md

# 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

<div class="grid cards" markdown>

-   :material-bug:{ .lg .middle } __Something is not working?__

    ---

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

    [:octicons-arrow-right-24: Report a bug][report a bug]

-   :material-file-document:{ .lg .middle } __Missing information in our docs?__

    ---

    Report missing information or potential inconsistencies in our documentation

    [:octicons-arrow-right-24: Report a docs issue][report a docs issue]

-   :material-lightbulb-on:{ .lg .middle } __Want to submit an idea?__

    ---

    Propose a change, feature request, or suggest an improvement

    [:octicons-arrow-right-24: Request a change][request a change]

-   :material-chat-question:{ .lg .middle } __Have a question or need help?__

    ---

    Ask a question on our discussion board and get in touch with our community

    [:octicons-arrow-right-24: Ask a question][ask a question]

</div>

### Contributing to this project

<div class="grid cards" markdown>

-   :material-translate-variant:{ .lg .middle } __Missing support for your language?__

    ---

    Add missing translations for a new or supported language

    [:octicons-arrow-right-24: Add a translation](https://github.com/squidfunk/mkdocs-material/adding-a-translation)

-   :material-source-pull:{ .lg .middle } __Want to create a pull request?__

    ---

    Learn how to create a comprehensive pull request (PR)

    [:octicons-arrow-right-24: Create a pull request](https://github.com/squidfunk/mkdocs-material/creating-a-pull-request)

</div>

  [report a bug]: reporting-a-bug.md
  [report a docs issue]: reporting-a-docs-issue.md
  [request a change]: requesting-a-change.md
  [ask a question]: https://github.com/squidfunk/mkdocs-material/discussions

---

!!! 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?

 [request]: https://github.com/squidfunk/mkdocs-material/issues/new?assignees=&labels=&template=03-request-a-change.yml
 [report]: https://github.com/squidfunk/mkdocs-material/issues/new?assignees=&labels=&template=01-report-a-bug.yml
 [contribution]: https://github.com/squidfunk/mkdocs-material/issues/new?assignees=&labels=change+request&template=04-add-a-translation.yml&title=Add+translations+for+...

### 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.

  [discussion board]: https://github.com/squidfunk/mkdocs-material/discussions
  [issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
  [documentation]: https://squidfunk.github.io/mkdocs-material/
  [Code of Conduct]: https://github.com/squidfunk/mkdocs-material/blob/master/CODE_OF_CONDUCT.md