Contributing to the Documentation¶
Documentation is as important as code. It follows the exact same principles: DRY, tests, ease of maintenance, extensibility, optimization, and refactoring just to name a few. And of course, documentation has bugs, typos, hard to read tutorials, and more.
If this is your first time thinking about writing documentation, have a look at Writing great documentation from Jacob Kaplan-Moss, one of the authors of Django, an awesome Python web framework.
Before contributing, you need to become familiar with the markup language used by the documentation.
The mangos-zero documentation is hosted on BitBucket:
If you want to submit a patch, fork the official repository on BitBucket and then clone your fork:
$ git clone firstname.lastname@example.org:YOURUSERNAME/documentation.git
develop branch holds the documentation for the development branch of the code.
Create a dedicated branch for your changes (for organization):
$ git checkout -b improving_foo_and_bar
You can now make your changes directly to this branch and commit them. When you’re done, push this branch to your BitBucket fork and initiate a pull request.
Creating a Pull Request¶
Following the example, the pull request will default to be between your
improving_foo_and_bar branch and the
The mangos-zero documentation is licensed under a Creative Commons Non-Commercial Attribution-Share Alike 3.0 Unported License.
You can also prefix the title of your pull request in a few cases:
[WIP](Work in Progress) is used when you are not yet finished with your pull request, but you would like it to be reviewed. The pull request won’t be merged until you say it is ready.
[WCM](Waiting Code Merge) is used when you’re documenting a new feature or change that hasn’t been accepted yet into the core code. The pull request will not be merged until it is merged in the core code (or closed if the change is rejected).
Pull Request Format¶
Unless you’re fixing some minor typos, the pull request description must include the following checklist to ensure that contributions may be reviewed without needless feedback loops and that your contributions can be included into the documentation as quickly as possible:
| Q | A | ------------- | --- | Doc fix? | [yes|no] | New docs? | [yes|no] (PR # on mangoszero/server if applicable) | Fixed tickets | [comma separated list of tickets fixed by the PR]
An example submission could now look as follows:
| Q | A | ------------- | --- | Doc fix? | yes | New docs? | yes (mangoszero/server#1250) | Fixed tickets | #1075
Online documentation is rebuilt on every code-push to BitBucket.
Documenting new Features or Behavior Changes¶
If you’re documenting a brand new feature or a change that’s been made in
mangos-zero, you should precede your description of the change with a
.. versionadded:: 1.X tag and a short description:
.. versionadded:: 1.1 The ``getCreaturesInRange`` method was introduced in **mangos-zero** 1.1.
All documentation in the mangos-zero Documentation should follow the documentation standards.