DeveloperGuide

This Guide is intended for OpenMalaria Developers (original by @tph-thuering) It contains notes regarding Continuous Integration with github and how versioning should work

Testing the version number of a openMalaria executable

You can see the openMalaria version by running this command:

./openMalaria --version

and the output looks like this:

OpenMalaria simulator of malaria epidemiology and control.
For more information, see https://github.com/SwissTPH/openmalaria/wiki

	schema version: 	33
	program version:	schema-33.1

OpenMalaria is copyright © 2005-2015 Swiss Tropical Institute
and Liverpool School Of Tropical Medicine.

OpenMalaria comes with ABSOLUTELY NO WARRANTY. This is free software, and you
are welcome to redistribute it under certain conditions. See the file COPYING
or http://www.gnu.org/licenses/gpl-2.0.html for details of warranty or terms of
redistribution.

for example: https://travis-ci.org/SwissTPH/openmalaria/builds/73035096#L567 (you might need to scroll down in your browser to find line 567

Finding the right version

You can use the program version name to find the right version of the source code and executables.

https://github.com/SwissTPH/openmalaria/releases/tag/ + schema-33.1 => https://github.com/SwissTPH/openmalaria/releases/tag/schema-33.1

Versioning

Everytime a new version of openMalaria needs to be built from source code into binary form, a decision has to be made how it is called.

openMalaria uses two kind of release types which use different names

• releases, which are used for stable versions
  • schema-MAJOR.MINOR.PATCH e.g.: schema-33.0.1
• pre-releases, which are used for development versions
  • schema-MAJOR[|.MINOR]-BRANCH[-NUMBER] e.g.: schema-34-develop-2 for branch develop or schema-34-feature-branch-1 for branch feature-branch

Releases and Pre-Releases are being compiled and tested automatically by the Continuous Integration system and uploaded to the Github Releases page

Releases

A release of openMalaria is considered a version which has new models implemented in a state we consider as stable and tested.

As a guideline, the following rules apply for releases:

• Increase MAJOR number when there are changes to the XML syntax rendering old scenario files incompatible

• Increase (or add) MINOR number when a small feature is added (e.g. backports from development versions) and XML syntax changes which do not render XMLs written for the previous release incompatible e.g. annotation for documentation updates.

• Increase (or add) PATCH number for bugfix releases.

• The MAJOR number should always be the same number as the schema version (model/util/DocumentLoader.h should have the MAJOR number).

• The file version.txt should reflect the version which is being released.

Pre-Releases

A pre-release of openMalaria is considered a version which has new models implemented in a state we do not consider as stable and tested.

Regards to the XML Schema definition, this means there will be changes in a way that requires updates on older scenario XMLs.

Use "schema-MAJOR-BRANCH-NUMBER" when working on one or more features, while MAJOR is the next version. Bugfixes can still use "schema-MAJOR.MINOR" while working in a separate branch, but must be updated to "schema-MAJOR.MINOR.PATCH" once this branch gets merged to develop or a schema-branch.

Tags and branches

Development usually happens in feature-branches. This means: A developer who wants to work on a new feature creates a branch with a specific name based on master or develop.

A feature-branch name should be speaking. For example: vivax-bloodstage-update

OpenMalaria has multiple different versions in development but only 2 types of builds will be published:

• release (new version with either no change to the XML or a new MAJOR version which changes XML)
• pre-release (new MAJOR version which is being worked on, but not all features are ready for release)

A release or pre-release only happens when people want to use the new version and don't want or are not able to compile it themselves and need an executable of openMalaria to run on their computer or cluster.

Integrating new features

If you want to work on a new feature, please create a new feature-branch from develop for new features or master for backported features.

git checkout master
git checkout -b "YOUR_FEATURE_BRANCH_NAME"
 "Do work here"
git commit
git push "YOUR_FEATURE_BRANCH_NAME"

If you work on a new feature and using a specific test scenario you can change .travis.yml to use test/run.py SCENARIO instead of the whole test sequence ctest. But please revert this change once you want to merge.

Once you have a new feature ready you can merge it to a MAJOR branch (named "schema-NUMBER").

How to update to a new version

If you have implemented a new feature or a bugfix, update the version like this:

echo "schema-33.1" > version.txt 
git add version.txt 
git commit -m "Bump version to `cat version.txt`"
git tag `cat version.txt`
git push `cat version.txt`

This will create an openMalaria-binary for download. (This means you don't have to build manually anymore).

Continuous Integration

If a tag is pushed to our github repository, the following happens:

ci = Continuous Integration Service

• travis-ci for Linux and OS X,
• appveyor for Windows

• ci checks out our repository and tries to build it
• ci runs unittests and scenario tests and gives feedback
• ci will upload the build (if successful) to github releases if a tagged commit is successful.

For example see this build for a bugfix (schema-33.0.1): https://travis-ci.org/SwissTPH/openmalaria/builds/71915483#L528

Currently (2015-07-20) builds are Linux-only.

We are working on integration of OS X builds and Windows as well. For more information see: Build infrastructure Milestone