How to Release the O3 RefApp

Our Community Environments: 

Dev Environment

QA Environment

Production Environment

Dev Environment

QA Environment

Production Environment

Most recent committed dev work

Most Recent Release

A specific version of O3 RefApp release

Sample login for all these is admin/Admin123.

Our Release Process:

Ongoing: PR Smoke Tests

Step 1: QA Release

Step 2: Manual Checks

Step 3: O3 RefApp Release

Ongoing: PR Smoke Tests

Step 1: QA Release

Step 2: Manual Checks

Step 3: O3 RefApp Release

Automatic tests are set up in the major O3 mono-repos to give devs feedback within minutes after submitting a PR if their work will break a key feature elsewhere within that mono-repo. 

The latest builds triggered by merged PRs can be reviewed here

"QA Release": Updating the test3 environment with the latest build and selected work from dev3.

"Tags": Moment in time snapshot - what the repo looked like at a particular point in time (points to a particular commit at a particular time where we released something)

Manual last-pass through of O3 using the test3/QA Environment and checking for clinical or other concerns using the O3 Review Checklist

"RefApp Release": specifies the version of each. 

Each of these steps is explained further below. The full fancy diagram here of the O3 Release Pipeline. 

Step 1: QA Release Process


Begin by securing team approval to initiate a QA release. Announce your intentions on the designated communication channel, such as #openmrs3. This release process includes updating both frontend and backend modules, adhering to Semantic Versioning principles as described here.

You may opt to not release a module if there are no significant changes since the last version.

Releasing Modules

Frontend Modules

To release a frontend module, follow the detailed steps available in the frontend module release guide.

Backend Modules

For backend modules, refer to the backend module release guide.

Releasing the Reference Application

Creating a Release Pull Request (PR)

Your PR should include exactly two commits, as follows (example):

Commit 1: Version Pinning

  • Action: Create a release commit to pin version numbers for all modules previously marked as "next" or "SNAPSHOT".

  • Reason: This ensures that the test environment does not deploy versions intended for development stages, thus preserving more recent changes.

  • Example: See this commit.

Commit 2: Version Reset

  • Action: Follow up with a commit that reverts to development version numbers.

  • Reason: Maintains the 'main' branch in a state where it continues to point to 'next', preserving the ongoing development status of the environment.

  • Label: The commit should be tagged (release-revert).

A GitHub Action is set up to run extensive end-to-end tests on the release commits within the PR. Ensure all tests pass before proceeding with the merge. The PR title should begin with "(release)" to activate these tests.

Tagging the Release

Tag the release commit using the version number. This tag facilitates the automatic triggering of subsequent QA processes.

Automated QA Release

Once the tag is set, it automatically triggers the QA release and the rebuilding of the Test3 environment. In our Bamboo Continuous Integration system, the "Distribution 3.x Releases" deployment project is exclusively triggered by such tags.


Final Steps

Announce the completion of the QA release and the new version number to the community via #openmrs.

This restructured document should provide clearer guidance and more accessible links, enhancing the overall ease of following the release process.

Step 2: Manual Checks

  1. Confirm that tests are passing satisfactorily in Test3. Using the O3 QA Spreadsheet is highly recommended, in addition to checking the automated tests. Go through both the Baseline Checklist and any checks specific to that release - so that new features get some review.  

  2. Remember: Keep an eye out for manual work that could be automated - we want to maximize how we use Automation and reduce manual overhead over time. 

Step 3: RefApp Release

Go to the Deployment Project, "Deploy Reference Application 3.x"  (under the "Deploy" option in the menu)

  1. Click the cloud icon for the QA build:

  2. "Create new release" → Use the last successful build, and name the release one version number higher than the last one. When that build finishes, the new O3 RefApp release is automatically pushed to both our "production" environment in and the Docker containers are automatically updated. 

  3. Announce the O3 Demo release & version number to the community in #openmrs3 and on Talk. 

Note: You can see the history of releases here.