Rolling a Release

Below is the process used for creating and publishing a release of OpenLMIS 3.x. These steps are being documented for 3.0 Beta, and this page should be used and updated for 3.0, 3.1, and subsequent 3.x releases.

Goals

What's the purpose of publishing a release? It gives us a specific version of the software for the community to test drive and review. Beta releases will be deployed with demo data to the UAT site (uat.openlmis.org). That will be a public, visible URL that will stay the same while stakeholders test drive it. It will also have demo data and will not be automatically wiped and updated each time a new Git commit is made.

Prerequisites

Before you tag and publish the release, make sure the following are in place:

• Demo data and seed data: make sure you have demo data that is sufficient to demonstrate the features of this release. Your demo data might be built into the repositories and used in the build process OR be prepared to run a one-time database load script/command.
• Features are completed for this release and are checked in.
• All automated tests pass.
• Release notes and other documentation/publicity is ready for distribution.

Steps

When you are ready to create and publish a release:

1. Select a tag name such as '3.0.0-beta' based on the OpenLMIS Releases guidelines in the wiki.
2. Tag each GitHub repository with that same tag. Do this for each service/repo in the project, including the API services, the AngularJS UI repo, and the Blue distribution.
   1. Do we need a release branch? For the 3.0 Beta release, we do not need a release branch, only a tag. If there are any later fixes we need to apply to the 3.0 Beta, we would issue a new beta release (eg, 3.0 Beta R1) to publish additional, specific fixes.
      
   2. Do we need a code freeze? We do not need a "code freeze" process. We will add the tag in Git, and everyone can keep committing further work on master as usual. Updates to master will be automatically built and deployed at the Test site (test.openlmis.org), but not the UAT site (uat.openlmis.org).
   3. Confirm that your release tags appear in GitHub.
      1. Look under the Releases tab of each repository, eg https://github.com/OpenLMIS/openlmis-requisition/releases.
3. Set CI/CD to build that specific tag and deploy it to the UAT environment.
   1. TBD: The exact steps for this are still being determined. It may be necessary to use the Configure pages in Jenkins to set that specific tag to be in use.
4. Trigger a Jenkins build to UAT.
   1. Log in at build.openlmis.org and click the Schedule a Build button (on which job(s))?
   2. ...wait for Jenkins CI/CD to run the build and deploy it to the UAT environment...
   3. Confirm that the build completes successfully.
      1. You can watch the status at build.openlmis.org. If there are any errors, stop and debug those issues.
5. Tag the images on Docker Hub with the same release tag.
   1. TBD: The steps for applying this tag are still being determined. It may be necessary to manually publish each image to Docker Hub and manually add the tag.
   2. Confirm that the build has published images to Docker Hub tagged with your release tag.
      1. Look on the Tags page of each repository, eg https://hub.docker.com/r/openlmis/requisition/tags/.
6. Confirm that the UAT site is running your release.
   1. Look at the UAT site (uat.openlmis.org) and test out an area of functionality so you can confirm that the latest features for this release are present.
7. Load the Demo Data, if needed.
   1. For 3.0 Beta, we will manually run a command-line script to load the demo data into the UAT environment. In the future, we ultimately want Jenkins to load the demo data into the UAT environment.

Once all these steps are completed and verified, the release process is complete. At this point you can conduct communication tasks such as sharing the URL and Release Announcement to stakeholders. Congratulations!