Page Comparison

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:

...

Steps

When you are ready to create and publish a release (Note that version modifiers should not be used in these steps - e.g. SNAPSHOT):

...

1. Update the serviceVersion of GitHub's openlmis-service-util
2. Check Jenkins built it successfully
3. At Nexus Repository Manager, login and navigate to Staging Repositories.  In the list scroll till you find orgopenlmis-NNNN.  This is the staged release.
4. Close the repository, if this succeeds, release it.  More information.
5. Wait 1-2 hours for the released artifact to be available on Maven Central.  Search here to check:  https://search.maven.org/
6. In each OpenLMIS Service's build.gradle, update the dependency version of the library to point to the released version of the library (e.g. drop 'SNAPSHOT')

...

1. Do we need a release branch? For the 3.0 Beta release No, 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 and in Docker Hub.
   
   1. Look under the Releases tab of each repository, eg https://github.com/OpenLMIS/openlmis-requisition/releases.
   2. Look under Tags in each Docker Hub repository.  e.g. https://hub.docker.com/r/openlmis/requisition/tags/  .   You'll need to wait for the Jenkins jobs to complete and be succesfull so give this a few minutes.
      Note: After tagging each service, you may also want to change the serviceVersion again so that future commits are tagged on Docker Hub with a different tag. For example, after releasing '3.1.0' you may want to change the serviceVersion to '3.1.1-SNAPSHOT'. You need to coordinate with developers on your component to make sure everyone is working on 'master' branch towards that same next release.
   3. On Jenkins, identify which build was the one that built and published to Docker/Maven the release.  Press the Keep the build forever button.

...

1. For each of the services deployed as a the new version on DockerHub, update the version in the docker-compose.yml file to the version you're releasing. See the lines under "services:" → serviceName → "image: openlmis/requisition-refui:3.0.0-beta-SNAPSHOT" and change that last part to the new version tag for each service.
2. Commit this change and tag the openlmis-ref-distro repo with the release being made.

...

1. Edit collect-docs.py to change links to pull in specific version tags of README files. In that script, change a line like urllib.urlretrieve("https://raw.githubusercontent.com/OpenLMIS/openlmis-referencedata/master/README.md", "developer-docs/referencedata.md") to urllib.urlretrieve("https://raw.githubusercontent.com/OpenLMIS/openlmis-referencedata/v3.0.0/README.md, "developer-docs/referencedata.md")
2. To make your new version visible in the "version" dropdown on ReadTheDocs, it has to be set as "active" in the admin settings on readthedocs (admin -> versions -> choose active versions). Once set active the link is displayed on the documentation page (it is also possible to set default version).

...

1. For each of the services deployed as a the new version on DockerHub, update the version in the docker-compose.yml file to the version you're releasing.
2. Commit this change. (You do not need to tag this repo because it is only used by Jenkins, not external users.)

...

1. Wait about 1 minute between starting each job
2. Confirm UAT has the deployed service.  e.g. for the auth service:  http://uat.openlmis.org/auth  check that the version is the one chosen.

...

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!

Updating a Component ServiceVersion

Each component is always working towards some future release, version X.Y.Z-SNAPSHOT. A component may change what version it is working towards, and when you update the serviceVersion of that component, the other items below need to change.

These steps apply when you change a component's serviceVersion (changing which -SNAPSHOT the codebase is working towards):

...

• See Step 3 above for details.

...

• See Step 5 above for details.
• Use a commit message that explains your change. EG, "Upgrade to 3.1.0-SNAPSHOT of openlmis-requisition component."

...

• See Step 7 above for details.
• Similar to above, please include a helpful commit message. (You do not need to tag this repo because it is only used by Jenkins, not external users.)

...

• Similar to the steps above, see the lines under "services:" and change its version to the new snapshot.
• You do not need to tag this repo. It will be used by Jenkins for subsequent contract test runs.

...

Moved into Developer Docs: http://docs.openlmis.org/en/latest/developer-docs/versioningReleasing.html#rolling-a-release