diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..94f5866e9 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,66 @@ +# Contributing + +Interested in contributing to the Material theme? Before you do, please read +the following guidelines. + +## Submission context + +### Got a question or problem? + +For quick questions there's no need to open an issue as you can reach us on +[gitter.im][1]. + + [1]: https://gitter.im/mkdocs-material/general + +### Found a bug? + +If you found a bug in the source code, you can help us by submitting an issue +to our GitHub Repository. Even better, you can submit a Pull Request with a +fix. However, before doing so, read the submission guidelines. + +### Missing a feature? + +You can request a new feature by submitting an issue to our GitHub Repository. +If you would like to implement a new feature, please submit an issue with a +proposal for your work first, to be sure that it is of use for everyone, as +the Material theme is highly opinionated. Please consider what kind of change +it is: + +* For a **Major Feature**, first open an issue and outline your proposal so + that it can be discussed. This will also allow us to better coordinate our + efforts, prevent duplication of work, and help you to craft the change so + that it is successfully accepted into the project. + +* **Small Features** and bugs can be crafted and directly submitted as a Pull + Request. However, there is no guarantee that your feature will make it into + the master, as it's always a matter of opinion whether if benefits the + overall functionality of the theme. + +## Submission guidelines + +### Submitting an issue + +Before you submit an issue, please search the issue tracker, maybe an issue for +your problem already exists and the discussion might inform you of workarounds +readily available. + +We want to fix all the issues as soon as possible, but before fixing a bug we +need to reproduce and confirm it. In order to reproduce bugs we will +systematically ask you to provide a minimal reproduction scenario using the +custom issue template. + +Unfortunately we are not able to investigate / fix bugs without a minimal +reproduction, so if we don't hear back from you we are going to close issues +that don't have enough information to be reproduced. + +### Submitting a Pull Request (PR) + +Search GitHub for an open or closed PR that relates to your submission. You +don't want to duplicate effort. Fork the project, make your changes in **a new +git branch** and commit your changes with a descriptive commit message. Then +push your branch to GitHub and send a PR to `mkdocs-material:master`. If we +suggest changes, make the required updates, rebase your branch and push +the changes to your GitHub repository, which will automatiaclly update your PR. + +Afer your PR is merged, you can safely delete your branch and pull the changes +from the main (upstream) repository.