How to create releases with Maven

This manual applies to all CITE projects using Maven.

How to configure Maven

Configure Maven release plugin

Following is a recommended Maven release plugin configuration for all projects:

      <plugin>
        <artifactId>maven-release-plugin</artifactId>
        <version>3.1.1</version>
        <configuration>
          <autoVersionSubmodules>true</autoVersionSubmodules>
          <tagNameFormat>@{project.version}</tagNameFormat>
          <releaseProfiles>release</releaseProfiles>
        </configuration>
      </plugin>

Create signed artefacts

Add maven-gpg-plugin to pom.xml of project to be deployed:

  <profiles>
    <profile>
      <id>release</id>
      <build>
        <plugins>
          <plugin>
            <artifactId>maven-gpg-plugin</artifactId>
            <version>3.2.7</version>
            <executions>
              <execution>
                <id>sign-artifacts</id>
                <phase>verify</phase>
                <goals>
                  <goal>sign</goal>
                </goals>
                <configuration>
                  <gpgArguments>
                    <arg>&#45;&#45;pinentry-mode</arg>
                    <arg>loopback</arg>
                  </gpgArguments>
                </configuration>
              </execution>
            </executions>
          </plugin>
          <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-source-plugin</artifactId>
            <version>3.3.1</version>
            <executions>
              <execution>
                <id>attach-sources</id>
                <goals>
                  <goal>jar-no-fork</goal>
                </goals>
              </execution>
            </executions>
          </plugin>
        </plugins>
      </build>
    </profile>
  </profiles>

Configure Nexus staging maven plugin

Following is a recommended Nexus staging maven plugin configuration for all projects:

      <plugin>
        <groupId>org.sonatype.plugins</groupId>
        <artifactId>nexus-staging-maven-plugin</artifactId>
        <version>1.7.0</version>
        <extensions>true</extensions>
        <configuration>
          <serverId>sonatype-nexus</serverId>
          <nexusUrl>https://oss.sonatype.org/</nexusUrl>
          <autoReleaseAfterClose>true</autoReleaseAfterClose>
        </configuration>
      </plugin>

Configure Maven scm publish plugin

Following is a recommended Maven configuration for all projects:

...
      <plugin>
        <artifactId>maven-scm-publish-plugin</artifactId>
        <version>3.3.0</version>
        <configuration>
          <scmBranch>gh-pages</scmBranch>
        </configuration>
      </plugin>
...
  <distributionManagement>
    <site>
      <id>site</id>
      <url>[SCM_URL]</url>
    </site>
  </distributionManagement>
...

[SCM_URL] has to be replaced with the URL of the project repository (e.g. scm:git:[email protected]:opengeospatial/ets-gpkg12.git)

How to create Jenkinsfile

Create Jenkinsfile with path jenkinsfiles/release/Jenkinsfile and add following content.

pipeline {
  agent any
  tools {
    maven 'mvn'
    jdk 'JDK 8'
  }
  stages {
    stage('Initialize') {
      steps{
        sh '''
          echo "PATH = ${PATH}"
          echo "M2_HOME = ${M2_HOME}"
        '''
        sh 'mvn --version'
      }
    }
    stage('Release') {
      steps{
        sh 'mvn -Dresume=false -DdryRun=true release:prepare -Psign-artifacts-with-ogc,integration-tests,docker -DreleaseVersion=${releaseVersion} -DdevelopmentVersion=${developmentVersion}'
        sh 'mvn -Dresume=false release:prepare release:perform -Psign-artifacts-with-ogc,integration-tests,docker -DreleaseVersion=${releaseVersion} -DdevelopmentVersion=${developmentVersion}'
      }
    }
    stage('Publication of site') {
      steps{
        sh 'git checkout ${releaseVersion}'
        sh 'mvn clean install site site:stage scm-publish:publish-scm'
      }
    }
    stage('Results') {
      steps{
        archiveArtifacts artifacts: 'target/*', allowEmptyArchive: true
        deleteDir()
      }
    }
  }
}

Now, releases can be created with any Jenkins instance by using the Jenkinsfile.

How to execute Maven plugins manually

Create release with Maven release plugin

Execute followings commands to create a release:

mvn -Dresume=false -DdryRun=true release:prepare
mvn -Dresume=false release:prepare release:perform -Psign-artifacts-with-ogc

Run integration tests

mvn clean install site -Pintegration-tests,docker

Note that if you are building the project from within a Java 11+ environment you may need to add this option to the maven command -Dsource=8. See this GitHub Issue for an explanation.

Publish sites with Maven scm publish plugin

Execute following commands to publish sites:

mvn clean install site site:stage scm-publish:publish-scm

If a release shall be deployed, check out the tag of the release first.