contribute.rst - jami-docs - Gitiles

 ##################
 Contribute to Jami
 ##################

 Contributions to Jami are always welcome and are much appreciated.
 There are many ways to contribute to Jami, including reporting bugs
 and issues, contributing code, helping package and maintain Jami for
 your GNU/Linux distribution or other operating system, as well as
 contributing to these very docs themselves.

 Please see below for how to get started contributing to Jami!

 .. contents::
    :local:
    :depth: 2

 Reporting bugs and issues
 =========================

 Please see the :doc:`user/bug-report-guide` for step-by-step
 instructions on how to report bugs and issues you encounter in Jami.

 Contributing code
 =================

 TODO

 Packaging Jami
 ==============

 TODO

 Contributing 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 :doc:`for any
 other Jami project <how-to-submit-a-patch>`, so we will not explain
 every command.

 .. note:: By contributing to this documentation, you agree to make
           your contributions available under the :doc:`fdl`, Version
           1.3 or any later version published by the Free Software
           Foundation; with no Invariant Sections, no Front-Cover
           Texts, and no Back-Cover Texts.

           You are also promising that you are the author of your
           changes, or that you copied them from a work in the public
           domain or a work released under a free license that is
           compatible with the :doc:`fdl`.  DO NOT SUBMIT COPYRIGHTED
           WORK WITHOUT PERMISSION.

 **TODO: internationalization**

 Dependencies
 ------------

 You will need Git installed and configured to use your SSH keypair,
 and an account on the `Jami Gerrit <https://review.jami.net>`_, where
 you would send your patches for review.  If you need help with this,
 see :doc:`the beginning of our patch submission guide
 <how-to-submit-a-patch>` (TODO).

 If you want to preview your changes locally in your web browser, you
 need to install `Sphinx <https://www.sphinx-doc.org>`_,
 the `Read the Docs Sphinx theme
 <https://sphinx-rtd-theme.readthedocs.io/en/stable/>`_,
 and the `MyST Markdown parser
 <https://myst-parser.readthedocs.io/en/latest/index.html>`_.

 .. code-block:: bash

    $ pip install --upgrade sphinx sphinx_rtd_theme myst_parser

 If you want to use the auto-build and auto-refresh feature, also install
 `sphinx-autobuild <https://github.com/executablebooks/sphinx-autobuild>`_.

 .. code-block:: bash

    $ pip install --upgrade sphinx-autobuild

 Cloning the repository
 ----------------------

 Clone the repository and configure the push settings like this:

 .. code-block:: bash

    $ 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
 branch:

 .. code-block:: bash

 	$ git checkout -b my-example-change

 Editing a page
 --------------

 Pages are written in either markdown or `reStructuredText
 <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_.
 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 ``.rst`` or ``.md`` files.

 Previewing your work
 --------------------

 From the base of the repository, run:

 .. code-block:: bash

    $ 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``.

 .. note:: This documentation does not currently build with the latest
           version of sphinx. Please see `this issue on GitLab
           <https://git.jami.net/savoirfairelinux/jami-docs/-/issues/15>`_
           for a workaround and updates regarding this problem.

 To automatically build the documentation and refresh your web browser whenever
 you save changes, run:

 .. code-block:: bash

    $ make clean && make watch

 Keep this running in the background, then navigate to http://127.0.0.1:8000
 (*not* the local .html file).

 Saving your work
 ----------------

 .. code-block:: bash

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

 Your commit message should look something like this:

 .. code-block:: none

    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.

 For example:

 .. code-block:: none

    Add new page section to contribute guide

    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 ``scp``
 command to install the commit hook.  After running the command, you
 should be able to recommit and push your change:

 .. code-block:: bash

    $ 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,
 and run ``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 page called
 ``hosting-jams-on-aws-guide.md`` to the Jami user manual in the
 ``user`` folder, you should add it in the ``toctree`` directive of
 ``user/index.rst``, *without* the file extension:


 .. code-block:: reST

    .. toctree::

       ...
       bug-report-guide
       hosting-jams-on-aws-guide
	##################
	Contribute to Jami
	##################

	Contributions to Jami are always welcome and are much appreciated.
	There are many ways to contribute to Jami, including reporting bugs
	and issues, contributing code, helping package and maintain Jami for
	your GNU/Linux distribution or other operating system, as well as
	contributing to these very docs themselves.

	Please see below for how to get started contributing to Jami!

	.. contents::
	:local:
	:depth: 2

	Reporting bugs and issues
	=========================

	Please see the :doc:`user/bug-report-guide` for step-by-step
	instructions on how to report bugs and issues you encounter in Jami.

	Contributing code
	=================

	TODO

	Packaging Jami
	==============

	TODO

	Contributing 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 :doc:`for any
	other Jami project <how-to-submit-a-patch>`, so we will not explain
	every command.

	.. note:: By contributing to this documentation, you agree to make
	your contributions available under the :doc:`fdl`, Version
	1.3 or any later version published by the Free Software
	Foundation; with no Invariant Sections, no Front-Cover
	Texts, and no Back-Cover Texts.

	You are also promising that you are the author of your
	changes, or that you copied them from a work in the public
	domain or a work released under a free license that is
	compatible with the :doc:`fdl`. DO NOT SUBMIT COPYRIGHTED
	WORK WITHOUT PERMISSION.

	TODO: internationalization

	Dependencies
	------------

	You will need Git installed and configured to use your SSH keypair,
	and an account on the `Jami Gerrit <https://review.jami.net>`_, where
	you would send your patches for review. If you need help with this,
	see :doc:`the beginning of our patch submission guide
	<how-to-submit-a-patch>` (TODO).

	If you want to preview your changes locally in your web browser, you
	need to install `Sphinx <https://www.sphinx-doc.org>`_,
	the `Read the Docs Sphinx theme
	<https://sphinx-rtd-theme.readthedocs.io/en/stable/>`_,
	and the `MyST Markdown parser
	<https://myst-parser.readthedocs.io/en/latest/index.html>`_.

	.. code-block:: bash

	$ pip install --upgrade sphinx sphinx_rtd_theme myst_parser

	If you want to use the auto-build and auto-refresh feature, also install
	`sphinx-autobuild <https://github.com/executablebooks/sphinx-autobuild>`_.

	.. code-block:: bash

	$ pip install --upgrade sphinx-autobuild

	Cloning the repository
	----------------------

	Clone the repository and configure the push settings like this:

	.. code-block:: bash

	$ 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
	branch:

	.. code-block:: bash

	$ git checkout -b my-example-change

	Editing a page
	--------------

	Pages are written in either markdown or `reStructuredText
	<https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_.
	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 ``.rst`` or ``.md`` files.

	Previewing your work
	--------------------

	From the base of the repository, run:

	.. code-block:: bash

	$ 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``.

	.. note:: This documentation does not currently build with the latest
	version of sphinx. Please see `this issue on GitLab
	<https://git.jami.net/savoirfairelinux/jami-docs/-/issues/15>`_
	for a workaround and updates regarding this problem.

	To automatically build the documentation and refresh your web browser whenever
	you save changes, run:

	.. code-block:: bash

	$ make clean && make watch

	Keep this running in the background, then navigate to http://127.0.0.1:8000
	(not the local .html file).

	Saving your work
	----------------

	.. code-block:: bash

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

	Your commit message should look something like this:

	.. code-block:: none

	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.

	For example:

	.. code-block:: none

	Add new page section to contribute guide

	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 ``scp``
	command to install the commit hook. After running the command, you
	should be able to recommit and push your change:

	.. code-block:: bash

	$ 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,
	and run ``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 page called
	``hosting-jams-on-aws-guide.md`` to the Jami user manual in the
	``user`` folder, you should add it in the ``toctree`` directive of
	``user/index.rst``, without the file extension:


	.. code-block:: reST

	.. toctree::

	...
	bug-report-guide
	hosting-jams-on-aws-guide