.. _developer-tutorial:

====================
 Developer Tutorial
====================

.. seealso::

   :ref:`user-tutorial`
     Using |project| in programs
   :ref:`conventions`
     Coding conventions

This tutorial explains how to extend |project| by adding new
:term:`data types <data type>`.

Adding new Data Types
=====================

|project| is meant to be a repository of stable :term:`type
specifications <data type>` to enable compatibility across
applications. To enable this, new :term:`data types <data type>` start
in an experimental :term:`sandbox` domain and undergo a review process
to be included into the :term:`stable` part of |project|.

The process to experiment with and eventually add new :term:`data
types <data type>` is as follows:

#. Creating **local git branch** for experimentation

   To experiment with a new :term:`data type`, create a branch of the
   |project| sources. Have a look at `git <http://git-scm.com/>`_ and
   do the following:

   .. parsed-literal::

      git clone -b |version| |repository| rst-proto
      git checkout -b |version|-:samp:`{YOUR-PROJECT}`

   where :samp:`{YOUR-PROJECT}` is an arbitrary project name which you
   can freely choose.

#. **From source build** for testing

   Add a proto file for the new :term:`data type` and test it by
   building your local branch from source as documented in
   :ref:`installation-from-source`.

#. **Pull request**

   Once your :term:`data type` is tested and works well in your local
   setup, add the new file, commit your changes to your local branch
   and create a patch:

   .. parsed-literal::

      git add YourNewType.proto
      git commit
      git format-patch origin/|version|

   This will create at least one :file:`*.patch` file with your local
   changes. To incorporate the new :term:`data type` into the public
   |project| repository, write a feature request at `RST Redmine`_
   with the title :samp:`"Add {YOUR-NEW-TYPE} to the sandbox"` and the
   issue category "Type Proposal". Attach the :file:`*.patch` file(s)
   generated above.

   .. note::

      By default, new :term:`data types <data type>` will only be
      committed to master. If you want new :term:`data types <data
      type>` also to be added to the |version| (current stable)
      branch, you have to note that in the issue description. This
      will then only allow *adding* new :term:`data types <data
      type>`, modifications of existing (and hence also the newly
      added) :term:`types <data type>` are only allowed for the master
      branch to preserve backwards compatibility at any point in time.

#. **Stable data type**

   After a :term:`data type` stabilized during the course of one
   release cycle of |project|, it will be reviewed and becomes a
   candidate for being moved from :term:`sandbox` to :term:`stable`.
   
.. note::

   Please follow the :ref:`coding conventions <conventions>` when modifying or
   adding new data types!