######################
Programming guidelines
######################


***************
Version control
***************

Version control is managed with `Git <http://git-scm.com/>`_. 
Issue tracking and repository management are done using `GitLab <https://about.gitlab.com/>`_ 
at http://git.metabarcoding.org/.


Branching strategy
==================


Master branch
-------------

The master branch should only contain functional scripts. 


Topic branches
--------------

Topic branches should correspond to development branches revolving around a topic corresponding 
to the branch's name.


Release branches
----------------

Release branches should start with duplicates of tags and be used to patch them. 


Tags
----

Tags should never be committed to.


Rebasing
--------

Rebasing should be avoided on the distant server.


Merging
-------

Merging should never overwrite on a release branch or on a tag.


Branching strategy diagram
--------------------------

.. image:: ./images/version_control.png


Issue tracking
==============

Issue tracking is done using `GitLab <https://about.gitlab.com/>`_ at http://git.metabarcoding.org/.
Tickets should always be labeled with the branches for which they are relevant.


*************
Documentation
*************

C functions are documented in the header files.


**************
OBITools3 wiki
**************

The OBITools3 wiki is managed with GitLab.


*********************
Programming languages
*********************

C99 :
	* All the low-level input/output functions (e.g. all the `OBIDMS <formats.html#the-obitools3-data-management-system-obidms>`_ functions)
	* Computing-intensive code (e.g. alignment or pattern matching)
	
`Cython <cython.org>`_ :
	* Object layer
	* OBITools3 library

`Python 3 <https://www.python.org/>`_ :
	* Top layer code (scripts)	
	
For the documentation, `Sphinx <http://sphinx-doc.org/>`_ should be used for both the original 
documentation and for the generation of documentation from the python code. `Doxygen <http://www.stack.nl/~dimitri/doxygen/>`_ 
should be used for the generation of documentation from the C code, which should be then integrated 
in the Sphinx documentation using `Breathe <https://breathe.readthedocs.org/en/latest/>`_.


******************
Naming conventions
******************

Struct, Enum:                                   ``Title_case``

Enum members, macros, constants:                ``ALL_CAPS``

Functions, local variables:                     ``lower_case``

Functions that shouldn't be called directly:    ``_lower_case`` (``_`` prefix)

Global variables:                                ``g_lower_case`` (``g_`` prefix)

Pointers:                                        ``pointer_ptr`` (``_ptr`` suffix)

.. note::
    Underscores are used to delimit 'words'.

.. todo::
    ``obi_function`` for public functions names?


*****************
Programming rules
*****************

    *