Country Versioning in OpenLMIS 3

What is OpenLMIS version 3?

OpenLMIS version 3 is not just a repackaged version of OpenLMIS 2. Instead, version 3 represents a significant shift in how features are built, shared and deployed. Whereas previous versions of OpenLMIS consisted of one, large application, OpenLMIS version 3 comprises separate, standalone and deployable 'services' or 'components'. Each service represents a logical set of related features, such as 'Requisitions', 'Fulfillment' (convert requisitions to orders), and 'Stock Management'. Cross-cutting feature sets like 'Authentication' and 'Notifications' are also bundled as separate deployable services. Each country implementation may choose whether or not to deploy some or all of these services. In addition, implementers can decide whether to create and deploy new custom services specific to the country needs.

This architectural approach is known as "microservices," and it provides for a more flexible, modular and extensible approach to software design and delivery that promotes greater shared value for OpenLMIS implementers. Different countries can use different sets of these services, and extend or customize specific parts, while still staying connected to the global OpenLMIS codebase. By using the global, shared codebase, rather than forking their own country-specific version, an implementation can continue to receive updates, bug fixes, security and performance improvements, as well as new features from the global community. For more information on microservices, we recommend Martin Fowler's introduction and resource guide.

Figure 1: OpenLMIS is made up of individual services that a country implementation can choose from

How does OpenLMIS versioning work?

Each OpenLMIS version 3 service uses "Semantic Versioning," where version numbers and the way they change convey meaning about the underlying code and what has been modified from one version to the next.

In each incremental "patch" release (3.0.1, 3.0.2, etc.), bug fixes, security updates, and performance improvements will come out on an as-needed schedule
In each "minor" release (3.1, 3.2, 3.3, etc.), new functionality will come out periodically and will be backwards compatible
A “major” release (e.g. OpenLMIS version 4) constitutes profound changes that may break backward-compatibility with the previous major release

The new architecture allows different country implementations to have some of their own custom features (through extension modules), but to still share the common, core base of software. The patch and minor releases will be backwards compatible and easy to apply to existing implementations. In order to achieve the "shared value" community goals, it is important that implementations of version 3.x.x stay up-to-date with these releases. When all participating countries stay up-to-date, that means any implementation can benefit from improvements made in another implementation.

Figure 2: Example of semantic versioning.

What does a country implementation deploy?

Implementers of OpenLMIS are responsible for choosing the combinations of services to use to satisfy their needs. This "recipe" of combinations is defined in a distribution. An implementation can also include custom-built extensions (see next question) and customizations. Figure 3 provides a visual example of how a country can select different services for its specific deployment.

How does a country/implementation instance differ from OpenLMIS version 3?

A country/implementation instance runs on top of OpenLMIS version 3 with some of its own customizations and extensions. Because each new global release of OpenLMIS 3 is backwards compatible, the extensions will continue to operate with minimal changes over time.

Figure 3: A country implementation selects which OpenLMIS services it wants to use.

How does an implementation upgrade to OpenLMIS 3.1, 3.2, etc?

Each time a new core version of OpenLMIS is released, we recommend implementations stay up-to-date and use the new version. The benefit of staying up-to-date is that each new version will include some bug fixes, performance enhancements and security improvements. In addition, the global shared value proposition depends on countries staying up-to-date, so that when one country makes an improvement it then becomes available to other countries.

What does an implementation team need to do to upgrade?

Regression testing occurs prior to each release and is completed by the global OpenLMIS team. The goal is to minimize any possibility of new releases causing issues during an upgrade. The OpenLMIS community strives to make upgrades easy and pain-free so that multiple implementations can participate in the shared value community.

We recommend that each implementation first upgrade one of their test servers in order to test out the system with their configuration and their set of extension modules in place before upgrading their production servers.

Figure 4: Country upgrade process

Backward compatibility and code forking

OpenLMIS strongly discourages code forking. The OpenLMIS community adopted this strategy after previous country implementations forked the core code software, causing concern by funders over the costly nature of these one-off implementations. The community responded by adopting an approach whereby features and improvements could be funded once and then used to benefit multiple countries.