Skip to content

Contributing Guide

First off, thanks for taking the time to contribute! 🚀

The Basics

If you are looking to help with a code contribution, this project uses MKDocs for documentation generation, Python for the plugin, along with a splattering of Markdown and ShellScript. I've included my VSCode workspace and a Docker development container. Read about how I develop using VSCode and Docker. If you don't feel ready to make a code contribution yet, no problem! You can also check out the issues we have in the Github issue tracker.

How to Contribute

Never made an open-source contribution before? Wondering how contributions work in this project? Here's a quick rundown!

  1. Find an issue that you are interested in addressing or a feature that you would like to add in the issue tracker. Don't see your issue? Submit one!

  2. Fork the repository associated with the issue to your local GitHub account. This means that you will have a copy of the repository under your-GitHub-username/repository-name.

  3. Clone the repository to your local machine.

    git clone https://github.com/github-username/mkdocs-simple-plugin.git

  4. Create a new branch for your fix.

    git checkout -b branch-name-here

  5. Make the appropriate changes for the issue you are trying to address or the feature that you want to add.

  6. Add the file contents of the changed files to the "snapshot" git uses to manage the state of the project, also known as the index.

    git add <file_list>

  7. Insert a short message of the changes made to store the contents of the index with a descriptive message.

    git commit -m"Insert a short message of the changes made here"

  8. Push the changes to the remote repository

    git push origin branch-name-here.

  9. Submit a pull request to the upstream repository.

  10. Title the pull request with a short description of the changes made and the issue or bug number associated with your change. For example, you can title an issue like so "Added more log outputting to resolve #4352".

  11. In the description of the pull request, explain the changes that you made, any issues you think exist with the pull request you made, and any questions you have for the maintainer. It's OK if your pull request is not perfect (no pull request is), the reviewer will be able to help you fix any problems and improve it!

  12. Wait for the pull request to be reviewed by a maintainer.

  13. Make changes to the pull request if the reviewing maintainer recommends them.

  14. Celebrate your success after your pull request is merged!

Getting Help

If you need help, you can ask questions on the issue tracker

Last update: August 25, 2023