Contribute

OpenSVC projects are tracked with the git source tracker. The documentation is also managed as a git tracked project. A GitWeb interface is available at https://git.opensvc.com.

Install git

sudo apt-get install git
git config --global user.name "First Last Name"
git config --global user.email "first.lastname@domain.com"

Clone the appropriate git repository

git clone https://git.opensvc.com/docs.opensvc.com/.git
git clone https://git.opensvc.com/opensvc/.git

Send patches

Configured local MTA, without git send-email

Send patch with:

git format-patch --to opensvc-devel@lists.opensvc.com -o /tmp origin | \
while read f ;
    do cat $f|sendmail -t ;
done

Configured local MTA, with git send-email

Install git-send-email:

sudo apt-get install git-email

Send patches with:

git send-email --to="opensvc-devel@lists.opensvc.com" origin

With msmtp, with git send-email

Install git-send-email, and msmtp if you have to use Gmail SMTP (no local MTA configured):

sudo apt-get install git-email
sudo apt-get install msmtp

Set up msmtp:

cat - <<EOF >$HOME/.msmtprc
defaults
tls on
tls_trust_file /usr/share/ncat/ca-bundle.crt
logfile ~/.msmtp.log
# My email service
account gmail
host smtp.gmail.com
port 587
from some.user.name@gmail.com
auth on
user some.user.name@gmail.com
password my-secret
# Set a default account
account default : gmail
EOF

chmod 600 $HOME/.msmtprc

Set up git-send-email to use msmtp:

git config --global sendemail.smtpserver /usr/bin/msmtp

Send patches with:

git send-email --to opensvc-devel@lists.opensvc.com origin

With msmtp, without git send-email

Install msmtp if you have to use Gmail SMTP (no local MTA configured):

sudo apt-get install msmtp

Set up msmtp:

cat - <<EOF >$HOME/.msmtprc
defaults
tls on
tls_trust_file /usr/share/ncat/ca-bundle.crt
logfile ~/.msmtp.log
# My email service
account gmail
host smtp.gmail.com
port 587
from some.user.name@gmail.com
auth on
user some.user.name@gmail.com
password my-secret
# Set a default account
account default : gmail
EOF

chmod 600 $HOME/.msmtprc

Send patches with:

git format-patch --to opensvc-devel@lists.opensvc.com -o /tmp origin | \
while read f ;
    do cat $f | msmtp -t ;
done

Contribute translations

Install the sphinx documentation generator.

For example, on a debian-based system:

sudo apt-get install python-sphinx python-sphinx-rtd-theme

Clone the documentation project:

git clone https://git.opensvc.com/docs.opensvc.com/.git

Step into the cloned project directory:

cd docs.opensvc.com

If starting a new translation, you have to add the new language support to the Makefile. Here are for example the definitions for the french translation you can clone:

html_fr:
        $(SPHINXBUILD) -b html -Dlanguage=fr $(ALLSPHINXOPTS) $(BUILDDIR)/html/fr

po_fr:
        @for pot in `echo $(POT_D)/*.pot` ; do \
        base_pot=`basename $$pot` ; \
        po=$(TRANS_D)/fr/`echo $$base_pot | sed "s/t$$//"` ; \
        echo "merge new strings in $$po" ; \
        touch $$po ; \
        msgmerge -s -U $$po $$pot ; \
        done

mo_fr:
        @for po in `echo $(TRANS_D)/fr/*.po` ; do \
        base_po=`basename $$po` ; \
        mo=$(TRANS_D)/fr/LC_MESSAGES/`echo $$base_po | sed "s/po$$/mo/"` ; \
        echo "gen hash in $$mo" ; \
        msgfmt -c -v -o $$mo $$po ; \
        done

Then plug your new targets in the generic targets:

po: po_fr <your po target>
mo: mo_fr <your mo target>
osvc: html html_fr <your translation target>

Create or refresh the translation files:

make pot po_<your language code>

This last command refreshed the .pot (strings index) and created the .po (translation) files. You can now add your translation in the .po files in source/translated/<your language code>/. Here is an example of translated content:

# 21aa40c7358948d9a69b6813104fd253
# 27fda7e570224a56b6e2631b1c302fd7
#: ../../contribute.rst:57 ../../contribute.rst:91
msgid "Set up :cmd:`msmtp`::"
msgstr "Configuration de :cmd:`msmtp` ::"

