Contributing to the Documentation¶
The documentation is as important as the 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 many more.
Before contributing, you need to become familiar with the markup language used by the documentation.
The Park-Manager documentation is hosted on GitHub, in the main repository:
If you want to submit a patch, fork the official repository on GitHub and then clone your fork to you local destination:
$ git clone email@example.com:YOUR_USERNAME/park-manager.git
Under the name
origin you will have from now on the access to your fork.
Add also the main repository as the
$ git remote add upstream firstname.lastname@example.org:park-manager/park-manager.git
See also Submitting a Patch
Remember to name your commits descriptively, keep them possibly small, with just unitary changes (such that you change something only in one part of the docs, not everywhere).
When you’re done, push this branch to your GitHub fork and initiate a pull request.
Your pull request will be reviewed, you will be asked to apply fixes if necessary and then it will be merged into the main repository.
To test the documentation before a commit, make sure Docker is running:
$ make doc
- In the
docsdirectory view the generated HTML files in the
Creating a Pull Request¶
GitHub covers the topic of pull requests in detail.
The Park-Manager documentation is licensed under a Creative Commons Attribution-Share Alike 3.0 Unported License.
You should always prefix the PR name with a
And your commits with
doc as the
You can 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.
[BundleName]when you add documentation of the Park-Manager Modules.
[API]when you are contributing docs to
the API guide.
For instance if your pull request is about documentation of some feature of the Core module,
but it is still a work in progress it should look like:
[WIP][Documentation][Core] Arbitrary feature documentation.
Documenting new Features or Behavior Changes¶
If you’re documenting a brand new feature or a change that’s been made in
Park-Manager, you should precede your description of the change with a
.. versionadded:: 1.X tag and a short description:
.. versionadded:: 1.1 The ``getProductDiscount`` method was introduced in Park-Manager v1.1.
All documentation in the Park-Manager Documentation should follow the documentation standards.