How to migrate from jgitflow-maven-plugin to gitflow-maven-plugin

Overview

This article describes the required steps to migrate from jgitflow-maven-plugin to gitflow-maven-plugin .

jgitflow-maven-plugin is no longer maintained. The gitflow-maven-plugin is not a drop-in replacement, but it’s very well maintained and provides a lot of additional features.

Adapt your project

If you have already used jgitflow-maven-plugin together with deriving your parent POM from wcm.io global-parent or aem-global-parent POM the migration is really easy.

If you have no special configuration for jgitflow-maven-plugin in your project POMs you have nothing to do besides updating to the latest version of global-parent (35 or higher) or aem-global-parent (1.4.16 or higher).

If you have multiple releasable modules within a single GIT repository and a configuration like this in place that customizes the branch and tag names:

<plugin>
  <groupId>external.atlassian.jgitflow</groupId>
  <artifactId>jgitflow-maven-plugin</artifactId>
  <configuration>
    <flowInitContext>
      <releaseBranchPrefix>release/${project.artifactId}-</releaseBranchPrefix>
      <hotfixBranchPrefix>hotfix/${project.artifactId}-</hotfixBranchPrefix>
      <versionTagPrefix>${project.artifactId}-</versionTagPrefix>
    </flowInitContext>
  </configuration>
</plugin>

you have to add a new configuration (or replace the existing configuration) for gitflow-maven-plugin which looks quite similar:

<plugin>
  <groupId>com.amashchenko.maven.plugin</groupId>
  <artifactId>gitflow-maven-plugin</artifactId>
  <configuration>
    <gitFlowConfig>
      <releaseBranchPrefix>release/${project.artifactId}-</releaseBranchPrefix>
      <hotfixBranchPrefix>hotfix/${project.artifactId}-</hotfixBranchPrefix>
      <versionTagPrefix>${project.artifactId}-</versionTagPrefix>
    </gitFlowConfig>
  </configuration>
</plugin>

Using gitflow-maven-plugin

You can use gitflow-maven-plugin in exactly the same way:

mvn gitflow:release-start gitflow:release-finish

There is a shortcut available if you want to use the start and finish commands simultaneously:

mvn gitflow:release

If you need to pass additional arguments e.g. for code signing this is possible like this:

mvn -DargLine="-Dgpg.keyname=XXX-Dgpg.passphraseServerId=XXX" gitflow:release

It is also possible to overwrite some of the preconfigured gitflow-maven-plugin settings on the command line - example to change the goals that are executed after the release (e.g. skipping deployment):

mvn -D"gitflow.postReleaseGoals"="clean install" gitflow:release

Next development version with gitflow-maven-plugin

The gitflow-maven-plugin provides no prompt during the release process for entering the new development version number that is used on the develop branch after the release. This means the new development version number is always calculated automatically.

You can influence this logic with two optional parameters which you can pass with -D as system properties on the command line:

versionDigitToIncrement parameter which controls which digit to increment in the next development version. Starts from zero. For example, if the release version is 1.2.3.4 and versionDigitToIncrement is set to 1 then the next development version will be 1.3.0.0-SNAPSHOT. If not set or set to not valid value defaults to increment last digit in the version.
digitsOnlyDevVersion parameter which will remove qualifiers from the next development version if set to true. For example, if the release version is 1.0.0-Final then development version will be 1.0.1-SNAPSHOT. The default value is false (i.e. qualifiers will be preserved in next development version).

If you have more complex versioning schemes (e.g. even-odd versioning), you can configure a Maven Release Version Policy to be used. Example:

<plugin>
  <groupId>com.amashchenko.maven.plugin</groupId>
  <artifactId>gitflow-maven-plugin</artifactId>
  <configuration>
    <projectVersionPolicyId>OddEvenVersionPolicy</projectVersionPolicyId>
  </configuration>
  <dependencies>
    <dependency>
      <groupId>org.apache.maven.release</groupId>
      <artifactId>maven-release-oddeven-policy</artifactId>
      <version>3.0.0-M5</version>
    </dependency>
  </dependencies>
</plugin>

Details of the gitflow-maven-plugin configuration

In the wcm.io global-parent/aem-global-parent the gitflow-maven-plugin is configured ready-to-use to behave as similar as possible as the jgitflow-maven-plugin, see the corresponding configuration section in global-parent POM and the default settings.

Some remarks on the configuration parameters we’ve chosen:

skipTestProject=true: Same behavior as jgitflow-maven-plugin. Additionally this prevents build failures in case you have never built the project locally and your modules have dependencies to each other. By default gitflow-maven-plugin executes a hard-coded “mvn clean test” without an install (this does also not change when setting installProject to true).
verbose=true: Show the maven build that is executed during the release process - important if you have lengthy builds.
pushRemote=false: Do not automatically push develop/master branches and the tag - if anything goes wrong you can easily drop the changes locally.
versionsForceUpdate=true: Make sure all child modules are updated as well.
postReleaseGoals: Make sure the artifacts are deployed to the maven repository during the release and the release-profile gets activated.
commitMessagePrefix: Is prepended to every commit message automatically generated by the plugin.

If you do not use the global-parent POM: Please make also sure you have updated to the latest version of versions-maven-plugin (2.8.1 or later).