Skip to content
Snippets Groups Projects
Select Git revision
  • master default protected
1 result

contribute.rst

Blame
  • Code owners
    Assign users and groups as approvers for specific file changes. Learn more.
    contribute.rst 5.33 KiB

    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!

    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.

    TODO: internationalization

    Dependencies

    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 :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, the Read the Docs Sphinx theme, and the MyST Markdown parser.

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

    $ pip install --upgrade sphinx-autobuild

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

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

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

    $ 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

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

    For example:

    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:

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

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