132 lines
2.9 KiB
ReStructuredText
Executable File
132 lines
2.9 KiB
ReStructuredText
Executable File
######################
|
|
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 for public functions, and in the source file for private functions.
|
|
|
|
|
|
**************
|
|
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.5 <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``
|
|
|
|
Public functions: ``obi_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'.
|
|
|
|
|
|
*****************
|
|
Programming rules
|
|
*****************
|
|
|
|
*
|
|
|