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

Pre-Releases are new schema version which is being worked on, but not all features are ready for a release. It 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.

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

A release or pre-release only should happen 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"

Please also update the list of branches with a description of the new branch when pushing.

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

For information on the progress of integration of these services see: Build infrastructure Milestone