How to Contribute to This Documentation

Contributions to these docs are always welcome, 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.

TODO: internationalization

Dependencies

You will need Git installed and configured to use your SSH keypair, and you will need an account on Gerrit . If you need help with this, see the beginning of our patch submission guide

If you want to preview your changes in a web browser, you must 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

It might be a good idea to checkout a new branch before you make changes:

$ git checkout -b my_wiki_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 see how the page was written.

Go ahead and make your changes to the .rst or .md files.

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 _build/html/index.html.

Saving your work

$ git add source/file/you/edited.md
$ git commit

Your commit message should look something like this:

wiki: short summary of your change in present tense

Longer description of your change in complete sentences, if necessary.

Gitlab issue numbers (e.g. #445), if relevent.

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 scp 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 accepting it. This is no problem! Simply make the changes, git add them, and run git commit --amend to modify the patch.

After your first time running git commit, do not run git commit again on a patch. Instead, you should always type:

$ git commit --amend

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 in the toctree directive of guides/index.rst:

.. toctree::

   Bug-report-guide
   ...
   Hosting-JAMS-on-AWS

(Don’t include the filename extension.)