Skip to content

Releasemanagement and versioning

Ralph Soika edited this page Apr 6, 2018 · 15 revisions

The Imixs Workflow Project consists of different submodules managed by a maven parent project. The following section gives an overview how release management and versioning is handled in this project. In general we are using "Semantic Versioning" from Tom Preston-Werner.

The Release Number

The release Number is separated into three digits.

  2. 0. 1 
  |  |  |-- patch level
  |  |-------- minor version 
  |-------------- major version

Major Version

The major version number indicates the general main release of Imixs-Workflow. This number did not change very often. Typical this number will be increase when a general redesign of the Imixs-Workflow-API is done or a fundamental new technology or framework is used like switching to Java 8. Often a new Major version implicates the need of a migration from older versions. You can not mix artifacts or components with different major versions!

Minor Version

The minor version number is used for new features or enhancements. For example adding a new controller or a service EJB can lead to an increase of the minor version number. As we use Maven as the general build and configuration framework, minor versions are typical reflected in dependencies. So for example the Imixs-Workflow-Engine depends on the Imixs-Workflow-Core API with the same minor version. You should not mix artifacts or components with different major versions.

Patch Level

The last digit is used for the Patch Level of a release. It indicates bug fixes made after a minor or major release. It is strongly recommended to always use the latest patch level version!

The Release Management

The release management process in Imixs-Workflow is managed by the configuration and build framework Maven. The release management is part of the maven-release-plugin which is configured in the parent pom.xml of the project. The results are distributed to the central maven repository locations with can be added to the settings.xml file of your maven setup (typical located in ~/.m2/settings.xml):

....
 <repositories>
    <!-- Sonatype Snapshot repository -->
    <repository>
        <id>sonatype-snaptshots</id>
        <name>Sonatype Snapshot repository</name>
        <url>http://oss.sonatype.org/content/repositories/snapshots</url>
    </repository>

    <!-- Sonatype Releases repository -->
    <repository>
        <id>sonatype-releases</id>
        <name>Sonatype Releases repository</name>
        <url>https://oss.sonatype.org/content/repositories/releases/</url>
    </repository>
 </repositories>
....

This repository contains all released and snapshot artifacts from the Imixs-Workflow project.

Maven Central repository

The central maven repository is the default repository used by maven without further configuration needed.

http://repo2.maven.org/maven2/

General access to the snapshot releases and staging database:

http://oss.sonatype.org

Performing a Release Deployment with the Maven Release Plugin

The following brief instruction describes how to promote a new release based on the maven release plugin configured in the parent pom.xml. Find detailed information about the process here.

The Maven Release Plugin is used to automate the changes to the Maven POM files, sanity checks, the SCM operations required and the actual deployment execution. The parent pom.xml file is already configured so manual changes should not be necessary.

With the SCM connection configured correctly you can perform a release deployment to OSSRH with

mvn release:clean release:prepare -DautoVersionSubmodules=true -Dusername=GITHUB_USERID -Dpassword=GITHUB_PASSWORD

by answering the prompts for versions and tags, followed by

mvn release:perform

This execution will deploy to OSSRH and release to the Central Repository in one go, thanks to the usage of the Nexus Staging Maven Plugin with autoReleaseAfterClose set to true.

If something went wrong

Just in case the release command failed unexpected you can roll back the release and staging process. The pom.xml files maybe were already be committed into your local repository and tags can already be created. To undo this commit you can use the following git command

mvn release:rollback
git reset --hard HEAD~1

Verify your local git workspace. In such a case you need also check and remove the generated new tag versions in GitHub and your local git repo.

You can’t perform that action at this time.