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
- not duplicate existing data types or packages
- reuse and integrate existing data types
- follow the conventions for writing type specifications
Adding a new Data Type¶
The process of experimenting with and eventually adding a new data type is as follows:
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.12 https://code.cor-lab.org/git/rst.git.proto rst-proto cd rst-proto git checkout -b 0.12-
YOUR-PROJECT
where
YOUR-PROJECT
is an arbitrary project name which you can freely choose.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.
From source build for testing
Test the new data type by building your local branch from source as documented in From Source.
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.
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.12
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.12 (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.
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.