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 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
Contribution workflow (GitHub)
A separate GitHub repository is created to manage each openIMIS component, e.g;
- web_app_vb
- web_service_vb
- rest_api_c-sharp
- etc
Using the Git branching features, each of these repositories will have a master branch (the latest stable version) and a separate branch for each version. For example, for the repository rest_api_c-sharp, there could be the following branches:
- 1.1.0
- 1.1.1
- 1.2.0
- Master ( = branch 1.2.0)
Contributions for a given version will be made via pull requests:
- For example, if a bug(s) is found in API 1.2.1, a new branch 1.2.2 is created from branch 1.2.1.
- No more changes will be made to branch 1.2.1.
- Developers/contributors assigned to the fix_XYZ will create the branch 1.2.2_fix_XYZ based on branch 1.2.2.
- Contributors will clone the branch 1.2.2_fix_XYZ locally to work on the fix
- Contributors will then commit and push their changes to the GitHub branch 1.2.2_fix_XYZ
- Once finished with the fix XYZ, contirbutors will make a pull request to ask for their contribution to be integrated by the system architect.
- The system architect will then review contributions and merge the branch 1.2.2_fix_XYZ with a new branch 1.2.2 (assuming that the code change is accepted).
- Branch 1.2.2 will then be tested before a release is tagged to this branch (=GitHub snapshot for this version)
- Branch 1.2.2 will be merged with the master branch to ensure that the lastest version is always available through the master branch
- No more changes will be made to branch 1.2.2.