-
Notifications
You must be signed in to change notification settings - Fork 64
Releasemanagement and versioning
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 is separated into three digits.
2. 0. 1
| | |-- patch level
| |-------- minor 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!
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.
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!
Since version 2.1.0 the release management process is managed through the configuration and build framework Maven. The release management is manged by the parent pom.xml. The process of promoting a new release is a half automated process controlled by the Maven release plugin. See the brief instruction below.
The results are distributed to the follwoing repository locations with can be added to the settings.xml file of your maven setup:
http://oss.sonatype.org/content/repositories/snapshots
This repository should be only used if snapshot releases are necessary for a specific build.
https://oss.sonatype.org/content/repositories/releases/
This repository contains all released artifacts from the imixs project. Commonly this repository is not necessary as all releases are published into the Maven central repository.
http://repo2.maven.org/maven2/
This is the default central repository used by maven without further configuration.
Each repository location can be added to the settings.xml configuration file from a local maven installation (typical located in ~/.m2/settings.xml)
General access to the snapshot releases and staging database:
The following brief instruction describes how to promote a new release based on the maven release plugin configured in the parent pom.xml.
1.) preparing the pom.xml
First of all the pom.xml of the subproject should fulfill all necesary informations to be deployed to the maven central repository Read details: https://docs.sonatype.com/display/NX/OSS+Repository+Hosting
Important informations are the scm tag and the maven-release-plugin configuration
The scm uris should point to the master branch of the project:
<scm>
<connection>scm:git:https://github.com/imixs/imixs-workflow.git</connection>
<developerConnection>scm:git:https://github.com/imixs/imixs-workflow.git</developerConnection>
<url>https://github.com/imixs/imixs-workflow/</url>
</scm>
The maven-release-plugin need no special configuration for GitHub.
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-release-plugin</artifactId>
</plugin>
The distributionManagement section is necessary if the artefact should be released on sonatype maven repository central. The section should include the snapshotRepository as also the repository location pointing to the sonatype staging repository:
<!-- Distributen Management oss.sonatype.org -->
<distributionManagement>
<snapshotRepository>
<id>sonatype-nexus-snapshots</id>
<name>Sonatype Nexus Snapshots</name>
<url>http://oss.sonatype.org/content/repositories/snapshots</url>
</snapshotRepository>
<repository>
<id>sonatype-nexus-staging</id>
<name>Nexus Release Repository</name>
<url>http://oss.sonatype.org/service/local/staging/deploy/maven2/</url>
</repository>
</distributionManagement>
The pom.xml is already configured so manual changes should not be necessary.
2) Merge master branch
After pom.xml is updated the project should be comited and merged into the GitHub master branch.
3) prepare release (tag a version)
This step prepares a new tag and update the current snapshot realease. This can be used for all kinds of maven artefacts, even if the artefact is not released in a maven repository like the sonatype maven central repository. Some of the Imixs modules (e.g. imixs-script) are not part of the maven central repository. In this case only this step is necessary to create a new snapshot version.
After project settings (pom.xml) are verified and data is synchronized with GitHub use the mvn tool from a command line. Do not! use the eclipse maven plugin m2eclipse because interactive mode is not working reliable From a command line perform the following mvn goals:
mvn clean
mvn -Dusername=your_github_username -Dpassword release:prepare
This will tag the current snapshot and update the snapshot release. The user and password can be left by during release:prepare command if you provide these informations in you settings.xml file in the server section.
If a problem occurs changes on the pom.xml files were already be comited into your local repository. To undo this commit triggered by maven you can use the following git command
git reset --hard HEAD~1
Verify your local git workspace. It could happen that maven also had added some version files which mybe should be removed manually.
4) promote release
After step 3 was sucessfull and !only! if your artefact should be released into a maven repository (as for the most imixs artefacts) this step performs a release. Between prepare and perform you should check the sources of the project. The pom.xml should be updated to the next snapshot version automatically. From a command line perform the following mvn goals:
mvn release:perform -Darguments=-Dgpg.passphrase="SECRET"
where SECRET is the gpg passphrase.
The gpg key is typical stored in the users home directory (for Linux .~/gnugp) If a problem occurs first clean the release:
mvn release:clean
Next remove the generated new tag version
Uno changes to the pom.xml - in most cases the version should be replaced with the old snapshot version. After all you can repeat the steps explained before.
5) check staging repository
This step is only necessary if step 4 was performed. A imixs artefact is typically release during the prepare phase into the sonatype maven central repository. You need finally check the http://oss.sonatype.org staging repository and 'close' and 'release' your artefact manually using the sonatype frontend.
Select the 'Staging Repositories' and select your current release. Click to the "close" command to close the staging artifact - this can take some minutes. Refresh the view and click to the "release" command to release the staging The Release should be published during the next 6 hours
6) push master branch and update developer branch
Finally you need to push the changes of your local git repository made by maven to the GitHub repoistory. Use the git push command.
Now your new release is taged and availalbe on GitHub and you can switch back to your developer branch. There you need to merge the new release from the master branch!