Developer Tutorial

See also

User Tutorial
Using RST in programs
Coding Conventions
Coding conventions

This tutorial explains how to extend RST by adding new data types.

Introduction

RST is meant to be a repository of stable, coherent, well-documented data type specifications. To facilitate this, new data types start in a domain called sandbox and undergo a review process before they are included in the stable part of RST. However, data types from both domains can be used transparently and combined freely.

When adding new data type specifications - even to the sandbox - care should be taken to

Adding a new Data Type

The process of experimenting with and eventually adding a new data type is as follows:

  1. Creating local git branch for experimentation

    To experiment with a new data type, create a branch of the RST sources. Have a look at git and do the following:

    git clone -b 0.16 https://code.cor-lab.org/git/rst.git.proto rst-proto
    cd rst-proto
    git checkout -b 0.16-YOUR-PROJECT
    

    where YOUR-PROJECT is an arbitrary project name which you can freely choose.

  2. Add new data type

    Add a proto file for the new data type using the google protocol buffers syntax. Please refer to their manual for detailed instructions and follow our Coding Conventions. You can also have a look at the existing 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:

    // @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:

    // @create_collection(MyNewTypeList)
    
  3. From source build for testing

    Test the new data type by building your local branch from source as documented in From Source.

  4. Validate coding convention

    Ensure that the coding conventions are not violated by running a checker script. Inside the project root run:

    python2 project/codeCheck.py -r proto
    

    Ensure that no warnings are raised.

  5. Pull request

    Once your 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:

    git add YourNewType.proto
    git commit
    git format-patch origin/0.16
    

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

    Note

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

  6. Stable data type

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