Wiki Spaces

Documentation
Projects
Resources

Get Help from Others

Q&A: Ask OpenMRS »
Discussion: OpenMRS Talk »
Real-Time: IRC Chat

Documentation

Skip to end of metadata
Go to start of metadata
On this page

 

Summary

Here's a quick summary of being Platform release manager (from Darius Jazayeri):

  1. Pick some tickets and kick others out of the release
  2. Keep an eye on those tickets, looking for unassigned & those assigned with no movement, occasionally pinging folks to see what's needed to move things along.
  3. For tickets awaiting to be reviewed and whose reviews are small, you can go ahead and review them yourself.
  4. Pull together the release (an hour or two of time)
    • Preliminary testing
    • Releasing an alpha release
  5. Oversee subsequent releases as described on the Release Process page.

Releases Process Checklist

This checklist provides a brief summary of the major steps during a release process. Some steps may be a single action while others may have more than one action 

1. Ensure that all issues and tickets are reviewed, committed or moved to later versions
2. Run LiquibaseRunner against the latest snapshot with all changes
3. Tag and Release the platform version
4. Build a WAR file using the distro-platform-project
5. Build a Standalone
6. Upload WAR file, Standalone and ReadME.txt to SourceForge
7. Update JIIRA with the new versions
8. Create Release Notes page
9. Create OpenMRS Wordpress Blog Post and Talk Announcement for release

Prior to Alpha Release

Prior to any release.

  1. Make an initial decision on what will be included on the release.

In most cases, this should be fairly clear from the road map; however, some projects may be a little behind schedule and a decision made whether they can be properly resourced/sped up to meet the release timeline or need to be bumped to a later release. You do not need to do all of the work of making these decision (the community should do that), but you should help ensure that the discussion occurs and you are the final arbiter for these decisions.

Features that have been committed but are not going to be in the release either need to be removed from the code or feature-toggled off.

Hold a Release Prioritization Meeting to prioritize tickets and finalize which will be included in the release as well as ten minor tickets that will be included in the release.

  1. Decide on what module(s) will be bundled with the release.
  2. Check those modules JIRA projects for any outstanding tickets and potentially hold prioritization meeting for them as well

