How to contribute to this documentation
Contributions to these docs are always welcome and appreciated, from small corrections to whole new chapters.
This page will walk through the steps to create a new page or submit a correction. The patch review process is the same as for any other Jami project, so we will not explain every command.
You will need Git installed and configured to use your SSH keypair, and an account on the Jami Gerrit, where you would send your patches for review. If you need help with this, see the beginning of our patch submission guide (TODO).
If you want to preview your changes locally in your web browser, you need to install Sphinx. You also need to install a markdown parser for Sphinx:
$ pip install --upgrade recommonmark
Cloning the repository
Clone the repository and configure the push settings like this:
$ git clone "ssh://USERNAME@review.jami.net:29420/jami-docs.git" $ cd jami-docs $ git config remote.origin.push HEAD:refs/for/master
You may want to checkout a new branch for each contribution/change
before you make any change to the files, so that you could easily
git pull any future changes from upstream into your main local
$ git checkout -b my-example-change
Editing a page
Pages are written in either markdown or reStructuredText. You can click “View page source” at the top of any page to open the raw source of the page and see how it was written.
Go ahead and make your changes to the
Previewing your work
From the base of the repository, run:
$ make clean && make html
You should now be able to view the documentation in your web
browser. The homepage is at
Saving your work
$ git add source/file/you/edited.md $ git commit
Your commit message should look something like this:
Short summary of your change in present tense Longer description of your change in complete sentences, if necessary. Jami GitLab issue numbers (e.g. GitLab: #445), if relevant.
Add new page section to guides/how-to-contribute-to-this-documentation Add a new section explaining how to add a new page to these docs, including listing it in the `toctree` directive of the containing section/folder index. GitLab: #123
Submitting a change
The first time you try to push your changes, Gerrit will complain that
you don’t have a Change-Id in your commit, and provide an
command to install the commit hook. After running the command, you
should be able to recommit and push your change:
$ git commit --amend --no-edit $ git push
Modifying your work
A reviewer may ask you to make changes to your patch before merging
it. This is no problem! Simply make the changes,
git add them,
git commit --amend to modify the patch. Note the
--amend switch, which is needed to tell git to amend/tweak the
existing newest commit rather than making a new commit. This is the
workflow for updating a proposed change when using Gerrit.
Adding a page
If you decide to add a whole new page to the documentation, you must
also add it to the
toctree directive of that chapter.
For instance, if you added a new guide called
hosting-jams-on-aws.md in the
guides folder, you should add it
toctree directive of
guides/index.rst, without the
.. toctree:: bug-report-guide ... hosting-jams-on-aws