Contributing

Contributing

Committing to the main branch is strictly forbidden. New changes should be committed to a feature branch based on main. We recommend that you fork the repo, create your own feature branch and create a pull request to the main branch when ready. The pull request will then be reviewed and merged.

You can find more information about the organization of the repository in the readme file.

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.

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

Increasing the version number

When moving to a new version, the following files must be updated to reflect the version which is being released. Remember to update the version number in the following commands:

• echo "schema-50.0" > version.txt
• The static variable SCHEMA_VERSION in model/util/DocumentLoader.h
• The line --namespace-map http://openmalaria.org/schema/scenario_50=scnXml in schema/CMakeLists.txt
• The util/example_scenario.xml file
• cp build/schema/scenario_current.xsd schema/scenario_50.xsd
• schema/*.xsd files

find schema -maxdepth 1 -type f -name '*.xsd' ! -name 'scenario_*.xsd' -exec perl -pi -e 's#http://openmalaria\.org/schema/scenario_49#http://openmalaria.org/schema/scenario_50#g' {} +

• All the test/scenario*.xml files:

perl -pi -e '
    s#http://openmalaria\.org/schema/scenario_49#http://openmalaria.org/schema/scenario_50#g;
    s#schemaVersion="49"#schemaVersion="50"#g;
' test/scenario*.xml

Triggering a release build

After updating the files below, commit and create a new tag:

git add version.txt 
git add model/util/DocumentLoader.h
git add util/example/example_scenario.xml
git add -u test/
git add -u schema/
git commit -m "Bump version to $(cat version.txt)"
git tag -s -a $(cat version.txt)
git push origin $(cat version.txt)

Pushing the tag to this repository will trigger a release build, which will automatically upload artifacts available for download here.

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

We rely on Github actions for Linux and MacOS (see: build-and-deploy.yml) and on Appveyor for Windows (see: appveyor.yml).

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

ci = Continuous Integration Service

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

Automated tests

There are 2 kinds of tests in OpenMalaria:

1. unit tests, and
2. System tests AKA "black box" tests.

Unit tests uses the cxxtest unit testing framework.

System tests simply associated different input scenarios with expected simulation output files, and are executed by a Python script that calls OpenMalaria and verifies that the output matches the expected results.

Deprecated repositories related to OpenMalaria:

• 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.
• openmalaria.omtools Guillaume's OpenMalaria frontend (unmaintained)
• openmalaria.svn-archive Pre-2013 history of OpenMalaria development