Configuring a Plan to Release from Bamboo

Changes in the repository

1) Change the SCM tag of your pom file to use SSL.

Example:

<scm> <connection>scm:git:git@github.com:openmrs/openmrs-module-allergyapi.git</connection> <developerConnection>scm:git:git@github.com:openmrs/openmrs-module-allergyapi.git</developerConnection> <url>https://github.com/openmrs/openmrs-module-allergyapi.git</url> </scm>

 

2) Make sure to set the correct distributionManagement for your project:

<distributionManagement> <repository> <id>openmrs-repo-modules</id> <name>OpenMRS Nexus Modules</name> <url>http://mavenrepo.openmrs.org/nexus/content/repositories/modules</url> </repository> <snapshotRepository> <id>openmrs-repo-snapshots</id> <name>OpenMRS Nexus Snapshots</name> <url>http://mavenrepo.openmrs.org/nexus/content/repositories/snapshots</url> </snapshotRepository> </distributionManagement>

 

3) Check the release plugin configuration

It cannot have a 'pushChanges=false', and the tag name format should be set to the OpenMRS standard.

<pluginManagement> <plugin> <artifactId>maven-release-plugin</artifactId> <version>2.4.2</version> <configuration> <!-- remove the next line if it exists --> <pushChanges>false</pushChanges> <!-- add this line if it does not exist --> <tagNameFormat>@{project.version}</tagNameFormat> </configuration> </plugin> </pluginManagement>

 

4) If you want to use the version of modules and dependencies defined in the refapp distro pom:

4.1) Add to your parent pom:

<properties> <distro.groupId>org.openmrs.distro</distro.groupId> <distro.artifactId>referenceapplication</distro.artifactId> <distro.version>2.1-SNAPSHOT</distro.version> </properties> <dependencyManagement> <dependencies> <!-- Importing versions from refapp distro --> <dependency> <groupId>${distro.groupId}</groupId> <artifactId>${distro.artifactId}</artifactId> <version>${distro.version}</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement> ... <pluginManagement> <plugin> <artifactId>maven-release-plugin</artifactId> <version>2.4.2</version> <configuration> <!-- refapp distro contains SNAPSHOT dependencies --> <allowTimestampedSnapshots>true</allowTimestampedSnapshots> </configuration> </plugin> </pluginManagement>

4.2) Delete all the other dependencies in DependencyManagement already defined.

For each dependency of your omod and api that belongs to the distro, make sure it's provided or test scoped.

Keep the properties used to generate the config.xml file for your omod.

4.3) Confirm your plugin still ships the right dependencies

Generate a dependency tree of both versions (before the changes and after), and make sure the scope and the dependencies are correct. If it changed, try to identify what caused it.

Do a mvn package and confirm that inside omod/target/your module-1.0-SNAPSHOT/lib/ it's only shipping what it should include. If not, find the dependency added and change its scope to provided or test.

4.4) Make sure to update the register of modules using it.

(temporarily it's in openmrs-contrib-bamboo repo)

Creating a new build with a release stage:

1) Clone the Release test module build

 

2) Change the plan configuration

When selecting the plan, Actions/Configure plan. Make sure to click in the plan level again in the configuration mode.

2.1) Plan details tab

Add a link to the Releasing a Module from Bamboo page in the plan config. For example, 'More details of the release in https://openmrs.atlassian.net/wiki/x/Mi9YAQ'

2.2) Repositories tab, 'Git' repository

Change it to point to your repository.

2.3) Variables tab

  • Delete refapp.distro.dev.branch variable

  • Change maven.release.version to the next version that should be released (e.g, if your pom is 1.0-SNAPSHOT, this variable should be 1.0)

  • Change refapp.distro.property to the property of this module in the refapp distro pom file. If it's not part of the distro, delete this variable.

2.4.) Update Java version

Make sure you are using the correct java version in both the first stage and the release stage (controlled by the JAVA_HOME variable):

To run in JDK 7, you can just remove the JAVA_HOME variable in the release prepare/perform task (or use JAVA_HOME=${bamboo.capability.system.jdk.openjdk-7-jdk}).

2.5) Dependencies tab

If your build is going to trigger other plans, make sure to add to its dependencies. 

2.6) Handle Test cases during the build

If your module doesn't have any test cases, then Goto Configuration → Tasks → Maven 3 X. Then clear the selection of the "The build will produce test results". Otherwise you might get the build failures. 

2.7) Refapp distro release tasks

If your module is not part of the refapp distro, make sure to delete the relevant tasks in the 'Release to maven' job of your build:

  • Retrieve next snaphot version

  • Update distro with the new version

Creating a manual stage for a build that already exists:

1) Add a link to the Releasing a Module from Bamboo page in the plan config

For example, 'More details of the release in https://openmrs.atlassian.net/wiki/x/Mi9YAQ'

2) Create the plan variables:

  • maven.development.version - leave it empty. It could be used to override the default value

  • maven.release.version: add the next release version of this module. Check the pom file in doubt. 

  • refapp.distro.property: only necessary if this module is part of the refapp distro. The maven property in the refapp distro pom file for this module.

If you are using Release test module as a guide, ignore the refapp.distro.dev.branch variable. It's there only for testing purposes.

 

 

3) In the plan configuration, add 'Release scripts' as the second repository:

This repository contains some scripts to execute the release.

 

4) Remove the polling trigger of the 'Release scripts' repository

 

5) Create a manual stage for the release:

 

6) Create the job for that stage

You can use Release module - Release to maven job as a reference.

6.1) Checkout task:

6.2) Release prepare/perform

Execute the release bash script from https://github.com/openmrs/openmrs-contrib-bamboo

If your build requires JDK 8, make sure to add JAVA_HOME=${bamboo.capability.system.jdk.openjdk-8-jdk} to the environment variables. 

6.3) Retrieve from the pom file what will be the next release

Save next version in the plan.

 

6.4) Retrieve the snapshot version to use in the next task

Only if this module is part of the refapp distro

 

 

6.5) Update version in the distro

Only if this module is part of the refapp distro

Execute the distro update bash script from https://github.com/openmrs/openmrs-contrib-bamboo

 

Creating a 'plan branch' to handle builds and releases of another branch (than master)

From the build configuration screen, click on the plan branches configuration

From there click on 'Create plan branch'

Bamboo will detect all the branches of the repository, pick the other-than-master branch off which you need to build/release:

Before clicking on 'Create', make sure that you enable the branch:

From this point everything works as usual once you have selected which branch to work on:

Update documentation

Make sure to add your module to Releasing a New Version of a Module.

If you do not have access to bamboo, ask OpenMRS Help Desk.

Resources

Module Release