Tools release processing

For some smaller project in the Narayana "fleet" (narayana-checkstyle-config, narayana-openshift-tools) we started to use the Maven Release Plugin to get the project released. This short article shows how to proceed and adds some context.

1) pom.xml preparation

Before the release is done the project’s pom.xml has to be prepared with several requirements. The release plugin uses the <distributionManagement> element to know where to deploy the artifacts and the <scm> element to know where to push the tag and the release changes in pom.xml.

Configure scm

The scm element contains several configuration sub-elements. The important one for the tagging and pushing is the developerConnection which is used to push the pom.xml changes during release:prepare.

For the git implementation it’s good to use one via ssh connection. Then the push is automatic without asking the username/password as the ssh key is used. For example it could be like <developerConnection>scm:git:[email protected]:jbosstm/narayana-checkstyle-config.git</developerConnection>.

Example configuration of <scm>

<scm>
  <connection>scm:git:https://github.com/jbosstm/narayana-checkstyle-config.git</connection>
  <url>https://github.com/jbosstm/narayana-checkstyle-config</url>
  <developerConnection>scm:git:[email protected]:jbosstm/narayana-checkstyle-config.git</developerConnection>
  <tag>HEAD</tag>
</scm>

Configure distributionManagement

This elements defines where to push the release when release:perform is launched. We use the Red Hat Nexus instance. For an easy release it’s needed that the repository id in pom.xml corresponds with configuration in ~/.m2/settings.xml where the credentials to connect to the Nexus are saved.

settings.xml configuration with credentials and the <id>

<server>
  <id>jboss-releases-repository</id>
  <username>[username]</username>
  <password>[password for jboss nexus connection]</password> <!-- same to developers.redhat.com -->
</server>

Example configuration of <distributionManagement>

<distributionManagement>
  <repository>
    <id>jboss-releases-repository</id>
    <name>JBoss Release Repository</name>
    <url>https://repository.jboss.org/nexus/service/local/staging/deploy/maven2/</url>
  </repository>
</distributionManagement>

Other necessary elements

The Red Hat nexus requires several elements for the released artifacts can be closed and promoted. The required elements are - besides others necessary for the mvn install to work (see example).

• <url>

• <description>

• <license>

• <developer>

Note	Otherwise you can get errors when viewing the Nexus staging area like failureMessage Invalid POM: /io/narayana/narayana-checkstyle-config/1.0.0.Final/narayana-checkstyle-config-1.0.0.Final.pom: Project description missing, Project URL missing, Developer information missing

2) Performing the release

mvn:release commands

The release is done in few steps

• verification that the local state of the git repository corresponds to upstream

  you can use commands like git checkout main; git fetch upstream main; git rebase upstream/main; git push upstream main

• mvn javadoc:javadoc

  verification that there won’t be any javadoc errors during release:perform

• mvn release:clean

  preparation step to clean some potential previous release attempts

• mvn release:prepare

  the Maven will ask you to 3 questions - what is the artifact version to be released (e.g. 1.0.0.Final), what is the scm/git tag which will be created and pushed to "github" (e.g. 1.0.0.Final), what is the name of the next Maven SNAPSHOT version (e.g. 1.0.1.Final-SNAPSHOT). When the command is processed then your git history is enriched with two commits - [maven-release-plugin] prepare release 1.0.0.Final and [maven-release-plugin] prepare for next development iteration. Plus, the git tag (e.g. 1.0.0.Final) is created and pushed to github. The information from <scm> tag and <developerConnection> is used.

• mvn release:perform

  Publishing the artifacts to Nexus. Data from <repository> tag is used.

Processing at Nexus

The Nexus artifacts are not automatically released. They are placed under Staging - https://repository.jboss.org/nexus/index.html#stagingRepositories and it’s needed to find the release and close it and then promote it.

When the artifacts are released from your local computer with the mvn release:perform then(!) go to the Nexus Staging Repositories tab. It’s hand to order the listing by column Updated. One of the recently updated items should be our release - you can see who create the staging record and what is the project that the staging was created for. Mark the staging record and then do Close action. When processed then do Promote action.

Sync the Nexus release with Maven Central

The synchronization of artifacts from Red Hat Nexus is automatic and has to be permitted by Nexus’s administrators. When the project/artifact is not synced then a new NEXUS issue has to be created.