| Note |
|---|
This guide is obsolete. Use Releasing a Module from Bamboo instead. |
...
| Note |
|---|
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.
...
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/helpdesk. Once you have a username and password to the maven repository, you can specify your username and password in settings.xml (in your ~/.m2 directory):
| Code Block |
|---|
<settings>
<servers>
<server>
<id>openmrs-repo</id>
<username>yourusername</username>
<password>yourpassword</password>
</server>
<server>
<id>openmrs-repo-modules</id>
<username>yourusername</username>
<password>yourpassword</password>
</server>
<server>
<id>openmrs-repo-releases</id>
<username>yourusername</username>
<password>yourpassword</password>
</server>
<server>
<id>openmrs-repo-snapshots</id>
<username>yourusername</username>
<password>yourpassword</password>
</server>
</servers>
</settings> |
...
| Note |
|---|
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:
| Code Block |
|---|
<scm> <connection>scm:git:git@githubhttps://github.com:/openmrs/openmrs-module-yourmoduleid.git<yourmoduleid</connection> <developerConnection>scm:git:git@githubhttps://github.com:/openmrs/openmrs-module-yourmoduleid.git<yourmoduleid</developerConnection> <url>scm:git:git@github<url>https://github.com:/openmrs/openmrs-module-yourmoduleid.git<yourmoduleid</url> </scm> |
Use the <distributionManagement> section your module's root pom.xml to tell it where it should deploy the module artifacts to:
...
| Code Block |
|---|
<build> <pluginManagement> <plugins> ... <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-release-plugin</artifactId> <version>2.3.2<5</version> <configuration> <autoVersionSubmodules>true</autoVersionSubmodules> <tagNameFormat>@{project.version}</tagNameFormat> </configuration> </plugin> </plugins> </pluginManagement> </build> |
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.)
...
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.)After doing the above, the compiled artifact for the tag you just created will be available in (TODO: check this) the "target" folder of your top-level maven repository. You can take this file and upload it to modules.openmrs.org.
Troubleshooting
- If your module contents are not published to Nexus repository due to an error during mvn release:perform
The versions of the pom files have been incremented to a new version with the tag snapshot added, for example 2.3-SNAPSHOT.- Edit the POM files to contain the version that you want to deploy e.g., 2.2.
- Run mvn deploy