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 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 version | Maintained API controller's version | Compatible client version (web / mobile) | Compatible database version |
---|---|---|---|
1.4.1 | 1.4.X | 1.5.0 | 1.4.1 |
1.3.X | 1.4.0 | ||
1.2.X | |||
1.4.0 | 1.4.X | 1.4.0 | 1.3.2 |
1.3.X | 1.3.1 | ||
1.2.X | 1.3.0 | ||
1.3.6 | 1.3.X | 1.3.1 | 1.2.9 |
1.2.X | |||
1.1.X | 1.3.0 | ||
1.3.5 | 1.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