Determining which modules are included in the release:

  • OpenMRS Platform includes core (required) modules and the REST Web Services module
     
  • OpenMRS is largely comprised of modules, including the app framework, UI framework, etc.  Many of these will be unchanged from one release to the next; however,  creating an alpha release of OpenMRS is the time to consider which modules should be removed and which might get added.  Core modules are required; however, bundled modules requirements vary. In most cases, you can simply continue with the bundled modules from the last release; however, there may be new modules that are candidates for bundling or existing bundled modules that should come out. Again, this should be a community decision, but your job is to ensure that the discussion takes place and to serve as the final arbiter for any dispute(s).
  1. Announce the upcoming Unsupported Releases (EOL) for the line of releases two back. (e.g. if you're releasing 1.7, announce EOL for 1.4.x)

Note:

  • Before an alpha release, all New Feature tickets should either be Closed or at least in a Post Commit state. The same goes for Blocker tickets.
  • You can perform the branching and releasing process either manually or by using the maven-release-plugin.
  • You will need to have an OpenMRS ID to create the required wiki pages and an OpenMRS Word Press account to create the release blog post. If you need an account, open a ticket to request it.
  • You will also need a SourceForge account to be able to upload files. This account needs to be associated with the OpenMRS project. If it isn't, open a ticket to request the association.
  • We recommend trying upgrading from various previous releases to your release mainly for the major release so that if there are any issues, they can be dealt with before the release.

Alpha Release

An alpha is a feature-complete release but is not yet verified to be bug free.

  1. There are two ways of branching for the release:
    1. Option 1: Automatic Maven way:
      1. Run mvn release:branch -DbranchName=1.8.x -Dusername=<scm-username> -Dpassword=<scm-password>
        • The username/password can be omitted if the subversion credentials are cached.
      2. At the interactive prompts, enter the following:
        New trunk development version: 1.9.0-SNAPHOT
        • To run in non-interactive mode, include the following with the release:branch command:
          -B -DdevelopmentVersion=1.9.0-SNAPSHOT
      3. If a failure occurs, the local changes can be reverted by running mvn release:clean
    2. Option 2: Manually:
      1. Create the release branch: e.g. 1.8.x.

      2. In the master branch, update the version to the next minor version, and commit

  2. Checkout the maintenance branch e.g 1.8.x
  3. Update the branches section in the .travis.yml to match the branch name so that travis builds can be triggered for pull requests created against the branch.
  4. Create a bamboo plan on ci.openmrs.org
    1. clone the prior minor release branch under https://ci.openmrs.org/browse/TRUNK
    2. modify Plan Configuration, Repositories, Branch to be the new branch name, e.g. 1.8.x
  5. Add or Update any bundled modules you wish to include before creating the tag and then Commit the changes.
  6. Run mvn clean install, verify all tests are passed and no changes to be committed.
  7. Do some last minute rudimentary testing. See Testing Releases.
  8. Announce on the Development Talk category that you are about to tag a release and make sure that everyone is prepared.
  9. There are three ways of tagging the release:
    1. Option 1: Let our CI server do the release. Our CI plans are set up with a manual "Release to maven" stage. See example. When you run that stage you would set variables like maven.release.version=2.1.0-alpha and maven.development.version=2.1.0-SNAPSHOT. This will also deploy files to the maven repository, hence making step 10-11 unnecessary. https://ci.openmrs.org
    2. Option 2: Automatic Maven way: (DARIUS: THIS DID NOT WORK WHEN I TRIED IT FOR 2.1.0-alpha)
      1. Run mvn release:prepare -Dusername=<scm-username> -Dpassword=<scm-password>
        • The username/password can be omitted if the subversion credentials are cached.
      2. At the interactive prompts, enter the following:
        Release version: 1.8.0-alpha
        Tag name: 1.8.0-alpha
        Development version: 1.8.0-SNAPSHOT
        • To run in non-interactive mode, include the following with the release:prepare command:
          -B -DreleaseVersion=1.8.0-alpha -Dtag=1.8.0-alpha -DdevelopmentVersion=1.8.0-SNAPSHOT
      3. If a failure occurs, the release changes can be reverted by running mvn release:rollback, but committed tags will need be to removed manually.
        • If no changes have been committed to subversion, the release can also be cleaned up using mvn release:clean
    3. Option 3: Manually:
      1. Change the values of the version tags in the pom files to be '1.8.0-alpha' the values of the scm URLs in the pom files to point to the new tag's location in the repository.
      2. Tag the branch with the name 1.8.0-alpha. (Using the SVN Repository View in subclipse: right-click --> SVN Branch/tag). Remember to add any bundled modules you wish to include before creating the tag.
      3. In the 1.8.x branch, change the values of the version tags in the pom files back to "1", "8", "0", and modifier of "SNAPSHOT" e.g 1.8.0-SNAPSHOT, change the values of the scm URLs in the pom files to point to the 1.8.x branch's location in the repository. Commit the changes.
  10. Check out the '1.8.0-alpha' tag and use it to build the archives with the maven 'package' goal
  11. If you did not release from bamboo with option a in step 9 above, deploy the files to maven repository with the command mvn clean deploy --batch-mode
  12. Prepare to release a platform by setting versions of modules to be included in the platform at https://github.com/openmrs/openmrs-distro-platform/. Edit properties in the pom.xml file for the corresponding version branch 1.10.x, 1.11.x, etc. Use the latest released versions of modules.
  13. Release the platform using the bamboo release button of the corresponding platform version, see https://ci.openmrs.org/browse/OP
  14. Create a war file by building the openmrs-distro-platform and upload the war file to  OpenMRS Download Files
  15. Create the Standalone. See the Standalone readme.txt file for how to build and package the standalone. Before you build the standalone please include the latest version of the CIEL dictionary by updating mvp-data.sql. After the standalone is packaged, add bundled modules to the war in openmrs-standalone/tomcat/webapps/openmrs-standalone.war/WEB-INF/bundledModules.
  16. Create the alpha release notes page at Release/Prelease Notes using all commits to trunk since the last release. e.g. Release Notes 1.8.0 Alpha
  17. Create the read me files, you can pick the ones from the prior releases at OpenMRS Download Files on sourceforge and edit it accordingly by updating the versions.
  18. Post an announcement on the Developing category on OpenMRS Talk.
  19. Create a release blog post on OpenMRS.org using your WordPress account. If you need an account, create a help desk case at https://help.openmrs.org/customer/portal/emails/new
  20. Send an announcement to the module author mailing list about any new features that effect modules (API changes, new features) and encouraging module authors to test their modules against the new version of OpenMRS.
  21. In the master branch, create a new liquibase update file for the next major version, and include it in the liquibase-update-to-latest.xml file. For instance, if the next major version is 2.2, create a file named liquibase-update-to-2.2.xml and include it in this file.

A release is ready to go from alpha to beta when preliminary testing has been completed and any bugs squashed (a minimum of rudimentary testing, ideally as many steps in the complete testing list as possible). If large bugs are found and squashed, alpha-2, alpha-3, etc. may be released to aid testers as needed.

Releasing additional alpha releases is up to the release manager. Going from alpha to beta does not require community discussion and is up to the release manager, but should be done only after the release manager has confirmed with testers that all known bugs have been squashed.

Beta Releases

A beta is a release that is ready to be tested by a larger group of people. Obvious bugs found in the alpha have been found and fixed.

Be sure to examine all outstanding tickets for the release milestone. By the time a beta release is being considered, all of the tickets assigned to the release milestone should have a clear trajectory (either be moved to a later release or have plans in place to address the issue by the full release).

  1. Checkout the maintenance branch e.g 1.8.x
  2. Add or Update any bundled modules you wish to include before creating the tag and then Commit the changes.
  3. Run mvn clean install, verify all tests are passed and no changes to be committed.
  4. Do some last minute rudimentary testing. See Testing Releases
  5. Announce on the Development Talk category that you are about to tag a release and make sure that everyone is prepared.
  6. There are three ways of tagging the release:
    1. Option 1: Let our CI server do the release. See description in the Alpha Releases section of this page. This will also deploy files to the maven repository, hence making steps 7-8 unnecessary.
    2. Option 2: Automatic Maven way:
      1. Run mvn release:prepare -Dusername=<scm-username> -Dpassword=<scm-password>
        • The username/password can be omitted if the subversion credentials are cached.
      2. At the interactive prompts, enter the following:
        Release version: 1.8.0-beta
        Tag name: 1.8.0-beta
        Development version: 1.8.0-SNAPSHOT
        • To run in non-interactive mode, include the following with the release:prepare command:
          -B -DreleaseVersion=1.8.0-beta -Dtag=1.8.0-beta -DdevelopmentVersion=1.8.0-SNAPSHOT
      3. If a failure occurs, the release changes can be reverted by running mvn release:rollback, but committed tags will need be to removed manually.
        • If no changes have been committed to subversion, the release can also be cleaned up using mvn release:clean
    3. Option 3: Manually:
      1. Change the values of the version tags in the pom files to be '1.8.0-beta' the values of the scm URLs in the pom files to point to the new tag's location in the repository.
      2. Tag the branch with the name 1.8.0-beta. (Using the SVN Repository View in subclipse: right-click --> SVN Branch/tag). Remember to add any bundled modules you wish to include before creating the tag.
      3. In the 1.8.x branch, change the values of the version tags in the pom files back to "1", "8", "0", and modifier of "SNAPSHOT" e.g 1.8.0-SNAPSHOT, change the values of the scm URLs in the pom files to point to the 1.8.x branch's location in the repository. Commit the changes.
  7. If you did not release from bamboo with option 1 in step 6 above, check out the '1.8.0-beta' tag and use it to build the archives with the maven 'package' goal
  8. If you did not release from bamboo with option 1 in step 6 above, deploy the files to maven repository with the command mvn clean deploy --batch-mode
  9. Prepare to release a platform by setting versions of modules to be included in the platform at https://github.com/openmrs/openmrs-distro-platform/. Edit properties in the pom.xml file for the corresponding version branch 1.10.x, 1.11.x, etc. Use the latest released versions of modules.
  10. Release the platform using the bamboo release button of the corresponding platform version, see https://ci.openmrs.org/browse/OP
  11. Create a war file by building the openmrs-distro-platform and upload the war file to  OpenMRS Download Files
  12. Create the Standalone. See the Standalone readme.txt file for how to build and package the standalone. Before you build the standalone please include the latest version of the CIEL dictionary by updating mvp-data.sql. After the standalone is packaged, add bundled modules to the war in openmrs-standalone/tomcat/webapps/openmrs-standalone.war/WEB-INF/bundledModules.
  13. Create the beta release notes page under Prereleases using all commits to the release branch since the last release. e.g. Release Notes 1.8.0
  14. Create the read me files, you can pick the ones from the prior releases at OpenMRS Download Files on Sourceforge and edit it accordingly by updating the versions.
  15. Send an announcement to the implementers and developers mailing lists.

Testing a Beta Release

  • Rudimentary testing should have already been done when creating the beta version.
  • Recruit volunteers to help test the beta version, including at least one implementation. Ideally, testers would run through all items in the list of application-level tests "More Complete Testing Process" on the Testing Releases page. It may help to copy this list to a shared document (e.g., Google doc or Wave) and have testers strike out tests that have been completed.
  • Consider adding to the More Complete Testing Process list to cover any bugs discovered at the application level (that may not be completely covered by unit testing) which are not currently included in that list.

Going from beta to a release candidate or full release requires that testing scripts have been completed and the system formally exercised by at least one (ideally two or more) implementation.

The decision to go from beta to release candidate or final release should be led by the release manager but agreed by the developer community (via mailing list or dev call).

Release Candidates

A release candidate is only needed when non-trivial changes were required during the beta phase. If the beta release was tested and no significant changes were needed, then you can proceed directly to a full release.

  1. Checkout the maintenance branch e.g 1.8.x
  2. Add or Update any bundled modules you wish to include before creating the tag and then Commit the changes.
  3. Run mvn clean install, verify all tests are passed and no changes to be committed.
  4. Do some last minute rudimentary testing. See Testing Releases.
  5. There are three ways of tagging the release:
    1. Option 1: Automatic Maven way:
      1. Run mvn release:prepare -Dusername=<scm-username> -Dpassword=<scm-password>
        • The username/password can be omitted if the subversion credentials are cached.
      2. At the interactive prompts, enter the following:
        Release version: 1.8.0-RC
        Tag name: 1.8.0-RC
        Development version: 1.8.0-SNAPSHOT
        • To run in non-interactive mode, include the following with the release:prepare command:
          -B -DreleaseVersion=1.8.0-RC -Dtag=1.8.0-RC -DdevelopmentVersion=1.8.0-SNAPSHOT
      3. If a failure occurs, the release changes can be reverted by running mvn release:rollback, but committed tags will need be to removed manually.
        • If no changes have been committed to subversion, the release can also be cleaned up using mvn release:clean
    2. Option 2: Manually:
      1. Change the values of the version tags in the pom files to be '1.8.0-RC' the values of the scm URLs in the pom files to point to the new tag's location in the repository.
      2. Tag the branch with the name 1.8.0-RC. (Using the SVN Repository View in subclipse: right-click --> SVN Branch/tag). Remember to add any bundled modules you wish to include before creating the tag.
      3. In the 1.8.x branch, change the values of the version tags in the pom files back to "1", "8", "0", and modifier of "SNAPSHOT" e.g 1.8.0-SNAPSHOT, change the values of the scm URLs in the pom files to point to the 1.8.x branch's location in the repository. Commit the changes.
    3. Use the bamboo release button. This will also deploy files to the maven repository, hence making step 7 unnecessary. https://ci.openmrs.org
  6. Check out the '1.8.0-RC' tag and use it to build the archives with the maven 'package' goal
  7. If you did not release from bamboo with option c in step 5 above, deploy the files to maven repository with the command mvn clean deploy --batch-mode
  8. Prepare to release a platform by setting versions of modules to be included in the platform at https://github.com/openmrs/openmrs-distro-platform/. Edit properties in the pom.xml file for the corresponding version branch 1.10.x, 1.11.x, etc. Use the latest released versions of modules.
  9. Release the platform using the bamboo release button of the corresponding platform version, see https://ci.openmrs.org/browse/OP
  10. Create a war file by building the openmrs-distro-platform and upload the war file to  OpenMRS Download Files
  11. Create the Standalone. See the Standalone readme.txt file for how to build and package the standalone. Before you build the standalone please include the latest version of the CIEL dictionary by updating mvp-data.sql. After the standalone is packaged, add bundled modules to the war in openmrs-standalone/tomcat/webapps/openmrs-standalone.war/WEB-INF/bundledModules.
  12. Create the beta release notes page atRelease/Prelease Notes using all commits to the release branch since the last release. e.g. Release Notes 1.8.0 RC
  13. Create the read me files, you can pick the ones from the prior releases at OpenMRS Download Files on sourceforge and edit it accordingly by updating the versions.
  14. Send an announcement to the implementers and developers mailing lists.

Going from release candidate to full release requires that testing scripts have been completed and the system formally exercised by at least two or more implementations. The decision to go from release candidate to final release should be led by the release manager but agreed by the developer community (via mailing list or dev call).

Final Release

A true "Release" is deemed tested and worthy of production environments.

Review all existing tickets. Be certain that all tickets assigned to this release milestone have been addressed and that there aren't any straggling tickets for this milestone or previous milestones.

  1. Checkout the maintenance branch e.g 1.8.x
  2. You may have to prepare any pointed out module(s) to be bundled with openmrs, we are currently including only the rest webservices module, the bundled module will be added to the war file immediately after you have built one after tagging by creating a folder called bundledModules and adding the module inside it then open the war file with any archive manager software of your preference and then drug and drop the bundledModules folder containing the module(s) into /WEB-INF/ of the war file. Otherwise use https://github.com/openmrs/openmrs-distro-platform to release the OpenMRS Platform
    1. Check each module's page in the module repository to find the latest version.  You should use the latest version unless a module developer specifically requests that an earlier version be bundled.
  3. Run mvn clean install, verify all tests are passed and no changes to be committed
  4. Do some last minute rudimentary testing. See Testing Releases
  5. There are three ways of tagging the release:
    1. Option 1: Automatic Maven way:
      1. Run mvn release:prepare -Dusername=<scm-username> -Dpassword=<scm-password>
        • The username/password can be omitted if the subversion credentials are cached
      2. At the interactive prompts, enter the following:
        Release version: 1.8.0
        Tag name: 1.8.0
        Development version: 1.8.1-SNAPSHOT
        • To run in non-interactive mode, include the following with the release:prepare command:
          -B -DreleaseVersion=1.8.0 -Dtag=1.8.0 -DdevelopmentVersion=1.8.1-SNAPSHOT
      3. If a failure occurs, the release changes can be reverted by running mvn release:rollback, but committed tags will need be to removed manually
        • If no changes have been committed to subversion, the release can also be cleaned up using mvn release:clean
      4. Deploy the artifacts to the maven repo, make sure you have username and password configured for the openmrs-repo-releases maven repository in the .m2/settings.xml file.
        • Run mvn release:perform
    2. Option 2: Manually:
      1. Change the values of the version tags in the pom files to be '1.8.0' the values of the scm URLs in the pom files to point to the new tag's location in the repository.
      2. Tag the branch with the name 1.8.0. (Using the SVN Repository View in subclipse: right-click --> SVN Branch/tag). Remember to add any bundled modules you wish to include before creating the tag.
      3. In the 1.8.x branch, change the values of the version tags in the pom files to "1", "8", "1", and modifier of "SNAPSHOT" e.g 1.8.1-SNAPSHOT, change the values of the scm URLs in the pom files to point to the 1.8.x branch's location in the repository. Commit the changes.
    3. Use the bamboo release button. This will also deploy files to the maven repository, hence making step 7 unnecessary. https://ci.openmrs.org
  6. Check out the '1.8.0' tag and use it to build the archives with the maven 'package' goal
  7. If you did not release from bamboo with option c in step 5 above, deploy the files to maven repository with the command mvn clean deploy --batch-mode
  8. Prepare to release a platform by setting versions of modules to be included in the platform at https://github.com/openmrs/openmrs-distro-platform/. Edit properties in the pom.xml file for the corresponding version branch 1.10.x, 1.11.x, etc. Use the latest released versions of modules.
  9. Release the platform using the bamboo release button of the corresponding platform version, see https://ci.openmrs.org/browse/OP
  10. Create a war file by building the openmrs-distro-platform and upload the war file to  OpenMRS Download Files
  11. Create the Standalone. See the Standalone readme.txt file for how to build and package the standalone. Before you build the standalone please include the latest version of the CIEL dictionary by updating mvp-data.sql. After the standalone is packaged, add bundled modules to the war in openmrs-standalone/tomcat/webapps/openmrs-standalone.war/WEB-INF/bundledModules.
  12. Create the release notes page as a child of Platform Release Notesand include JIRA filters showing all closed tickets (e.g.Platform Release Notes 1.11.0)
  13. Create the read me files, you can pick the ones from the prior releases at OpenMRS Download Files on sourceforge and edit it accordingly by updating the versions.
  14. Create a help desk case with https://help.openmrs.org/customer/portal/emails/new at a minimum of one working day prior to the scheduled release providing download links. DO NOT mark Impact as anything other than "Routine." 
    Use the following template for description (replace 2.0.5 with the correct maintenance version, the release date & time and the JIRA url, which you can determine from https://issues.openmrs.org/browse/TRUNK/?selectedTab=com.atlassian.jira.jira-projects-plugin:versions-panel):

    In preparation for the release of OpenMRS Platform 2.0.5 on 21/04/2017 10:00 UTC please do:
    1. Update SCRAP to allow automated bug reports to be received for Platform 2.0.5 found in JIRA at https://issues.openmrs.org/browse/TRUNK/fixforversion/21343
    2. Update http://openmrs.org/help/report-a-bug/ to allow bug reports for Platform 2.0.5.
    3. Update http://openmrs.org/download/ to point to Platform 2.0.5 standalone at http://sourceforge.net/projects/openmrs/files/releases/OpenMRS_Platform_2.0.5/openmrs-standalone-2.0.5.zip/download 
    4. Update http://openmrs.org/download/ to point to Platform 2.0.5 war at http://sourceforge.net/projects/openmrs/files/releases/OpenMRS_Platform_2.0.5/openmrs.war/download
  15. If the current Reference Application is based on a SNAPSHOT of the version you just released, then update the reference application to build with your just-released version. (You can check and fix the openMRSVersion property in https://github.com/openmrs/openmrs-distro-referenceapplication/blob/master/pom.xml. For example if the property was set to 1.11.0-SNAPSHOT and you just released 1.11.0, change the property to 1.11.0.)
  16. Update the TRUNK project in JIRA with this maintenance release version number, if it's not already there. This can be done by the TRUNK project administrators/approvers and allows "Fix Version" and "Affects Version" to be specified for this release.

  17. Once helpdesk confirms all is set for the release, make an announcement at https://talk.openmrs.org/c/software/platform and/or https://talk.openmrs.org/c/software/openmrs-2-x . Include information about Unsupported Releases (EOL) for the version two back. (e.g. if releasing 1.8.0, then 1.5.x is now EOL).
  18. Edit the wiki page Platform Release Notes so that it includes as content the release notes.

Maintenance Release

A maintenance release contains bug fixes and security patches for use between major releases, e.g., from 1.8.0 to 1.8.1. There is no branch to create. You just pick up where you left off in the current minor version series release branch.

  1. Write a post that announces the release date and modules to be included on Talk under Software category.
  2. Verify that there are no unreviewed open tickets against the version to be released. You can use this query https://goo.gl/WXqrI3 (adjust the fixVersion).
    1. Review/close tickets that are in Post Commit Review.
    2. Look carefully at In Progress tickets to see, if some of them have not been committed to a branch (back ported) already. You need to review/close such tickets as well. You can easily check, if any code was committed by searching for an issue id on a GitHub comparison page at https://github.com/openmrs/openmrs-core/compare/2.0.4...2.0.x (adjust the versions). 
    3. Move tickets to the next version that are In Progress or in Pre-Commit Review stage (use Manage Versions admin page for bulk moving of tickets, see the 4.a. step below).
  3. Create a new version for the next maintenance release. Using the Manage Versions in https://tickets.openmrs.org/plugins/servlet/project-config/TRUNK.
  4. Release the current maintenance version using the above admin page.
    1. When you release a version it will allow you to move non-closed tickets to the next version.
  5. Download the latest CIEL for OpenMRS 1.9.x (use 1.9.x regardless of the maintenance release version) as described here. Upload the version to our maven repository to be used in standalone by running:

    Adjust the version and the file parameters to match the downloaded version of CIEL.

  6. Update the CIEL version in standalone's pom.
  7. Prepare to release a platform by setting versions of modules to be included in the platform at https://github.com/openmrs/openmrs-distro-platform/. Edit properties in the pom.xml file for the corresponding version branch 1.10.x, 1.11.x, etc. Use the latest released versions of modules.
  8. Check if the branch to be released is green at https://ci.openmrs.org/browse/TRUNK and https://ci.openmrs.org/browse/OP
  9. Do some last minute rudimentary testing as described in Testing Releases on snapshot artifacts published by CI under e.g. https://ci.openmrs.org/browse/OP-OP2/latest/artifact.
  10. Release openmrs-core from CI by running the Release stage of the latest build for the corresponding branch at https://ci.openmrs.org/browse/TRUNK e.g. https://ci.openmrs.org/browse/TRUNK-OC2/latest (click the Play icon next to the Release stage on the left menu) 
  11. Once the release build turns green release the corresponding platform from CI at https://ci.openmrs.org/browse/OP e.g. https://ci.openmrs.org/browse/OP-OP2/latest
  12. In the file listing page on Sourceforge, open the recently released version, click the info "i" button next to the standalone to expand the details of the uploaded ZIP file. For "Download Button", type "OpenMRS Platform 2.0.5 Standalone". Under "Default Download For:" check all the option boxes. Click "Save" to save the settings.

  13. Create the release notes page as a child of Platform Release Notes and include JIRA filters showing all closed tickets (e.g. Platform Release Notes 1.11.1)
    • Use Finding Database Changes Between Releases to put the db changes into the release notes page.
    • Edit the Platform Release Notes page to include as content the new release notes page you just created, and updated it to give the new version number.
    • Update the Releases page to include the new platform release, (replacing the prior version in the release line this is a maintenance release in)
    • Update and modify the Downloads wiki page with the latest release notes page.
  14. Create a help desk case with https://help.openmrs.org/customer/portal/emails/new at a minimum of one working day prior to the scheduled release providing download links. DO NOT mark Impact as anything other than "Routine." 
    Use the following template for description (replace 2.0.5 with the correct maintenance version, the release date & time and the JIRA url, which you can determine from https://issues.openmrs.org/browse/TRUNK/?selectedTab=com.atlassian.jira.jira-projects-plugin:versions-panel):

    In preparation for the release of OpenMRS Platform 2.0.5 on 21/04/2017 10:00 UTC please do:
    1. Update SCRAP to allow automated bug reports to be received for Platform 2.0.5 found in JIRA at https://issues.openmrs.org/browse/TRUNK/fixforversion/21343
    2. Update http://openmrs.org/help/report-a-bug/ to allow bug reports for Platform 2.0.5.
    (Do not include the rest, if it is not the latest LTE branch release)
    3. Update http://openmrs.org/download/ to point to Platform 2.0.5 standalone at http://sourceforge.net/projects/openmrs/files/releases/OpenMRS_Platform_2.0.5/openmrs-standalone-2.0.5.zip/download 
    4. Update http://openmrs.org/download/ to point to Platform 2.0.5 war at http://sourceforge.net/projects/openmrs/files/releases/OpenMRS_Platform_2.0.5/openmrs.war/download
  15. Once helpdesk confirms all is set for the release, create a blog post on OpenMRS.org using your WordPress account. If you need an account, create a help desk case at https://help.openmrs.org/customer/portal/emails/new
  16. Write a post that announces the released on Talk under Software category.

About Release branches

A new release branch is created for each new major and minor release. (Reading Versioning would be helpful about now) So, for example, a new release branch is created when preparing to release version 2.0.0, or version 1.3.0. However, when preparing to release 1.3.1 (a maintenance-version increment), the release branch created at the time of 1.3.0 is used.

A new release branch needs to be created when the alpha is released. Generally, we have a soft schedule of releasing a new minor version every 2-3 months. So, approximately 2 months after the previous minor release is a good time to start proposing an alpha release and release branch creation. But remember that this is flexible, depending on what features are being developed.

Once a release branch has been created, no development ever takes place there. The only changes permitted are ones made to various bookkeeping files and changes merged in from trunk.

Troubleshooting

  • When running: mvn release:prepare You may also get an error message in validating the generated JavaDoc files, which you can resolve by adding  -Darguments="-Dmaven.javadoc.skip=true" to skip the validation process. However this does not work with Java 8
  • When releasing using the Automatic Maven method, you may some times get this error message: [ERROR] svn: MKACTIVITY of '/!svn/act/adeb5614-9496-4b46-b28e-eb5d1d6b3bc0': authorization failed: Could not authenticate to server: rejected Basic challenge (http://svn.openmrs.org). This is caused by an invalid svn user name or password. I also got the same error message when my user name and password were correct but the password had spaces in it. Resolving it required only changing my password to one which did not have spaces. But before you change your password, Ben suggests that you try enclosing it in double quotes and see if it works.
  • When errors occur while running: mvn release:prepare you may want to rollback the release process to fix them, then use mvn release:rollback. However this has to be followed by the manual deletion of the tag that was created in the local git environment.
  • There are also times when you may get this error message: [ERROR] Failed to execute goal org.apache.maven.plugins:maven-release-plugin:2.1:prepare (default-cli) on project openmrs: Can't release project due to non released dependencies : This is caused by having SNAPSHOT dependencies (outside the current build) which should be released before you can release the project. Their released artifacts should be deployed to Nexus (through release process or manually if necessary). Then the pom.xml should be updated with the release versions and the trunk pom.xml should be bumped to their next SNAPSHOT versions, if development is continuing.
  • When running: mvn clean deploy --batch-mode  You may get an error message like this: Failed to execute goal org.apache.maven.plugins:maven-deploy-plugin:2.5:deploy (default-deploy) on project openmrs: Failed to deploy artifacts: Could not transfer artifact ............ Failed to transfer file ......... Return code is: 401 -> [Help 1].  Solving this requires you to have a nexus repository account, under the openmrs-repo-releases section, in your maven settings.xml file which should be in your MAVEN_HOME folder. If this file does not already exist, you need to create one. See the example maven settings.xml file attached: settings-example-mvnrepo.xml.
  • When running: mvn clean deploy --batch-mode  You may also get an error message like: Failed to transfer file: .........  Return code is: 400    The reason is that the Maven nexus release repo does not allow redeployment by default. To enable that, you could logon nexus and select the release repo, then change the configuration to allow redeployment there. But be aware that any projects using the release artifact will ONLY download the artifact once and thus the artifact you redeployed may not be able to be consumed by the projects, which may cause a lot of troubles. The solution is to manually remove the cached release artifact under .m2/repository so that Maven can download the new one. Because of the disadvantage for the above approach, i just logged onto the nexus repository and manually deleted the successfully deployed artifacts. Then i was able to deploy again.
  • When running: mvn clean deploy --batch-mode  You may also get an error message like: [ERROR] Java heap space -> [Help 1].  To solve this, increase the memory for maven. On my mac, i just typed this on the same shell terminal where i was deploying from: export MAVEN_OPTS="-Xmx512m -Xms128m -XX:MaxPermSize=512m"
  • When you are deploying a module to nexus repository using: mvn clean deploy command  You may get an error message like [ERROR] Failed to execute goal org.apache.maven.plugins:maven-deploy-plugin:2.7:deploy (default-deploy) on project...Return code is: 401, ReasonPhrase:Unauthorized. To solve this you need to add a server for the module repo by adding the following with nexus repository credentials to the list of servers in the file /M2_HOME/settings.xml .

Tips

  • When doing release testing, creating standalone distributions can be a very quick and easy way.
  • No labels