Module Release

Owned by Ellen Ball
Last updated: Mar 26, 2020 by Cintia Del Rio
4 min read

So that others may use the module you develop, you must Release the module.

We recommend releasing your module to Bintray. Typically modules are released to a generic omod repository; some projects like OpenMRS code are release as maven repository. 

Artifacts published to the maven repository are used by developers and include module's Java API and an OMOD. The omod repository on the other hand is used to distribute modules to implementers, thus only OMODs are published there.

Implementers will typically find your module via the OpenMRS add-ons index, so you should get your module indexed there. (It can index modules from various distribution channels including Bintray.)

Release versioning

In OpenMRS we adopted the semantic versioning e.g. 1.2.3. As a guideline:

  • major new features or complete module rewrites should change the major version (1.2.3 -> 2.0.0)

  • minor new features should change the minor version (1.2.3 -> 1.3.0)

  • bugfixes should change the maintenance version (1.2.3 -> 1.2.4)

Community maintained modules

Community maintained modules are available at https://github.com/openmrs. For those modules developer artifacts are published to the dedicated OpenMRS maven repository at https://mavenrepo.openmrs.org. Compiled OMODs are published to the Bintray repository at https://bintray.com/openmrs/omod.

Thanks to the generosity of the JFrog company we have virtually unlimited space in the dedicated maven repository, but every new module adds some maintenance on us, thus modules are approved on case-by-case basis. All modules published to the OpenMRS maven repository are automatically published to the Bintray repository without any additional steps. However, it may take up to 3 hours to see the omod on Bintray; check this Bamboo build if that didn't happen. If you want to update some details of a module in Bintray, please ask via Talk.

Please see this page on how to setup a module and do releases to the OpenMRS maven repository.

All community supported module releases should be done through CI at https://ci.openmrs.org/.

Setup Bintray account for Maven

In order to be able to release to Bintray you need to create an open source account at https://bintray.com/signup/oss and set it up as follows.

  1. From your user profile page click "Add New Repository". Specify the name and type as "maven" and "Maven".

  2. Repeat the 1-st step, creating a new repository of type "Generic" and with name "omod".

  3. Add your Bintray credentials to maven's settings.xml as follows:

    <server> <id>bintray-[YOUR_USERNAME]-maven</id> <username>[YOUR_USERNAME]</username> <password>[YOUR_PASSWORD]</password> </server>

     

  4. After the first release of your module, you need to request for the module to be included in Bintray's JCenter repository so that it is publicly visible and can be fetched for example with SDK. See Bintray's instructions on how to do that.

  5. It is also possible to publish SNAPSHOT (development) versions of your module to Bintray. It is particularly useful, if you have a CI server. Refer to Bintray's docs on how to do that.

Setup Bintray maven release

In order to be able to release to Bintray you need to add the following snippets to pom.xml in your module (make sure there is only one scm and distributionManagement section in your pom.xml):

<scm> <connection>scm:git:https://github.com/[YOUR_GITHUB_USERNAME]/openmrs-module-[YOUR_MODULE_ID]</connection> <developerConnection>scm:git:https://github.com/[YOUR_GITHUB_USERNAME]/openmrs-module-[YOUR_MODULE_ID]</developerConnection> <url>https://github.com/[YOUR_GITHUB_USERNAME]/openmrs-module-[YOUR_MODULE_ID]</url> </scm>   <distributionManagement> <repository> <id>bintray-[YOUR_BINTRAY_USERNAME]-maven</id> <name>[YOUR_BINTRAY_USERNAME]-maven</name> <url>https://api.bintray.com/maven/[YOUR_BINTRAY_USERNAME]/maven/openmrs-module-[YOUR_MODULE_ID]/;publish=1</url> </repository> </distributionManagement>

Release Checklist

  1. If JIRA is used for the module to track issues (JIRA privilges for the project are needed, contact the module author):

    1. Ensure that a Version exists for the version after the one you're about to release (e.g. if you're releasing 1.7.3, create 1.7.4).

    2. Ensure that Versions are in the correct sequential order.

    3. Make sure there are no unclosed issues assigned to the version you want to release.

      1. Issues, which are open (Ready for work, In progress, Pre-commit review), but not committed can be typically bumped to the next version,

      2. Issues, which are in Post-commit review should be reviewed and closed whenever possible. If changes are not stable, they should be reverted and bumped to the next version.

    4. Mark the about-to-release version as Released.

  2. Update the release notes section on the module page in the OpenMRS wiki.

Maven Release

Releasing your module to the maven repository can be done with:

mvn release:prepare release:perform

Please see the maven release plugin documentation for more details.

Bintray Release

In order to publish your module to your 'omod' repository follow these instructions (soon to be automated with OpenMRS SDK!).

Once you make the first release you are welcome to apply for your module to be listed under https://bintray.com/openmrs/omod among other modules for better recognition within the OpenMRS community. Simply ask for your module to be linked on Bintray via Talk. Don't forget to include its Bintray URL in your post. Anyone, who is a member of the OpenMRS org on Bintray can go to the provided Bintray URL, click "Link", type in "/openmrs/omod" for the repo name and click the "tick" icon next to it to include the module.

Add-ons Release

See these instructions for adding your module to the OpenMRS add-ons index. (Your module will be periodically checked for new releases and updated accordingly.)