Version management

openIMIS consists of a number of interacting components (web app, mobile apps, API/web service, database) which are maintained in parallel GitHub repositories, as a result it is important to track and document compatibility across different versions of each component.

Numbering system

  • Based on the semantic versioning methodology defined here,
  • All components’ versions (API, mobile app, web app) will consist of 3 digits: MAJOR.MINOR.PATCH, where:
    • MAJOR version when incompatible changes are made,
    • MINOR version when functionality in a backwards-compatible manner are made, and
    • PATCH version when backwards-compatible bug fixes are made
  • But, different components’ versions will not necessarily increment synchronously.

Maintenance / Compatibility

The 3 most recent versions of the API will be maintained, where maintenance means that only bugs will be fixed in these versions. Only the latest version of the mobile app is maintained. The same will apply for the database.

The compatibility restrictions across components will be documented on GitHub:

  • Each API versions will indicate which database version can be used
  • And each mobile app version will indicate which API version can be used


For example, in the current architectural context, we could have:

API versionMaintained API controller's versionCompatible client version (web / mobile)Compatible database version
1.4.11.4.X1.5.01.4.1
1.3.X1.4.0
1.2.X
1.4.01.4.X1.4.0

1.3.2

1.3.X1.3.1
1.2.X1.3.0
1.3.61.3.X1.3.11.2.9
1.2.X
1.1.X1.3.0
1.3.51.3.X
1.2.X
1.1.X

This means that:

  • An API version will contain the definition of past controllers
  • When fixing an API bug in a given API version, this very bug will also be fixed in the 2 previous API versions
  • A MINOR change in the database will trigger a MINOR change in the API
  • A MINOR API change will trigger a database MINOR change only if new data field is required
  • The mobile app versions will be independently incremented