Contributing Guidelines

See contribution-guide.org for the basics on contributing to an open source project.

The content in this repository is licensed CC-BY-SA-4.0. By contributing, you grant this project and its members the right to publish your contribution under the terms of that license.

Reporting an Error, or Requesting an Addition

Any corrections and change requests are managed using GitHub’s issue tracker. If you never opened an issue on GitHub before, consult the Mastering Issues guide.

Adding Your Own Contributions

The handbook is rendered to HTML using the Sphinx tool, the text itself is written using reStructuredText markup.

The easiest way to edit text is using GitHub’s built-in editor. When you click the edit button (pencil), it will fork the project for you and then open the rich-text web editor. It is very convenient to fix small spelling or grammatical errors on the fly, while you’re reading the handbook.

If you’re reading this on Read the Docs, take note of the “Edit on GitHub” button in the top-right corner of each page, which will take you to the under-lying text file on GitHub.

The GitHub editor has a Preview button (use it) and can save directly into a so-called ‘pull request’ (PR) for integration into the project. Please do not save changes into a PR just to “try it out”, you can however save changes into your fork at your pleasure.

The more technical but also more powerful way is to clone the project to your machine. Here are some resources to help you with getting started, if you never wrote anything for a Sphinx document before:

After you wrote, spell-checked and reviewed your text, open a pull request as explained in the GitHub help. Try to keep PRs at a reasonable size, ideally only changing one file, especially when it comes to the command reference. This reduces the potential of merge conflicts and rework, and also makes reviews take a manageable amount of time.