jami-docs

Forked version of Jami documentation, see wrycode.com/jami-docs-demo
git clone git://git.wrycode.com/wrycode/jami-docs.git
Log | Files | Refs

how-to-contribute-to-this-documentation.txt (3750B)

      1 #########################################
      2 How to Contribute to This Documentation
      3 #########################################
      4 
      5 Contributions to these docs are always welcome, from small corrections
      6 to whole new chapters.
      7 
      8 This page will walk through the steps to create a new page or submit a
      9 correction. The patch review process is the same as :doc:`for any
     10 other Jami project <how-to-submit-a-patch>`, so we will not explain
     11 every command.
     12 
     13 **TODO: internationalization**
     14 
     15 Dependencies
     16 ================================
     17 
     18 You will need Git installed and configured to use your SSH keypair,
     19 and you will need an account on `Gerrit <review.jami.net/>`_ . If you
     20 need help with this, see :doc:`the beginning of our patch submission
     21 guide <how-to-submit-a-patch>`
     22 
     23 If you want to preview your changes in a web browser, you must install
     24 `Sphinx <https://www.sphinx-doc.org>`_. You also need to install a
     25 markdown parser for Sphinx:
     26 
     27 .. code-block:: bash
     28 
     29 	$ pip install --upgrade recommonmark
     30 
     31 
     32 Cloning the repository
     33 =========================================
     34 Clone the repository and configure the push settings like this:
     35 
     36 .. code-block:: bash
     37 
     38 	$ git clone "ssh://USERNAME@review.jami.net:29420/jami-docs.git"
     39 	$ cd jami-docs
     40 	$ git config remote.origin.push HEAD:refs/for/master
     41 
     42 It might be a good idea to checkout a new branch before you make changes:
     43 
     44 .. code-block:: bash
     45 
     46 	$ git checkout -b my_wiki_change
     47 
     48 Editing a page
     49 =========================================
     50 
     51 Pages are written in either markdown or `reStructuredText
     52 <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_. You
     53 can click "View page source" at the top of any page to see how the
     54 page was written.
     55 
     56 Go ahead and make your changes to the ``.rst`` or ``.md`` files.
     57 
     58 Previewing your work
     59 =======================================
     60 
     61 From the base of the repository, run:
     62 
     63 .. code-block:: bash
     64 
     65 	$ make clean && make html
     66 
     67 You should now be able to view the documentation in your web
     68 browser. The homepage is at ``_build/html/index.html``.
     69 
     70 Saving your work
     71 ================================================
     72 
     73 .. code-block:: bash
     74 
     75 	$ git add source/file/you/edited.md
     76 	$ git commit
     77 
     78 Your commit message should look something like this:
     79 
     80 .. code-block:: none
     81 
     82     wiki: short summary of your change in present tense
     83 
     84     Longer description of your change in complete sentences, if necessary.
     85 
     86     Gitlab issue numbers (e.g. #445), if relevent.
     87 
     88 Submitting a change
     89 ================================================
     90 
     91 The first time you try to push your changes, Gerrit will complain that
     92 you don't have a Change-Id in your commit, and provide an ``scp``
     93 command to install the commit hook. After running the command, you
     94 should be able to recommit and push your change:
     95 
     96 .. code-block:: bash
     97 
     98 	$ git commit --amend --no-edit
     99 	$ git push
    100 
    101 
    102 Modifying your work
    103 ================================================
    104 
    105 A reviewer may ask you to make changes to your patch before accepting
    106 it. This is no problem! Simply make the changes, ``git add`` them, and
    107 run ``git commit --amend`` to modify the patch.
    108 
    109 After your first time running ``git commit``, **do not** run ``git
    110 commit`` again on a patch. Instead, you should always type:
    111 
    112 .. code-block:: bash
    113 
    114 	$ git commit --amend
    115 
    116 Adding a page
    117 ===============================================
    118 
    119 If you decide to add a whole new page to the documentation, you must
    120 also add it to the ``toctree`` directive of that chapter.
    121 
    122 For instance, if you added a new guide called
    123 ``Hosting-JAMS-on-AWS.md`` in the ``guides`` folder, you should add it
    124 in the ``toctree`` directive of ``guides/index.rst``:
    125 
    126 
    127 .. code-block:: ReST
    128 
    129 	.. toctree::
    130 
    131 	   Bug-report-guide
    132 	   ...
    133 	   Hosting-JAMS-on-AWS
    134 
    135 
    136 (Don't include the filename extension.)