asc/cmba-bylaws
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 3 Wiki Activity

Add AI documentation skills

Browse Source
This commit is contained in:
Anthony Correa
2026-04-25 09:08:55 -05:00
parent 100a4d5419
commit 9d15ab56c6
255 changed files with 68574 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

125
.ai/skills/mkdocs/references/upstream/mkdocs-material-9.7.1-docs/contributing/adding-translations.md Normal file
View File

@@ -0,0 +1,125 @@
# Translations
It's unbelievable – with the help of international community contributions,
Material for MkDocs has been translated into 60+ languages. As you can imagine,
it's impossible for us maintainers to keep all languages up-to-date, and new
features sometimes require new translations.
If you would like to help us to make Material for MkDocs even more globally
accessible and have noticed a missing translation in your language, or would
like to add a new language, you can help us by following the steps of the guide
below.
## Before creating an issue
Translations change frequently, which is why we want to make sure that you don't
invest your time in duplicating work. Before adding translations, please check
the following things:
### Check language availability
With more than 60 languages, the chances are good that your language is already
supported by Material for MkDocs. You can check if your language is available,
or needs improvements or additional translations by inspecting the list of
[supported languages]:
- __Your language is already supported__ – in this case, you can check if there
are translations missing, and click the link underneath your language to add them, which takes 5 minutes.
- __Your language is missing__ – in that case, you can help us add support
for your language to Material for MkDocs! Read on, to learn how to do this.
[supported languages]: ../setup/changing-the-language.md#site-language
### Search our issue tracker
Another user might have already created an issue supplying the missing
translations for your language that still needs to be integrated by us
maintainers. To avoid investing your time in duplicated work, please search the
[issue tracker] beforehand.
[issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
---
At this point, when you have made sure that Material for MkDocs doesn't already
support your language, you can add new translations for it by following the
issue template.
## Issue template
We have created an issue template that makes contributing translations as simple
as possible. It is the result of our experience with 60+ language contributions
and updates over the last couple of years, and consists of the following parts:
- [Title]
- [Translations]
- [Country flag] <small>optional</small>
- [Checklist]
[Title]: #title
[Translations]: #translations
[Country flag]: #country-flag
[Checklist]: #checklist
### Title
When you update an already existing language, you can just leave the title as it
is. Adding support for a new language, replace the `...` in the pre-filled title
with the name of your language.
| <!-- --> | Example |
| -------- | -------- |
| :material-check:{ style="color: #4DB6AC" } __Clear__ | Add translations for German
| :material-close:{ style="color: #EF5350" } __Unclear__ | Add translations ...
| :material-close:{ style="color: #EF5350" } __Useless__ | Help
### Translations
If a translation contains an :arrow_left: icon on the right side, it is missing.
You can translate this line and remove the :arrow_left: icon. If you don't know
how to translate specific lines, simply leave them for other contributors to
complete. To ensure the accuracy of your translation, consider double-checking the
context of the words by looking at our [English translations].
[English translations]: https://github.com/squidfunk/mkdocs-material/tree/master/src/templates/partials/languages/en.html
### Country flag <small>optional</small> { #country-flag }
For a better overview, our list of [supported languages] includes country flags
next to the language names. You can help us select a flag for your language by
adding the shortcode for the country flag to this field. Go to our
[emoji search] and enter `flag` to find all available shortcodes.
!!! question "What if my flag is not available?"
[Twemoji] provides flag emojis for 260 countries – subdivisions of countries,
such as states, provinces, or regions, are not supported. If you're adding
translations for a subdivision, please choose the most appropriate available
flag.
[Twemoji]: https://github.com/jdecked/twemoji
[emoji search]: ../reference/icons-emojis.md#search
> __Why this might be helpful__: adding a country flag next to the country name
> can be helpful for you and for others to find the language in the list of
> supported languages faster and easier. If your country's flag is not supported
> by [Twemoji], you can help us choose an alternative.
### Checklist
Thanks for following the guide and helping us to add new translations to Material
for MkDocs – you are almost done. The checklist ensures that you have read this
guide and have worked to your best knowledge to provide us with everything we need
to integrate your contribution.
__We'll take it from here.__
---
## Attribution
If you submit a translation using the template above, you will be __credited as
a co-author__ in the commit, so you don't need to open a pull request. You have
done a significant contribution to the project, making Material for MkDocs
accessible to more people around the world. Thank you!

269
.ai/skills/mkdocs/references/upstream/mkdocs-material-9.7.1-docs/contributing/index.md Normal file
View File

@@ -0,0 +1,269 @@
# Contributing
Material for MkDocs is an actively maintained and constantly evolving project
serving a diverse user base with versatile backgrounds and needs. In order to
efficiently address the requirements of all our users, evaluate change requests,
and fix bugs, we put in a lot of work.
Our ever-growing community includes many active users, who open new
issues and discussions several times a day, evolving our [issue tracker] and
[discussion board] into a knowledge base – an important addition to
our [documentation] – yielding value to both new and experienced users.
[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/
## How you can contribute
We understand that reporting bugs, raising change requests, as well as engaging
in discussions can be time-consuming, which is why we've carefully optimized our
issue templates and defined guidelines to improve the overall interaction
within the project. We've invested a lot of time and effort into making our
[issue tracker] and [discussion board] as efficient as possible.
Our goal is to ensure that our documentation, as well as issue tracker and
discussion board, are __well-structured__, __easy to navigate__, and
__searchable__, so you can find what you need quickly and efficiently. Thus,
when you follow our guidelines, we can help you much faster.
In this section, we guide your through our processes.
### Creating an issue
<div class="grid cards" markdown>
- :material-bug-outline: &nbsp;
__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-remove-outline: &nbsp;
__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-20: &nbsp;
__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-account-question-outline: &nbsp;
__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][discussion board]
</div>
### Contributing
<div class="grid cards" markdown>
- :material-translate: &nbsp;
__Missing support for your language?__
---
Add or improve translations for a new or already supported language
---
[:octicons-arrow-right-24: Add translations][add translations]
- :material-source-pull: &nbsp;
__Want to create a pull request?__
---
Learn how to create a comprehensive and useful pull request (PR)
---
[:octicons-arrow-right-24: Create a pull request][create 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
[add translations]: adding-translations.md
[create a pull request]: making-a-pull-request.md
## Checklist
Before interacting within the project, please take a moment to consider the
following questions. By doing so, you can ensure that you are using the correct
issue template and that you provide all necessary information when interacting
with our community.
!!! warning "Issues, discussions, and comments are forever"
Please note that everything you write is permanent and will remain
for everyone to read – forever. Therefore, please always be nice and
constructive, follow our contribution guidelines, and comply with our
[Code of Conduct].
### Before creating an issue
- Are you using the appropriate issue template, or is there another issue
template that better fits the context of your request?
- Have you checked if a similar bug report or change request has already been
created, or have you stumbled upon something that might be related?
- Did your fill out every field as requested and did you provide all additional
information we maintainers need to comprehend your request?
### Before asking a question
- Is the topic a question for our [discussion board], or is it a bug report or
change request that should better be raised on our [issue tracker]?
- Is there an open discussion on the topic of your request? If the answer is yes,
does your question match the direction of the discussion, or should you open a
new discussion?
- Did your provide our community with all the necessary information to
understand your question and help you quickly, or can you make it easier to
help you?
### Before commenting
- Is your comment relevant to the topic of the current page, post, issue, or
discussion, or is it a better idea to create a new issue or discussion?
- Does your comment add value to the conversation? Is it constructive and
respectful to our community and us maintainers? Could you just use a
[:octicons-smiley-16: reaction][reaction] instead?
[Code of Conduct]: https://github.com/squidfunk/mkdocs-material/blob/master/CODE_OF_CONDUCT.md
[reaction]: https://github.blog/2016-03-10-add-reactions-to-pull-requests-issues-and-comments/
## Rights and responsibilities
As maintainers, we are entrusted with the __responsibility__ to moderate
communication within our community, including the authority to close, remove,
reject, or edit issues, discussions, comments, commits, and to block users who
__do not align__ with our contribution guidelines and our [Code of Conduct].
This role requires us to be actively involved in maintaining the integrity and
positive atmosphere of our community. Upholding these standards decisively
ensures a respectful and inclusive environment for all members.
### Code of Conduct
Our [Code of Conduct] outlines the expectation for all community members to
treat one another with respect, employing inclusive and welcoming language. Our
commitment is to foster a positive and supportive environment, free of
inappropriate, offensive, or harmful behavior.
We take any violations seriously and will take appropriate action in response to
uphold these values.[^1]
[^1]:
__Warning and blocking policy:__
Given the increasing popularity of our project and our commitment to a
healthy community, we've defined clear guidelines on how we proceed with
violations:
1.1. __First warning:__ Users displaying repeated inappropriate, offensive,
or harmful behavior will receive a first warning. This warning serves as a
formal notice that their behavior is not in alignment with our community
standards and Code of Conduct. The first warning is permanent.
1.2. __Second warning and opportunity for resolution:__ If the behavior
persists, a second warning will be issued. Upon receiving the second
warning, the user will be given a 5-day period for reflection, during which
they are encouraged to publicly explain or apologize for their actions.
This period is designed to offer an opportunity for openly clearing out any
misunderstanding.
1.3. __Blocking:__ Should there be no response or improvement in behavior
following the second warning, we reserve the right to block the user from
the community and repository. Blocking is considered a last resort, used
only when absolutely necessary to protect the community's integrity and
positive atmosphere.
Blocking has been an exceptionally rare necessity in our overwhelmingly
positive community, highlighting our preference for constructive dialogue
and mutual respect. It aims to protect our community members and team.
### Incomplete issues and duplicates
We have invested significant time and effort in the setup of our contribution
process, ensuring that we assess the essential requirements for reviewing and
responding to issues effectively. Each field in our issue templates is
thoughtfully designed to help us fully understand your concerns and the nature
of your matter. We encourage all members to utilize the search function before
submitting new issues or starting discussions to help avoid duplicates. Your
cooperation is crucial in keeping our community's discussions constructive and
organized.
- __Mandatory completion of issue templates:__ We need all of the information
required in our issue templates because it ensures that every user and
maintainer, regardless of their experience, can understand the content and
severity of your bug report or change request.
- __Closing incomplete issues:__
We _reserve the right to close issues lacking essential information_, such as
but not limited to [minimal reproductions] or those not adhering to the
quality standards and requirements specified in our issue templates. Such
issues can be reopened once the missing information has been provided.
- __Handling duplicates:__ To maintain organized and efficient
communication within our [issue tracker] and [discussion board], we
_reserve the right to close any duplicated issues or lock duplicated
discussions_. Opening multiple channels to ask the same question or report the
same issue across different forums hinders our ability to manage and address
community concerns effectively. This approach is vital for efficient time
management, as duplicated questions can consume the time of multiple team
members simultaneously. Ensuring that each issue or discussion is unique and
progresses with new information helps us to maintain focus and support our
community.
We further _reserve the right to immediately close discussions or issues that
are reopened without providing new information_ or simply because users have
not yet received a response to their issue/question, as the issue is marked as
incomplete.
- __Limitations of automated tools:__ While we believe in the value and
efficiency that automated tools bring to identifying potential issues (such
as those identified by Lighthouse, Accessibility tools, and others), simply
submitting an issue generated by these tools does not constitute a complete
bug report. These tools sometimes produce verbose outputs and may include
false positives, which necessitate a critical evaluation. You are of course
welcome to attach generated reports to your issue. However, this does not
substitute the requirement for a minimal reproduction or a thorough discussion
of the findings. _We reserve the right to mark these issues as incomplete and
close them._ This practice ensures that we are addressing genuine concerns
with precision and clarity, rather than navigating through extensive automated
outputs.
[minimal reproductions]: ../guides/creating-a-reproduction.md

402
.ai/skills/mkdocs/references/upstream/mkdocs-material-9.7.1-docs/contributing/making-a-pull-request.md Normal file
View File

@@ -0,0 +1,402 @@
# Pull Requests
You can contribute to Material for MkDocs by making a [pull request] that
will be reviewed by maintainers and integrated into the main repository when
the changes made are approved. You can contribute bug fixes, changes to the
documentation, or new functionality you have developed.
[pull request]: https://docs.github.com/en/pull-requests
!!! note "Considering a pull request"
Before deciding to spend effort on making changes and creating a pull
request, please discuss what you intend to do. If you are responding to
what you think might be a bug, please issue a [bug report] first. If you
intend to work on documentation, create a [documentation issue]. If you
want to work on a new feature, please create a [change request].
Keep in mind the guidance given and let people advise you. It might be that
there are easier solutions to the problem you perceive and want to address.
It might be that what you want to achieve can already be done by
configuration or [customization].
[bug report]: reporting-a-bug.md
[documentation issue]: reporting-a-docs-issue.md
[change request]: requesting-a-change.md
[customization]: ../customization.md
## Learning about pull requests
Pull requests are a concept layered on top of Git by services that provide Git
hosting. Before you consider making a pull request, you should familiarize
yourself with the documentation on GitHub, the service we are using. The
following articles are of particular importance:
1. [Forking a repository]
2. [Creating a pull request from a fork]
3. [Creating a pull request]
Note that they provide tailored documentation for different operating systems
and different ways of interacting with GitHub. We do our best in the
documentation here to describe the process as it applies to Material for MkDocs
but cannot cover all possible combinations of tools and ways of doing things.
It is also important that you understand the concept of a pull-request in
general before continuing.
[Forking a repository]: https://docs.github.com/en/get-started/quickstart/fork-a-repo
[Creating a pull request from a fork]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork
[Creating a pull request]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request
## Pull request process
In the following, we describe the general process for making pull requests. The
aim here is to provide the 30k ft overview before describing details later on.
### Preparing changes and draft PR
The diagram below describes what typically happens to repositories in the
process or preparing a pull request. We will be discussing the review-revise
process below. It is important that you understand the overall process first
before you worry about specific commands. This is why we cover this first before
providing instructions below.
``` mermaid
sequenceDiagram
autonumber
participant mkdocs-material
participant PR
participant fork
participant local
mkdocs-material ->> fork: fork on GitHub
fork ->> local: clone to local
local ->> local: branch
loop prepare
loop push
loop edit
local ->> local: commit
end
local ->> fork: push
end
mkdocs-material ->> fork: merge in any changes
fork ->>+ PR: create draft PR
PR ->> PR: review your changes
end
```
1. The first step is that you create a fork of the Material for MkDocs
repository. This provides you with a repository that you can push changes to.
Note that it is not possible to have more than one fork of a given repository
at any point in time. So, the fork you create will be *the* fork you have.
1. Once it is made, clone it to your local machine so you can start working on
your changes.
2. All contributions should be made through a 'topic branch' with a name that
describes the work being done. This allows you to have more than one piece
of work in progress and, if you are working with the public version, also
shows others clearly that the code contained is work in progress. The topic
branch will be relatively short-lived and will disappear at the end, when
your changes have been incorporated into the codebase.
3. If you intend to make any code changes, as opposed to working on
documentation only, you will need to [set up a development
environment](#setting-up-a-development-environment).
4. Next comes the iterative process of making edits, committing them to your
clone. Please commit in sensible chunks that constitute a piece of work
instead of committing everything in one go.
Remember that fine-grained, incremental commits are much easier to
review in than large changes all over the place and with many files involved.
Try to keep your changes as small and localized as possible and keep the
reviewer in mind when committing. In particular, make sure to write
meaningful commit messages.
5. Push your work up to your fork regularly.
6. You should also keep an eye on changes in the Material for MkDocs repository
you cloned. This is especially important if you work takes a while. Please
try and merge any concurrent changes into your fork and into your branch
regularly. You *must* do this at least once before creating a pull request,
so make your life easier and do it more often so as to minimize the risk of
conflicting changes.
7. Once you are happy that your changes are in a state that you can describe
them in a *draft* pull request, you should create this. Make sure to
reference any previous discussions or issues that gave rise to your work.
Creating a draft is a good way to get *early* feedback on your work from the
maintainer or others. You can explicitly request reviews at points where you
think this would be important.
8. Review your work as if you were the reviewer and fix any issues with your
work so far. Look critically at the diffs of the files that you have changed.
In particular, pay attention to whether the changes are as small as possible
and whether you have follow the general coding style used in the project.
If you received feedback, iterate over the process so far as necessary.
You should choose a number of projects to test your changes with. You should
definitely make sure that the changes do not break the building of the
documentation for Material for MkDocs, which you can find in the `docs`
folder. You may also want to make sure that relevant examples from the
[examples repository] still build fine.
[examples repository]: https://github.com/mkdocs-material/examples
### Finalizing
Once you are happy with your changes, you can move to the next step, finalizing
your pull request and asking for a more formal and detailed review. The diagram
below shows the process:
``` mermaid
sequenceDiagram
autonumber
participant mkdocs-material
participant PR
participant fork
participant local
activate PR
PR ->> PR : finalize PR
loop review
loop discuss
PR ->> PR: request review
PR ->> PR: discussion
local ->> fork: push further changes
end
PR ->> mkdocs-material: merge (and squash)
deactivate PR
fork ->> fork: delete branch
mkdocs-material ->> fork: pull
local ->> local: delete branch
fork ->> local: pull
end
```
1. When you are happy that the changes you made amount to a contribution that
the maintainer(s) could integrate into the codebase, finalize the pull
request. This signals to everyone that consider the work 'done' and that it
can be reviewed with a view to accepting and integrating it.
2. Request a review from the maintainer, `@squidfunk`.
3. The maintainer may make comments on your code, which you should discuss with
them. Bear in mind when doing this that the maintainer may have a different
point of view compared to yours. They will often take a more long-term
perspective of maintaining the project in the years to come while you may be
more focused on the specific issue or feature that you worked on. Please keep
the discussion respectful at all times.
It is important to note that not all pull requests get incorporated into the
codebase. The reasons can vary. The work may bring to light other issues that
block integration of the pull request. Sometimes it helps uncover better ways of
doing things or shows that a more general approach is needed. All of this is
fine and helps the project progress, even if specific changes are not,
ultimately, accepted.
4. Make any requested changes by committing them to your local clone and
pushing them up to your fork. This will automatically update the pull request.
It may well take a few iterations to get your contributions to an acceptable
state. You can help the process along by carefully reading comments made and
making changes with care.
5. Once the reviewer is fully satisfied with the changes, they can merge them
into the main branch (or 'master'). In the process, they may 'squash' your
commits together into a smaller number of commits and may edit the messages
that describe them. Congratulations, you have now contributed to this project
and should see the changes in the main branch under your name.
6. You can now delete the fork and your local repository and start afresh again
next time around. Alternatively, you can keep the repository and local clone
around but it is important that you keep them in sync with the upstream
repository for any subsequent work. We recommend that you start by deleting
the branch you used on your fork.
7. To make sure you have the changes you produced, pull them from the main
repository into the main branch of your fork.
8. Similarly, delete the topic branch from your local clone and...
9. pull the changes to its master branch.
## Steps
Now that the overall process is outlined, here are specific instructions and
tips. There are many choices to be made when describing a process for
contributing to a project via a pull request. In the following, we assume that
you are working with the Git command-line tools. For most alternatives (such as
using IDEs or using functionality provided through the GitHub web interface),
the translation from the command-line instructions should be simple enough. We
will add notes only where really necessary to keep the complexity of this to a
reasonable level.
### Forking the repository
To make changes to Material for MkDocs, you would first fork one of its
repositories on GitHub. This is so that you have a repository on GitHub that
you can push changes to (only maintainers and collaborators have write access
to the original repositories).
Fork the [repository] if you want to make changes to code or to the documentation.
It is a good idea to change the name of the repository by appending `-fork` so
that people who come across it know that they have found a temporary fork rather
than the original or a permanent fork of the project. You may also want to add
a description that clarifies what the repository is for.
[repository]: https://github.com/squidfunk/mkdocs-material
### Setting up a development environment
From this point onwards, please follow the [instructions for setting up the
development environment]. They will take you through the process of setting up
an environment in which you can make changes and review/test them.
[instructions for setting up the development environment]: ../customization.md#environment-setup
### Making changes
When you make changes to the code or the documentation please follow the
established style used in the project. Doing so increases readability and
also helps with making diffs easier to read for those who will review the pull
request. Avoid making any large-scale style changes such as asking your IDE
to re-format all code.
Study the code that you are modifying well to ensure that you fully understand
how it works before you try to change it. This will not only help you solve the
problem you are trying to address but also minimize the risks of creating
unintended side effects.
### Committing to a branch
Development for pull requests is best done in a topic branch separate from the
`master` branch. Create a new local branch with `git switch -c <name>` and
commit your changes to this branch.
When you want to push commits to your fork, you can do so with
`git push -u origin <name>`. The `-u` argument is the short version of
`--set-upstream`, which makes the newly created branch 'track' the branch with
the same `<name>` in your fork. This means that then `pull` and `push` commands
will work against that branch in your fork by default.
### Merging concurrent changes
If the work you do takes some time then the chances increase that changes will
be made to the main repository while you work. It is probably a good idea to set
up the original Material for MkDocs repository as an `upstream` repository for
your local clone.
This is what it might look like:
```bash hl_lines="4"
$ git remote -v
origin git@github.com:<your_username>/mkdocs-material-fork.git (fetch)
origin git@github.com:<your_username>/mkdocs-material-fork.git (push)
$ git remote add upstream https://github.com/squidfunk/mkdocs-material.git
$ git remote -v
origin git@github.com:alexvoss/mkdocs-material-fork.git (fetch)
origin git@github.com:alexvoss/mkdocs-material-fork.git (push)
upstream https://github.com/squidfunk/mkdocs-material.git (fetch)
upstream https://github.com/squidfunk/mkdocs-material.git (push)
```
After you have done this, you can pull any concurrent changes from the upstream
repository directly into your clone and do any necessary merges there, then push
them up to your fork. You will need to be explicit about which remote repository
you want to use when you are doing a `pull`:
```bash
# making and committing some local changes
push pull upstream master
```
This fetches changes from the `master` branch into your topic branch and merges
them.
### Testing and reviewing changes
Before you commit any changes, you should make sure that they work as expected
and do not create any unintended side effects. You should test them on at least
these three [smoke tests]:
- The documentation of Material for MkDocs itself. If you set up and run the
development environment as outlined in the [instructions for setting up the
development environment], `mkdocs serve` should be running and continuously
building the documentation. Check that there are no error messages and, ideally,
no (new) warnings.
- Test on a project that represents the problem or a test for a newly developed
feature. You may already have this if you have filed a bug report and created
a [minimal reproduction]. If you are working on a new feature then you may need
to build a project to serve as a test suite. It can double as documentation that
shows how your new feature is meant to work.
- Test with relevant examples from the [Material for MkDocs Examples]
repository.
[smoke tests]: https://en.wikipedia.org/wiki/Smoke_testing_(software)
[minimal reproduction]: https://squidfunk.github.io/mkdocs-material/guides/creating-a-reproduction/
[Material for MkDocs Examples]: https://github.com/mkdocs-material/examples
- Ideally, also test the examples in the [examples repository].
[examples repository]: https://github.com/mkdocs-material/examples
[projects plugin]: https://squidfunk.github.io/mkdocs-material/plugins/projects/
### Creating the pull request
Initially, create the pull request **as a draft**. You do this [through the
various interfaces that GitHub provides]. Which one you use is entirely up to
you. We do not provide specific instructions for using the interfaces as GitHub
provide all the information that should be necessary.
[through the various interfaces that GitHub provides]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request
### Commits, messages, mistakes and 'squash'
### Deleting branches
Once the pull request has been merged into the master branch of the Material
for MkDocs repository, you should remove the branch both from the fork on
GitHub and from the local clone on your computer. This avoids possible
confusion about the state of development.
First, switch back to the `master` branch with `git switch master` and then
delete the branch used for the PR using `git branch -d <name>`.
### Subsequent Pull Requests
It is important that subsequent pull requests are started from an up-to-date
history of the `master` branch. One way to achieve this is to delete the fork
and start with an entirely new one next time round.
If you contribute to Material for MkDocs more often or just happen to be
doing two or more pull requests in succession, you can also just make sure
to sync your fork (using the GitHub UI) and pull from it into your local
repository. So, just delete the topic branch you created (both locally and in
your fork) and pull from the main repository's `master` branch into your
`master` branch before starting work on a new pull request.
## Dos and Don'ts
1. **Don't** just create a pull request with changes that are not explained.
2. **Do** discuss what you intend to do with people in the discussions so that the
rationale for any changes is clear before you write or modify code.
3. **Do** link to the discussion or any issues to provide the context for a pull
request.
4. **Do** ask questions if you are uncertain about anything.
5. **Do** ask yourself if what you are doing benefits the wider community and
makes Material for MkDocs a better product.
6. **Do** ask yourself if the cost of making the changes stands in a good
relation to the benefits they will bring. Some otherwise sensible changes can
add complexity for comparatively little gain, might break existing behaviour
or might be brittle when other changes need to be made.
7. **Do** merge in concurrent changes frequently to minimize the chance of
conflicting changes that may be difficult to resolve.

313
.ai/skills/mkdocs/references/upstream/mkdocs-material-9.7.1-docs/contributing/reporting-a-bug.md Normal file
View File

@@ -0,0 +1,313 @@
# Bug reports
Material for MkDocs is an actively maintained project that we constantly strive
to improve. With a project of this size and complexity, bugs may occur. If you
think you have discovered a bug, you can help us by submitting an issue in our
public [issue tracker], following this guide.
[issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
## Before creating an issue
With more than 20,000 users, issues are created every other day. The maintainers
of this project are trying very hard to keep the number of open issues down by
fixing bugs as fast as possible. By following this guide, you will know exactly
what information we need to help you quickly.
__But first, please do the following things before creating an issue.__
### Upgrade to latest version
Chances are that the bug you discovered was already fixed in a subsequent
version. Thus, before reporting an issue, ensure that you're running the
[latest version] of Material for MkDocs. Please consult our [upgrade guide] to
learn how to upgrade to the latest version.
!!! warning "Bug fixes are not backported"
Please understand that only bugs that occur in the latest version of
Material for MkDocs will be addressed. Also, to reduce duplicate efforts,
fixes cannot be backported to earlier versions.
### Remove customizations
If you're using [customizations] like [additional CSS], [JavaScript], or
[theme extension], please remove them from `mkdocs.yml` before reporting a bug.
We can't offer official support for bugs that might hide in your overrides, so
make sure to omit the following settings from `mkdocs.yml`:
- [`theme.custom_dir`][theme.custom_dir]
- [`hooks`][hooks]
- [`extra_css`][extra_css]
- [`extra_javascript`][extra_javascript]
If, after removing those settings, the bug is gone, the bug is likely caused by
your customizations. A good idea is to add them back gradually to narrow down
the root cause of the problem. If you did a major version upgrade, make sure you
adjusted all partials you have overridden.
!!! warning "Customizations mentioned in our documentation"
A handful of the features Material for MkDocs offers can only be implemented
with customizations. If you find a bug in any of the customizations [that
our documentation explicitly mentions], you are, of course, encouraged to
report it.
__Don't be shy to ask on our [discussion board] for help if you run into
problems.__
[latest version]: ../changelog/index.md
[upgrade guide]: ../upgrade.md
[Customizations]: ../customization.md
[additional CSS]: ../customization.md#additional-css
[JavaScript]: ../customization.md#additional-javascript
[theme extension]: ../customization.md#extending-the-theme
[theme.custom_dir]: https://www.mkdocs.org/user-guide/configuration/#custom_dir
[hooks]: https://www.mkdocs.org/user-guide/configuration/#hooks
[extra_css]: https://www.mkdocs.org/user-guide/configuration/#extra_css
[extra_javascript]: https://www.mkdocs.org/user-guide/configuration/#extra_javascript
[discussion board]: https://github.com/squidfunk/mkdocs-material/discussions
[StackOverflow]: https://stackoverflow.com
[that our documentation explicitly mentions]: ?q="extends+base"
### Search for solutions
At this stage, we know that the problem persists in the latest version and is
not caused by any of your customizations. However, the problem might result from
a small typo or a syntactical error in a configuration file, e.g., `mkdocs.yml`.
Now, before you go through the trouble of creating a bug report that is answered
and closed right away with a link to the relevant documentation section or
another already reported or closed issue or discussion, you can save time for
us and yourself by doing some research:
1. [Search our documentation] and look for the relevant sections that could
be related to your problem. If found, make sure that you configured
everything correctly.[^1]
[^1]:
When adding lines to `mkdocs.yml`, make sure you are preserving the
indentation as mentioned in the documentation since YAML is a
whitespace-sensitive language. Many reported issues turn out to be
configuration errors.
1. [Search our issue tracker][issue tracker], as another user might already
have reported the same problem, and there might even be a known workaround
or fix for it. Thus, no need to create a new issue.
2. [Search our discussion board][discussion board] to learn if other users
are struggling with similar problems and work together with our great
community towards a solution. Many problems are solved here.
__Keep track of all <u>search terms</u> and <u>relevant links</u>, you'll need
them in the bug report.__[^2]
[^2]:
We might be using terminology in our documentation different from yours,
but we mean the same. When you include the search terms and related links
in your bug report, you help us to adjust and improve the documentation.
---
At this point, when you still haven't found a solution to your problem, we
encourage you to create an issue because it's now very likely that you
stumbled over something we don't know yet. Read the following section to learn
how to create a complete and helpful bug report.
[Search our documentation]: ?q=
## Issue template
We have created a new issue template to make the bug reporting process as simple
as possible and more efficient for our community and us. It is the result of
our experience answering and fixing more than 1,600 issues (and counting) and
consists of the following parts:
- [Title]
- [Context] <small>optional</small>
- [Bug description]
- [Related links]
- [Reproduction]
- [Steps to reproduce]
- [Browser] <small>optional</small>
- [Checklist]
[Title]: #title
[Context]: #context
[Bug description]: #bug-description
[Related links]: #related-links
[Reproduction]: #reproduction
[Steps to reproduce]: #steps-to-reproduce
[Browser]: #browser
[Checklist]: #checklist
### Title
A good title is short and descriptive. It should be a one-sentence executive
summary of the issue, so the impact and severity of the bug you want to report
can be inferred from the title.
| <!-- --> | Example |
| -------- | -------- |
| :material-check:{ style="color: #4DB6AC" } __Clear__ | Built-in `typeset` plugin changes precedence of nav title over `h1`
| :material-close:{ style="color: #EF5350" } __Wordy__ | The built-in `typeset` plugin changes the precedence of the nav title over the document headline
| :material-close:{ style="color: #EF5350" } __Unclear__ | Title does not work
| :material-close:{ style="color: #EF5350" } __Useless__ | Help
### Context <small>optional</small> { #context }
Before describing the bug, you can provide additional context for us to
understand what you were 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 bug here.
> __Why this might be helpful__: some errors only manifest in specific settings,
> environments or edge cases, for example, when your documentation contains
> thousands of documents.
### Bug description
Now, to the bug you want to report. Provide a clear, focused, specific, and
concise summary of the bug you encountered. Explain why you think this is a bug
that should be reported to Material for MkDocs, and not to one of its
dependencies.[^3] Adhere to the following principles:
[^3]:
Sometimes, users report bugs on our [issue tracker] that are caused by one
of our upstream dependencies, including [MkDocs], [Python Markdown],
[Python Markdown Extensions] or third-party plugins. A good rule of thumb is
to change the [`theme.name`][theme.name] to `mkdocs` or `readthedocs` and
check if the problem persists. If it does, the problem is likely not
related to Material for MkDocs and should be reported upstream. When in
doubt, use our [discussion board] to ask for help.
- __Explain the <u>what</u>, not the <u>how</u>__ – don't explain
[how to reproduce the bug][Steps to reproduce] here, we're getting there.
Focus on articulating the problem and its impact as clearly as possible.
- __Keep it short and concise__ – if the bug can be precisely explained in one
or two sentences, perfect. Don't inflate it – maintainers and future users
will be grateful for having to read less.
- __One bug at a time__ – if you encounter several unrelated bugs, please
create separate issues for them. Don't report them in the same issue, as
this makes attribution difficult.
---
:material-run-fast: __Stretch goal__ – if you found a workaround or a way to fix
the bug, you can help other users temporarily mitigate the problem before
we maintainers can fix the bug in our code base.
> __Why we need this__: in order for us to understand the problem, we
> need a clear description of it and quantify its impact, which is essential
> for triage and prioritization.
[MkDocs]: https://www.mkdocs.org
[Python Markdown]: https://python-markdown.github.io/extensions/
[Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/
[theme.name]: https://www.mkdocs.org/user-guide/configuration/#theme
### Related links
Of course, prior to reporting a bug, you have read our documentation and
[could not find a working solution][search for solutions]. Please share links
to all sections of our documentation that might be relevant to the bug, as it
helps us gradually improve it.
Additionally, since you have searched our [issue tracker] and [discussion board]
before reporting an issue, and have possibly found several issues or
discussions, include those as well. Every link to an issue or discussion creates
a backlink, guiding us maintainers and other users in the future.
---
:material-run-fast: __Stretch goal__ – if you also include the search terms you
used when [searching for a solution][search for solutions] to your problem, you
make it easier for us maintainers to improve the documentation.
> __Why we need this__: related links help us better understand what you were
> trying to achieve and whether sections of our documentation need to be
> adjusted, extended, or overhauled.
[search for solutions]: #search-for-solutions
### Reproduction
A minimal reproduction is at the heart of every well-written bug report, as
it allows us maintainers to instantly recreate the necessary conditions to
inspect the bug to quickly find its root cause. It's a proven fact that issues
with concise and small reproductions can be fixed much faster.
[:material-bug: Create reproduction][Create reproduction]{ .md-button .md-button--primary }
---
After you have created the reproduction, you should have a `.zip` file, ideally
not larger than 1 MB. Just drag and drop the `.zip` file into this field, which
will automatically upload it to GitHub.
> __Why we need this__: if an issue contains no minimal reproduction or just
> a link to a repository with thousands of files, the maintainers would need to
> invest a lot of time into trying to recreate the right conditions to even
> inspect the bug, let alone fix it.
!!! warning "Don't share links to repositories"
While we know that it is a good practice among developers to include a link
to a repository with the bug report, we currently don't support those in our
process. The reason is that the reproduction, which is automatically
produced by the [built-in info plugin] contains all of the necessary
environment information that is often forgotten to be included.
Additionally, there are many non-technical users of Material for MkDocs that
have trouble creating repositories.
[Create reproduction]: ../guides/creating-a-reproduction.md
[built-in info plugin]: ../plugins/info.md
### Steps to reproduce
At this point, you provided us with enough information to understand the bug
and provided us with a reproduction that we could run and inspect. However, when
we run your reproduction, it might not be immediately apparent how we can see
the bug in action.
Thus, please list the specific steps we should follow when running your
reproduction to observe the bug. Keep the steps short and concise, and make sure
not to leave anything out. Use simple language as you would explain it to a
five-year-old, and focus on continuity.
> __Why we need this__: we must know how to navigate your reproduction in order
> to observe the bug, as some bugs only occur at certain viewports or in
> specific conditions.
### Browser <small>optional</small> { #browser }
If you're reporting a bug that only occurs in one or more _specific_ browsers,
we need to know which browsers are affected. This field is optional, as it is
only relevant when the bug you are reporting does not involve a crash when
[previewing] or [building] your site.
---
:material-incognito: __Incognito mode__ – Please verify that a the bug is
not caused by a browser extension. Switch to incognito mode and try to reproduce
the bug. If it's gone, it's caused by an extension.
> __Why we need this__: some bugs only occur in specific browsers or versions.
> Since now, almost all browsers are evergreen, we usually don't need to know the
> version in which it occurs, but we might ask for it later. When in doubt, add
> the browser version as the first step in the field above.
[previewing]: http://localhost:8000/mkdocs-material/creating-your-site/#previewing-as-you-write
[building]: http://localhost:8000/mkdocs-material/creating-your-site/#building-your-site
### Checklist
Thanks for following the guide and creating a high-quality and complete bug
report – you are almost done. The checklist ensures that you have read this guide
and have worked to your best knowledge to provide us with everything we need to
know to help you.
__We'll take it from here.__

91
.ai/skills/mkdocs/references/upstream/mkdocs-material-9.7.1-docs/contributing/reporting-a-docs-issue.md Normal file
View File

@@ -0,0 +1,91 @@
# Documentation issues
Our documentation is composed of more than 80 pages and includes extensive
information on features, configurations, customizations, and much more. If you
have found an inconsistency or see room for improvement, please follow this
guide to submit an issue on our [issue tracker].
[issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
## Issue template
Reporting a documentation issue is usually less involved than reporting a bug,
as we don't need a [reproduction]. Please thoroughly read this guide before
creating a new documentation issue, and provide the following information as
part of the issue:
- [Title]
- [Description]
- [Related links]
- [Proposed change] <small>optional</small>
- [Checklist]
[reproduction]: ../guides/creating-a-reproduction.md
[Title]: #title
[Description]: #description
[Related links]: #related-links
[Proposed change]: #proposed-change
[Checklist]: #checklist
### Title
A good title should be a short, one-sentence description of the issue, contain
all relevant information and, in particular, keywords to simplify the search in
our issue tracker.
| <!-- --> | Example |
| -------- | -------- |
| :material-check:{ style="color: #4DB6AC" } __Clear__ | Clarify social cards setup on Windows
| :material-close:{ style="color: #EF5350" } __Unclear__ | Missing information in the docs
| :material-close:{ style="color: #EF5350" } __Useless__ | Help
### Description
Provide a clear and concise summary of the inconsistency or issue you
encountered in the documentation or the documentation section that needs
improvement. Explain why you think the documentation should be adjusted and
describe the severity of the issue:
- __Keep it short and concise__ – if the inconsistency or issue can be
precisely explained in one or two sentences, perfect. Maintainers and future
users will be grateful for having to read less.
- __One issue at a time__ – if you encounter several unrelated inconsistencies,
please create separate issues for them. Don't report them in the same issue
– it makes attribution difficult.
> __Why we need this__: describing the problem clearly and concisely is a
> prerequisite for improving our documentation – we need to understand what's
> wrong, so we can fix it.
### Related links
After you described the documentation section that needs to be adjusted above,
we now ask you to share the link to this specific documentation section and
other possibly related sections. Make sure to use anchor links (permanent links)
where possible, as it simplifies discovery.
> __Why we need this__: providing the links to the documentation help us
> understand which sections of our documentation need to be adjusted, extended,
> or overhauled.
### Proposed change <small>optional</small> { #proposed-change }
Now that you have provided us with the description and links to the
documentation sections, you can help us, maintainers, and the community by
proposing an improvement. You can sketch out rough ideas or write a concrete
proposal. This field is optional but very helpful.
> __Why we need this__: an improvement proposal can be beneficial for other
> users who encounter the same issue, as they offer solutions before we
> maintainers can update the documentation.
### Checklist
Thanks for following the guide and providing valuable feedback for our
documentation – 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 we need to improve it.
__We'll take it from here.__

282
.ai/skills/mkdocs/references/upstream/mkdocs-material-9.7.1-docs/contributing/requesting-a-change.md Normal file
View File

@@ -0,0 +1,282 @@
# Change requests
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.
[issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
!!! warning "[How we manage change requests]"
Before submitting a new idea, please take a moment to read how we manage
change requests
[How we manage change requests]: #how-we-manage-change-requests
## Before creating an issue
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.__
[philosophy]: ../philosophy.md
### 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.
[bug reporting guide]: reporting-a-bug.md
### 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.
__Keep track of all <u>search terms</u> and <u>relevant links</u>, you'll need
them in the change request.__[^1]
[^1]:
We might be using terminology in our documentation different from yours,
but we mean the same. When you include the search terms and related links
in your change request, you help us to adjust and improve the documentation.
[:octicons-comment-discussion-16:&nbsp; Start a discussion][discussion board]{ .md-button .md-button--primary }
[discussion board]: https://github.com/squidfunk/mkdocs-material/discussions
## 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]
- [Context] <small>optional</small>
- [Description]
- [Related links]
- [Use cases]
- [Visuals] <small>optional</small>
- [Checklist]
[Title]: #title
[Context]: #context
[Description]: #description
[Related links]: #related-links
[Use cases]: #use-cases
[Visuals]: #visuals
[Checklist]: #checklist
### 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 |
| -------- | -------- |
| :material-check:{ style="color: #4DB6AC" } __Clear__ | Index custom front matter in search
| :material-close:{ style="color: #EF5350" } __Wordy__ | Add a feature where authors can define custom front matter to be indexed in search
| :material-close:{ style="color: #EF5350" } __Unclear__ | Improve search
| :material-close:{ style="color: #EF5350" } __Useless__ | Help
### Context <small>optional</small> { #context }
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
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]
[^2]:
Sometimes, users suggest ideas on our [issue tracker] that concern one of
our upstream dependencies, including [MkDocs][mkdocs], [Python Markdown],
[Python Markdown Extensions] or third-party plugins. It's a good idea to
think about whether your idea is beneficial to other themes, upstreaming
change requests for a bigger impact.
- __Explain the <u>what</u>, not the <u>why</u>__ – don't explain
[the benefits of your idea][Use cases] here, we're getting there.
Focus on describing the proposed change request as precisely as possible.
- __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.
- __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.
---
:material-run-fast: __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.
[Python Markdown]: https://python-markdown.github.io/extensions/
[Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/
### Related links
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.
### Use cases
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.
### Visuals <small>optional</small> { #visuals }
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.
__You can drag and drop the files here or include links to external assets.__
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.
### Checklist
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.__
---
## How we manage change requests
Change requests are submitted as issues on our public [issue tracker]. Since
they often propose new features or enhancements, we review and manage them
differently than bug reports.
To maintain clarity and ensure that our roadmap remains focused and achievable,
we've introduced a structured process and use a dedicated [backlog] to
track and organize change requests, and how they fit into our roadmap.
[backlog]: https://github.com/users/squidfunk/projects/4/views/1
Here’s how we handle new change requests:
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.
__Benefits of this approach:__
- Users get a clearer and quicker overview of known issues and bugs, as change
requests are managed separately, giving a better idea how actively this project
is maintained.
- Related ideas are grouped in the backlog, allowing us to track progress more
effectively, and to more easily see which change requests are related.
## Rejected requests
__Your change request got rejected? We're sorry for that.__ We understand it can
be frustrating when your ideas don't get accepted, but as the maintainers of a
very popular project, we always need to consider the needs of our entire
community, sometimes forcing us to make tough decisions.
We always have to consider and balance many factors when evaluating change
requests, and we explain the reasoning behind our decisions whenever we can.
If you're unsure why your change request was rejected, please don't hesitate
to ask for clarification.
The following principles (in no particular order) form the basis for our
decisions:
- [ ] Alignment with vision and tone of the project
- [ ] Compatibility with existing features and plugins
- [ ] Compatibility with all screen sizes and browsers
- [ ] Effort of implementation and maintenance
- [ ] Usefulness to the majority of users
- [ ] Simplicity and ease of use
- [ ] Accessibility
But that's not the end of your idea – you can always implement it on your own
via [customization]. If you're unsure about how to do that or want to know if
someone has already done it, feel free to get in touch with our community on
the [discussion board].
[customization]: ../customization.md