Releasing OpenMRS Modules Using git and the Maven Release Plugin

[Wesley Brown]

Greetings,

Our team has been releasing a number of versions of our modules recently and we have created a process document to help us remember how to do it without messing up our branches.  We wanted to share it in case it could help others.  Note that this is just one of many release processes and not be the best; however it does work well for us.

This release process assumes that you have at least 2 branches: 

1. master: the current released version
   
2. develop: the development version

After testing the module and ensuring that your develop branch has all changes that you want to release:

1. Ensure that git links use git@github style scm urls (see the Jasper Module)
   
2. Enusre the pom.xml contains a maven-release-plugin definition (see the Jasper Module)
   
• Make sure that the following configuration settings are specified:
• <pushChanges>false</pushChanges>
  
• <localCheckout>true</localCheckout>
  
• These settings are required because the default behavior pushes the release commit and next development commit to the wrong branches.
3. git checkout develop
   
4. git branch release/vX.X.X
   
5. mvn release:prepare
• This does a number of things:
• Removes the -SNAPSHOT from the version
  
• Checks that you don't have any SNAPSHOT dependencies
  
• Builds the module and runs all tests
• Creates a new commit for the release version
• Creates a tag for the release commit
• Updates the version number for the next development cycle
• Creates a new commit for the next development cycle
6. git checkout vX.X.X 
• Checks out the tag created by release:prepare
7. mvn release:clean 
• Removes the backup files created by release:prepare
  
8. mvn delpoy 
• Deploys our release tag to nexus
  
• Note that you will need credentials for the OpenMRS nexus to do this.  Put these credentials into your ~/.m2/settings.xml file so that they are not stored publicly in your module pom.xml file.  Info on exactly how to do this can be found here: http://www.sonatype.com/books/nexus-book/reference/_adding_credentials_to_your_maven_settings.html.
9. git push --tags 
• Push any missing tags to github
  
10. git checkout develop
    
11. git merge --no-ff release/vX.X.X
    
• This merges the changes from the release branch, which should just be the updated version numbers
12. git checkout master
    
13. git merge --no-ff vX.X.X 
• Merge the tag (this is, what we released) into master
  
14. git push origin master
    
15. git branch -D release/vX.X.X
    
• We're done with the release branch so we can delete it.

If you want to add/update the module on the OpenMRS module site:

1. git checkout vX.X.X
   
2. mvn clean install
   
3. From module site:
   
1. Edit module
2. Add version
3. Select the .omod file that was just created. The file will be in the '<module root>/omod/target/' directory.
4. Save module

So that's the, um, "simple" release process... just 15 steps!  We welcome any feedback/questions.

-Wes Brown

[Mark Goodrich]

Thanks Wes,

It would be great to put this on the wiki somewhere.  We generally follow the same process, but I haven't formalized it into a set workflow.  It is interesting that you don't use the mvn  release:perform goal.  I've generally had mixed feeling about that goal as well, and sometimes I use it but sometimes I don't.  It is easy enough to do mvn deploy to accomplish what it does, and then you have more control.

Take care,
Mark

--
OpenMRS Developers: http://go.openmrs.org/dev
Post: d...@openmrs.org
Unsubscribe: dev+uns...@openmrs.org
Manage your OpenMRS subscriptions at https://id.openmrs.org/
 
 

[Darius Jazayeri]

Hi Wesley,

Thanks for sharing this.

Personally, on the modules that I work on, I've been following a simpler process. There's just a single master branch, and tags for releases, but I can use "mvn release:prepare" and "mvn release:perform" as-is so it's many fewer steps. I'll try to document this at some point.

-Darius

[Wesley Brown]

Hey Mark,

We did try and use mvn release:perform but found that it caused problems because we use git flow for our team branching strategy.  Also, even if it did work, it is extremely slow for us because it clones the tag from github rather than using the local one.

-Wes

[Mark Goodrich]

Yeah, I find the fact that it clones from the tag rather silly...  especially when it is easy enough to check out the tag locally and do a mvn deploy to do more or less the same thing...