O3 currently follows a release cadence of two weeks. This means we aim to publish new versions of our frontend to our QA environment(opens in a new tab) every fortnight. QA review and feedback typically takes a week, after which we promote the release to our demo Production environment(opens in a new tab). This cadence is subject to change as we get more experience with the process.

Steps of releasing O3

Cutting a new release of O3 typically includes three steps

1. Cutting releases for the frontend modules

2. Cutting releases for the backend modules

3. Cutting the release for the ref app

1. Releasing frontend modules

Frontend releases are typically cut individually, for each module. Here’s how you can cut a release for a frontend module:

2. Releasing backend modules

Prior to cutting a O3 release, you must ensure that the backend module versions which are currently on a SNAPSHOT version must be released. E.g:- there cannot be lines such as <module.version>x.x.x-SNAPSHOT</module.version> in the distro reference application’s pom.xml file - https://github.com/openmrs/openmrs-distro-referenceapplication/blob/main/distro/pom.xml

There are two main methods for releasing a module:

• GitHub Actions (recommended)

• Bamboo (legacy, currently not supported for most modules)

Releasing a Module Using GitHub Actions

1. Visit the Actions tab on your module's GitHub repository and select the release action

   Open

   

2. Click the Run workflow button.

3. Set the values as follows:

   • Branch: main

   • Release version: Find the current snapshot version in pom.xml and remove the -SNAPSHOT suffix. For example, if the current version is 2.4.1-SNAPSHOT, set the release version to 2.4.1.

   • Next development version: Set it to the next snapshot version in the format x.(x+1).0-SNAPSHOT. For example, if the current version is 2.4.1-SNAPSHOT, the next development version would be 2.5.0-SNAPSHOT.

   • Branch to release from: main

4. Click Run workflow.

5. Once the workflow completes, verify the release by:

   • Checking the workflow logs to confirm it completed successfully.

   • Checking the GitHub tags to make sure the correct tag was created.

   • Checking the OpenMRS Maven artifact repository at http://openmrs.jfrog.io/ui/native/public/org/openmrs/ to confirm the artifacts were published.

Releasing a module on Bamboo (Deprecated)

Before you update these versions, you’ll need to release such backend modules on Bamboo (instructions adopted from https://openmrs.atlassian.net/wiki/x/awSFAQ ).

1. Find the bamboo plan for the relevant module.

2. Check if the module has had a release recently (it might be that the module has had a release and the version just didn’t get updated in the ref app)

Open

3. Click the latest build to go to the build’s page to trigger a release.

Open

Here’s an example PR where we updated these versions - https://github.com/openmrs/openmrs-distro-referenceapplication/pull/896

Open

You can set the release version and the development version. If you are overriding the development version, leave the value empty as the script will automatically set it (make sure to check in the metadata section for the relevant build that the variables are what you want them to be, if they are, you don’t need to override these). If you don't override development version, it will be automatically set for you. If you are releasing 1.19.0, your next snapshot should be 1.20.0-SNAPSHOT, as per this discussion.

2. Updating the versions in the reference application

Once the backend releases are done, update their version numbers in the distro refapp repository.

Here’s an example PR that does that - https://github.com/openmrs/openmrs-distro-referenceapplication/pull/896

3. Releasing O3 to the QA environment

Once the step 1 and step 2 are released, you need to go to the Bamboo plan Create initial QA release - https://ci.openmrs.org/browse/O3-CQR and Run customized build

Open

The o3.core.version should be set to the latest release of esm-core which you can find in here - https://github.com/openmrs/openmrs-esm-core/releases

The o3.release.version should be set to the new version of O3 that you want to release.

Once this plan finishes, the build script would have automatically made a branch for this release as releases/x.x.x. The job will also trigger the Publish QA Release job here. Once the publish QA release job completes, the version would be deployed to test3.openmrs.org.

4. Updating the QA environment

Say you’ve made some bug fixes, and you need to make some changes to the ref app itself. Make sure to add those changes to the respective release branch. Once the changes are merged in to the release branch, you’ll need to run the Bamboo plan https://ci.openmrs.org/browse/O3-CUQR , which does the following:

• Update the version numbers

• Create a corresponding Git commit

• Tag the commit with the version number

  Open

  

  Set the release version to the next release candidate number

Once the job finishes, the Publish QA Release job which updates the test instance, will be automatically triggered.

5. Releasing to the production environment

Run the Deploy Reference Application job, and click the Deploy → Demo button.

Open

Select Create new release and select the last successful build from the QA release.

Open