Don't forget to create the directory source/translated/<your language code>/LC_MESSAGES/. Finally, create the .mo (binary translation) and html files with:

make mo_<your language code> html_<your language code>

Note you can see what string miss translating in the output of the mo target. For example:

gen hash in source/translated/fr/LC_MESSAGES/agent.install.mo
82 translated messages, 2 fuzzy translations, 8 untranslated messages.

Verify your translation pointing a web browser to your local directory. When satisfied, git add and git commit your touched files (don't track the .mo and html files), and submit your commits using the procedures described in the previous chapters.

Contribute documentations

Getting Started

Install the sphinx documentation generator and ansi2html software https://github.com/ralphbean/ansi2html

For example, on a debian-based system:

sudo apt-get install python-sphinx python-sphinx-rtd-theme

Install ansi2html:

sudo pip install ansi2html

Clone the documentation project:

git clone https://git.opensvc.com/docs.opensvc.com/.git

Step into the cloned project directory:

cd docs.opensvc.com

Modify the documentation source files (.rst located in the sources directory), and then use the Makefile to build the html documentations:

make clean ; make osvc

Once the build is done, all html files can be found in the docs.opensvc.com/build/html folder.

Command line output coloring

When producing command line output, it is expected to follow the steps below to preserve colors, so as to provide a better experience for futures readers:

First generate raw html code from cli:

$ sudo nodemgr print devs --color=yes | ansi2html -i
<span style="font-weight: bold">centos71.opensvc.com                        </span>  <span style="font-weight: bold">Type  </span>  <span style="font-weight: bold">Size</span>  <span style="font-weight: bold">Pct of Parent</span>
`- <span style="color: #aa5500">vda                                      </span>  linear  15g   -
   |- <span style="color: #aa5500">vda1                                  </span>  linear  500m  3%
   `- <span style="color: #aa5500">vda2                                  </span>  linear  14g   96%
      |- <span style="color: #aa5500">centos_centos71-swap               </span>  linear  1g    10%
      `- <span style="color: #aa5500">centos_centos71-root               </span>  linear  13g   89%
         |- <span style="color: #aa5500">loop2                           </span>  linear  50m   0%
         |  |- <span style="color: #aa5500">testsvc1-lv1                 </span>  linear  20m   40%
         |  `- <span style="color: #aa5500">testsvc1-lv2                 </span>  linear  20m   40%
         |- <span style="color: #aa5500">loop1                           </span>  linear  100m  0%
         |  |- <span style="color: #aa5500">testsvc3-lv2                 </span>  linear  20m   20%
         |  |- <span style="color: #aa5500">testsvc3-lv1-real            </span>  linear  52m   52%
         |  |  |- <span style="color: #aa5500">testsvc3-lv1              </span>  linear  52m   100%
         |  |  `- <span style="color: #aa5500">testsvc3-osvc_sync_lv1    </span>  linear  52m   100%
         |  `- <span style="color: #aa5500">testsvc3-osvc_sync_lv1-cow   </span>  linear  8m    8%
         |     `- <span style="color: #aa5500">testsvc3-osvc_sync_lv1    </span>  linear  52m   650%
         `- <span style="color: #aa5500">loop0                           </span>  linear  100m  0%
            |- <span style="color: #aa5500">testsvc2-lv1                 </span>  linear  52m   52%
            `- <span style="color: #aa5500">testsvc2-lv2                 </span>  linear  20m   20%

Edit the .rst document and format the html code as described below, so as to be tagged with .. raw:: html, and enclosed between <pre class=output> and </pre> :

.. raw:: html

    <pre class=output>
        <span style="font-weight: bold">centos71.opensvc.com                        </span>  <span style="font-weight: bold">Type  </span>  <span style="font-weight: bold">Size</span>  <span style="font-weight: bold">Pct of Parent</span>
        `- <span style="color: #aa5500">vda                                      </span>  linear  15g   -
           |- <span style="color: #aa5500">vda1                                  </span>  linear  500m  3%
           `- <span style="color: #aa5500">vda2                                  </span>  linear  14g   96%
              |- <span style="color: #aa5500">centos_centos71-swap               </span>  linear  1g    10%
              `- <span style="color: #aa5500">centos_centos71-root               </span>  linear  13g   89%
                 |- <span style="color: #aa5500">loop2                           </span>  linear  50m   0%
                 |  |- <span style="color: #aa5500">testsvc1-lv1                 </span>  linear  20m   40%
                 |  `- <span style="color: #aa5500">testsvc1-lv2                 </span>  linear  20m   40%
                 |- <span style="color: #aa5500">loop1                           </span>  linear  100m  0%
                 |  |- <span style="color: #aa5500">testsvc3-lv2                 </span>  linear  20m   20%
                 |  |- <span style="color: #aa5500">testsvc3-lv1-real            </span>  linear  52m   52%
                 |  |  |- <span style="color: #aa5500">testsvc3-lv1              </span>  linear  52m   100%
                 |  |  `- <span style="color: #aa5500">testsvc3-osvc_sync_lv1    </span>  linear  52m   100%
                 |  `- <span style="color: #aa5500">testsvc3-osvc_sync_lv1-cow   </span>  linear  8m    8%
                 |     `- <span style="color: #aa5500">testsvc3-osvc_sync_lv1    </span>  linear  52m   650%
                 `- <span style="color: #aa5500">loop0                           </span>  linear  100m  0%
                    |- <span style="color: #aa5500">testsvc2-lv1                 </span>  linear  52m   52%
                    `- <span style="color: #aa5500">testsvc2-lv2                 </span>  linear  20m   20%
    </pre>

After building html documentation, the result looks like the example below :

centos71.opensvc.com                          Type    Size  Pct of Parent
`- vda                                        linear  15g   -
   |- vda1                                    linear  500m  3%
   `- vda2                                    linear  14g   96%
      |- centos_centos71-swap                 linear  1g    10%
      `- centos_centos71-root                 linear  13g   89%
         |- loop2                             linear  50m   0%
         |  |- testsvc1-lv1                   linear  20m   40%
         |  `- testsvc1-lv2                   linear  20m   40%
         |- loop1                             linear  100m  0%
         |  |- testsvc3-lv2                   linear  20m   20%
         |  |- testsvc3-lv1-real              linear  52m   52%
         |  |  |- testsvc3-lv1                linear  52m   100%
         |  |  `- testsvc3-osvc_sync_lv1      linear  52m   100%
         |  `- testsvc3-osvc_sync_lv1-cow     linear  8m    8%
         |     `- testsvc3-osvc_sync_lv1      linear  52m   650%
         `- loop0                             linear  100m  0%
            |- testsvc2-lv1                   linear  52m   52%
            `- testsvc2-lv2                   linear  20m   20%

Decorating with sphinx roles

It is recommended to use the sphinx roles below to improve documentaiton rendering.

As an example for a service, use the syntax:

:c-svc:`svc1`

which will be rendered as svc1

Role Syntax Rendering
:c-action:`action` action
:c-docker-repo:`repo` repo
:c-docker-registry:`registry` registry
:c-node:`node` node
:c-svc:`svc` svc
:c-res:`res` res
:c-tag:`tag` tag
:c-svc-env:`svc-env` svc-env
:c-env:`env` env
:c-pkg:`pkg` pkg
:c-net:`net` net
:c-check:`check` check
:c-form:`form` form
:c-report:`report` report
:c-metric:`metric` metric
:c-chart:`chart` chart
:c-group:`group` group
:c-priv:`priv` priv
:c-user:`user` user
:c-dns-domain:`domain.com` domain.com
:c-dns-record:`example.com. IN A 12.13.14.15` example.com. IN A 12.13.14.15
:c-fset:`fset` fset
:c-disk:`disk` disk
:c-array:`array` array
:c-diskgroup:`diskgroup` diskgroup
:c-rule:`rule` rule
:c-rset:`ruleset` ruleset
:c-modset:`moduleset` moduleset
:c-mod:`module` module
:c-app:`application` application
:c-close:`close` close
:c-fullscreen:`fullscreen` fullscreen
:c-shrink:`shrink` shrink
:c-link:`link` link
:kw:`keyword` keyword
:cmd:`command` command
:opt:`opt` opt