All OpenMRS ID accounts have been reset.

Read more and change your password before signing in.
Icon

EXTENDED: OMRS14 Proposals due 30 April! Read more and submit a proposal at OpenMRS Talk.

Skip to end of metadata
Go to start of metadata
Icon

This guide assumes your module is maven-based, and stored in git. If you don't have a pom.xml file in your module, see Converting old code to Maven in before using this approach

Background

While you are doing development in a maven module, your module's working version ends in -SNAPSHOT. By default, this will start at 1.0-SNAPSHOT.

Releasing a new version of your module involves many steps (most of which are automated). Each of your module's pom.xml files (parent, api, omod) have a version that needs to be updated, the module needs to be tagged, built, tested, committed, deployed to the maven and module repositories, and then the numbers need to point to the next SNAPSHOT.

The Maven Release Plugin automates nearly all of this.

Prerequisites

Credentials to the maven repository (you need to do this once in your dev environment)

You need to have a login to mavenrepo.openmrs.org. (This does not use your OpenMRS ID.) You can request an account at http://go.openmrs.org/helpdeskOnce you have a username and password to the maven repository, you can specify your username and password in settings.xml (in your ~/.m2 directory):

If you're curious, you can see more details at Managing the Maven Repository.

Icon

If you don't want to type your username in clear text (note the password is saved in clear text to the file release.properties), you can try to set up maven password encryption.

Settings in pom.xml (you need to do this once for any module you release)

The <scm> section of your module's root pom.xml needs to point to the urls that the module lives at. (Note that the maven module archetype incorrectly defaults these to point to svn, so you need to change these to point at github.) For example:

Use the <distributionManagement> section your module's root pom.xml to tell it where it should deploy the module artifacts to:

Via <pluginManagement>, override some of the release plugin's configuration settings:

Don't forget to commit and push these configuration changes to github!

Doing the Release (the Maven part)

After configuring all the prerequisites, make sure you are pointing at the branch you want to release (normally "master") all your code is committed and pushed, and you have pulled the latest version from origin (and upstream, if relevant.)

From command line, run:

You will be asked what version number you want to release as. The default is usually correct, i.e. dropping -SNAPSHOT from the development version. 

Next, you will be asked what you want to tag this release as. The default is usually correct, i.e. the version you just released as, like "1.0".

Third, you will be asked for the next development version. The default (incrementing the last digit by one from the previous development version) is often correct, but don't be afraid to increase higher order numbers.

 (If you did not set the release plugin's configuration settings as described above, you will need to choose the same version numbers three times, and you'll need to change the tag from something like "mymodule-1.0" to "1.0".)

The release plugin will then do a lot work, (e.g. building, running tests, and tagging). If things go wrong at this point, you may do "mvn release:rollback" and delete the artifact from the releases section in github.  Note for Windows users: One thing that might go wrong is it just hangs at some point, as described here: http://stackoverflow.com/questions/3243755/maven-error-releasing-code-to-github-hangs-after-push. A solution involving some clever git ssh magic is also described in that SO entry. 

Assuming things went right, the next step is:

When this completes, the particular git revision will have been tagged, and its compiled artifacts will have been deployed to our maven repository.

Uploading to the Module Repository (the manual part)

(Unfortunately this last step is manual. If you're interested in automating it, please volunteer on the dev mailing list!)

The steps you ran above with the mvn release plugin will have created your official module-x.y.omod file under omod/target, and deployed this to our maven repository so that developers can access it programmatically. For implementers to be able to access it manually, you need to upload it to the Module Repository. (You can log in using your OpenMRS ID.)

  • No labels

5 Comments

  1. FYI: you cannot do release:prepare if you have any snapshot dependencies (for example I can't release:prepare htmlformentry19ext until openmrs-api 1.9 is in our nexus repository)

    Does anyone know if release:prepare works with modules whose source code is in git?

    1. Looks like release:prepare should work with git if you set up your <scm> in your pom correctly:

      http://maven.apache.org/scm/git.html

      (And I just noticed that the HFE pom still references svn... I will clean that up next week)

      1. Yes, it works great with git. (Also I edited the text to reflect this.)

  2. Not that this is helpful in this case, but it looks like you can flag the release plugin to allow snapshot dependencies, but only if they are timestamped...

    http://maven.apache.org/plugins/maven-release-plugin/prepare-mojo.html

  3. Does anybody know if there's a way to combine things so that every time I use the release plugin, it also does a mvn deploy?