Developers guide

This page explains the basic workflow used in the development of statismo.

A step by step guide to the git/github workflow

Notes about the repository layout

We are using a slightly simplified version of the Git flow branching model: all cutting-edge development is performed on the develop branch, while the current stable (released) version is maintained in the master branch. Note that we do not have separate release branches, however we might introduce them in the future in case the need arises (currently, we do not see the need to maintain multiple releases).

In a nutshell, all development generally happens on the develop branch. The only reason to directly "write" to the master branch are bugfixes affecting released code, and the promotion of the current develop state to a new stable release.

Fork the repository

Create your own fork of the repository and clone it on your system. You will find detailed instructions on how to do this in this article.

Create a new branch

Create a new branch (from the develop branch) for the feature you want to develop.

git checkout develop
git checkout -b my-feature-branch

Remember, you should always branch out from the develop branch, not from master. The only exception to this rule is if you contribute a bugfix to released code, in which case you'd branch from master. Note that such bugfixes must not change the externally visible API of the project (e.g., it is not allowable to change method signatures etc.).

Implement your feature

Do the development. Commit using the usual git commands git add ... git commit ..., etc. (If you are new to git, you can read up the basics in this book).

Synchronize upstream changes

Once the development is complete, you need to synchronize your local repository with the upstream (which may have new changes in the meantime).
To do this, checkout the develop branch and pull the changes from the upstream repository.

git checkout develop
git fetch upstream
git rebase upstream/develop

Then go back to your feature branch, git checkout my-feature-branch and rebase the changes into your feature branch

git rebase develop

push changes to github and create pull request

Now you can push your changes to github git push origin my-feature-branch and create a pull request (see this article). Remember to specify the correct branch (usually develop) for the pull request.

Do's and don'ts

• Always create a new branch from the develop branch for every feature you develop.
  • Never work directly in the develop branch
• Always test that your contribution compiles
  • You may have to run a make clean to enforce that all parts are rebuilt
• Write descriptive commit messages that clearly explain the task that you worked on. Start by providing a one line description of your commit (< 80 characters) Then detail the content of your commit in a separate paragraph
• In case the Python Wrappings work on your system, run the unit tests.

How to run the unit tests

There are two types of unit tests. One test suite tests the Representers. These tests are written in C++ and can be compiled by switching on the feature BUILD_REPRESENTER_TESTS in CMake (you only see the feature in advanced mode). To run the tests, simply type make test in the build directory.

The second, and more important, test suite is written in Python. In order to be able to run these tests, the Python Wrapping of statismo has to be enabled in the CMake (BUILD_PYTHON_WRAPPING_VTK). To run these tests, type make unit_test.