.. _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 `. .. toctree:: :hidden: conventions Introduction ============ |project| is meant to be a repository of stable, coherent, well-documented :term:`data type specifications `. To facilitate this, new :term:`data types ` start in a domain called :term:`sandbox` and undergo a review process before they are included in the :term:`stable` part of |project|. However, :term:`data types ` from both domains can be used transparently and combined freely. When adding new :term:`data type specifications ` - even to the :term:`sandbox` - care should be taken to * not duplicate existing :term:`data types ` or packages * reuse and integrate existing :term:`data types ` * follow the :ref:`conventions for writing type specifications ` Adding a new Data Type ====================== The process of experimenting with and eventually adding a new :term:`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 `_ and do the following: .. parsed-literal:: git clone -b |version| |repository| rst-proto cd rst-proto git checkout -b |version|-:samp:`{YOUR-PROJECT}` where :samp:`{YOUR-PROJECT}` is an arbitrary project name which you can freely choose. #. **Add new data type** Add a proto file for the new :term:`data type` using the `google protocol buffers`_ syntax. Please refer to `their manual `_ for detailed instructions and follow our :ref:`conventions`. You can also have a look at the existing :ref:`data types ` and their source code for inspiration. In case your new type should also be used as a collection, add the following line directly above the ``message`` definition: .. code-block:: java // @create_collection This will automatically create an additional type named after your new type with the suffix ``Collection`` added to the name. The new collection type contains a single repeated field for your new type. You can also control the name of the collection: .. code-block:: java // @create_collection(MyNewTypeList) #. **From source build** for testing Test the new data type by building your local branch from source as documented in :ref:`installation-from-source`. #. **Validate coding convention** Ensure that the coding conventions are not violated by running a checker script. Inside the project root run: .. parsed-literal:: python2 project/codeCheck.py -r proto Ensure that no warnings are raised. #. **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 ` will only be committed to master. If you want new :term:`data types ` 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 `, modifications of existing (and hence also the newly added) :term:`types ` 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`.