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

Source code

Code is stored with the 'git' version control system and is hosted on GitHub (since Google Code was shut down). Repositories:

• openmalaria (this one)
• openmalaria.snippets Short bits of XML as templates and examples of how to configure scenarios
• openmalaria.tools Python tools for quickly plotting results, generating documentation from OpenMalaria's XSD, and updating OpenMalaria XMLs.
• vecnet.openmalaria Code for the VecNet OpenMalaria interface. Contains the new experiment creator
• openmalaria.experiment-creator Old Java experiment creation tool
• openmalaria.omtools Guillaume's OpenMalaria frontend (unmaintained)
• openmalaria.svn-archive Pre-2013 history of OpenMalaria development

To check out a complete copy of one of the repositories and to commit changes, you need to use git. The Git Pro book should help get you started.

OpenMalaria branches

The main OpenMalaria repository (i.e. for the OpenMalaria model code) has several different branches. To get the latest stable code, use the main branch. We don't commit directly to the main branch. New changes should be committed to a feature branch forked from main. We recommend that you fork the repo, create your own feature branch forked from the main branch, and create a pull request from your branch to the main branch of SwissTPH/openmalaria when ready. The pull request will then be reviewed and merged.

You can find more information about organisation of the repository in

• the readme file
• and here the actual branches

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).

When moving to a new version, the following files must be updated to reflect the version which is being released:

• version.txt
• The static variable SCHEMA_VERSION in model/util/DocumentLoader.h
• The line --namespace-map http://openmalaria.org/schema/scenario_45=scnXml in schema/CMakeLists.txt
• All the schema/*.xsd files
• All the test/*.xml files
• The util/example_scenario.xml file
• Copy build/schema/scenario_current.xsd to schema/scenario_XX.xsd.

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"

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-45.0" > version.txt 
git add version.txt 
git commit -m "Bump version to $(cat version.txt)"
git tag -s -a $(cat version.txt)
git push origin $(cat version.txt)

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

Note that only tag names starting with schema- will trigger a release build, and it does not have to be on the main branch. See: .github/workflows/build-and-deploy.yml

In case you pushed tags you did not want to push, you can delete them on the repository like this:

$ git tag -d release01
$ git push origin :refs/tags/release01

Continuous Integration

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

ci = Continuous Integration Service

• github actions for Ubuntu and MacOS,
• 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.