Release and Release Process

This section provides a step by step description to execute a release of the OpenEngSB. It is relevant for everyone marked in the OpenEngSB Team List as release manager because only they have the required rights to execute the following steps.

Releases and the OpenEngSB

Every release of the OpenEngSB consists of the following parts: RELEASE.MAJOR.MINOR.TYPE. Every release of this type is available at Maven Central. Optionally SNAPSHOT is appended. Snapshot releases are available from the Sonatype Snapshot repository. This section explains what each modifier means and how it is used within the OpenEngSB.

SNAPSHOTS: Snapshots are always available from the latest build of the OpenEngSB. They are taken from the master branch automatically at each commit.

TYPE: Type could be MX, RCX or RELEASE, where X is a number. While RELEASE marks a final release, ready for use in your production environment, M and RC are typically not ready for production. M stands for Milestone release and is cut every two weeks to present the current state of the OpenEngSB and allow a coarse grained planning and roadmap for the OpenEngSB team. RC, release candidates, are handled differently.
After everything is finished and the OpenEngSB teams think that the current work is ready for a release, we provide a release candidate and invite everyone to test the release. If there are any issues with the release we fix them and provide another release candidate. During this process no new features, but only bug fixes are handled. We continue this process as long as there are no new bug reports for a RC for two weeks.
Then we re-release the latest release candidate as final release. This process only applies for RELEASE and MAJOR. MINOR is handled differently, as explained later on.

RELEASE is a increasing number used for mayor changes within the OpenEngSB architecture. In addition all methods and interfaces marked as deprecated are removed during such a release. It is also possible that a RELEASE does not enhance any mayor architectural concept but is only used to get rid of all the deprecated methods, generated during MAJOR releases.

MAJOR is the main feature development number of the OpenEngSB. Each release containing new features will be a MAJOR release. Nevertheless, between MAJOR releases architectural concepts are not removed but only set to deprecated. This means they only enhance functionality but try to not break with former releases.

MINOR releases are bug-fix releases. They do not include any new features but only fix bugs within the OpenEngSB. They have no release plan, but are simply cut after each bug-fix.

To visualize the explained process the following example. Assume we have released openengsb-1.0.0.RELEASE. Now we're working on openengsb-1.1.0.RELEASE. Therefore we start developing openengsb-1.1.0.M1 which will be released in two weeks. During the development of 1.1.0.M1 a bug occurs at openengsb-1.0.0.RELEASE. During the development the bug is fixed and openengsb-1.0.1.RELEASE is released.
After 1.1.0.M1 we require three additional milestone releases to get feature releases. Six weeks after 1.1.0.M1 we'll release 1.1.0.RC1. From now on we continue to develop 1.2.0.M1 (or 2.0.0.M1, depending on the gravity of the changes) and wait for feedback on 1.1.0.RC1. Now a bug-report occurs for 1.0.1.RELEASE. We fix the bug, release 1.0.2.RELEASE with the fix.
If it also affects 1.1.0.RC1, we fix the bug there too and release 1.1.0.RC2 (still working on 1.2.0.M1(!)). Now assume that some other bug reports are received for 1.0.0.RC2. We fix them and release 1.1.0.RC3. In the meantime we finished 1.2.0.M1 and start work on 1.2.0.M2. Now two weeks after the release of 1.1.0.RC3 without any new bug-reports we re-release 1.1.0.RC3 to 1.1.0.RELEASE (starting the game again from the beginning).

Git Branches

For the best cooperation between Git and Maven the OpenEngSB team has developed its own workflow with branches during releases. For different project phases (milestone, RC, final, support) different workflows apply.

New Feature Workflow

For new features the already described workflow apply. This means create a feature branch based on the integration branch, add your commits and create a pull request if you're finished. Your changes will be merged (after review) to the integration branch. From time to time the integration branch ins merged into the master, which is pushed as snapshots to sonatype.

Milestone Releases

For milestone releases about one day before a planned release a openensb-1.X.0-release branch is created. This branch can be forward merged to integration as often as liked (no backward merges are allowed). If all final bugs and changes are done the MX version is released on this branch and the branch is merged into integration and deleted again. During this process any number of new features are merged into integration, without affecting the release any longer.

Release Candidates

RCs are the pre-level for final releases. This means, after the openengsb team decides a release is ready to go, two new branch are created from the latest commit AFTER the milestone release (where the mvn versions are set backo the snapshot version): openengsb-1.X.x-dev and openengsb-1.X.x-release. openengsb-1.X.x-dev is used for bug-fixes.
Every fix which should also be merged into the integration branch/master should be branched off openengsb-1.X.x-dev and afterewards merged into integration and openengsb-1.X.x-dev. If a release is ready openengsb-1.X.x-dev is merged into openengsb-1.X.x-release, where the release takes place. BUT no merge from openengsb-1.X.x-release to openengsb-1.X.x-release is allowed!

Final and Support Releases

All support and final releases are handled exactly as the RC releases between the openengsb-1.X.x-dev and openengsb-1.X.x-release branch.

Configure Maven

For the right rights to deploy to maven central and upload maven site to openengsb.org the following entries are required in your ~/.m2/settings.xml file:

<![CDATA[<settings>
  <server>
    <id>sonatype-nexus-snapshots</id>
    <username>SONATYPE_USERNAME</username>
    <password>SONATYPE_PASSWORD</password>
  </server>
  <server>
    <id>sonatype-nexus-staging</id>
    <username>SONATYPE_USERNAME</username>
    <password>SONATYPE_PASSWORD</password>
  </server>
  <server>
    <id>OpenengsbWebServer</id>
    <username>OPENENGSB_SERVER_USERNAME</username>
    <password>OPENEGNSB_SERVER_PASSWORD</password>
  </server>
  <profiles>
    <profile>
      <id>milestone</id>
      <properties>
        <gpg.passphrase>GPG_PASSPHRASE</gpg.passphrase>
      </properties>
    </profile>
    <profile>
      <id>release</id>
      <properties>
        <gpg.passphrase>GPG_PASSPHRASE</gpg.passphrase>
      </properties>
    </profile>
    <profile>
      <id>final</id>
      <properties>
        <gpg.passphrase>GPG_PASSPHRASE</gpg.passphrase>
      </properties>
    </profile>
  </profiles>
<settings>]]>

All the usernames and passwords can be retrieved from someone marked as administrator in the OpenEngSB Team List.

In addition you have to have a GPG key for your mail address (the same you're using to commit to the OpenEngSB source repository which is uploaded to the MIT Key Server.

Adapt Jira

A word in front, how Jira is used for the OpenEngSB. Jira is used for bug tracking and release planning. ONLY each Milestone release has its own target. Release candidates and final releases are handled differently. Since we release RC and MINOR releases quite often its much too much administration work to keep JIRA up to date.

Ok, knowing that the release process is simple:
*) If you release a milestone release close the release target (e.g. 1.0.0.M1).
*) If you release a release candidate create a VERSION.RCX release target and close the old one.
*) If you release a final release (MAJOR RELEASE) create a new release target 1.0.X.RELEASE.
*) If you release a minor release close the 1.0.X.RELEASE target and create 1.0.(X+1).RELEASE.

Perform the release

Performing a release is quite simple, because of the maven release plugin and some scripts. Simple follow these steps:
*) First of all make sure that the NOTICE file is up-to-date using notice:generate
*) Now invoke "mvn openengsb:release{Final|Milestone|Support|RC} -DconnectionUrl=path/to/your/repo" (e.g. mvn openengsb:releaseMilestone -DconnectionUrl=scm:git:file://~/openengsb)
*) After the artifacts are available for sync to maven central you have to push them from the staging to the final repository. Therefore follow the steps as explained here
*) If everything works fine execute git push;git push --tags

Spread the News

Post a message to the OpenEngSB twitter account with the following content:

<![CDATA[openengsb-VERSION "NAME" released, closing XX issues (JIRA_RELEASE_REPORT_SHORT_URL). Try the new features now: http://openengsb.org]]>

Mails in this case are not only used for notification but also to get the developers and users to try a new release and report issues and problems. Therefore, we use different templates for different types of releases of the project.

The following template shows a copy and paste template for mails send for a release candidate. This mail should only be sent to the developer mailing list:

<![CDATA[Hey guys,

I've just uploaded openengsb-1.0.0.RC4 to maven central (Should be available
within the next hour).

Sources can be downloaded here:

https://github.com/openengsb/openengsb/zipball/openengsb-1.0.0.RC4

The binary release can be downloaded here:

http://repo1.maven.org/maven2/org/openengsb/openengsb/1.0.0.RC4/openengsb-1.0.0.RC4.zip

Between openengsb-1.0.0.RC3 and openegnsb-1.0.0.RC4 we've fixed the following
issues:

** Bug
  * [OPENENGSB-548] - jetty7 - felix problems 
  * [OPENENGSB-605] - Use png as favicon for openengsb war file and script

** Improvement
  * [OPENENGSB-603] - Context has to be stored persistently and
  * restored on system startup
  * [OPENENGSB-610] - Maven connector has to support the execution of a configurable command

** Task
  * [OPENENGSB-606] - update docs new jira release 

** TBD
  * [OPENENGSB-589] - document release process for stable branches

Please give it a try and report all problems you encounter here:

http://issues.openengsb.org/jira/browse/OPENENGSB/fixforversion/10142

If there are no new issues reported within the next 72 hours I set RC4 as the final release 1.0.0.RELEASE.

Kind regards,
andreas]]>

Prepare Changelog

The changelog is a file to inform users about the changes in the version they are using. This file should only contain the releases which are done in one branch. E.g. the master will never contain changelog about minor releases; because of the way we handle Jira those changes are captured and included anyhow.

Now the CHANGELOG.md file has to be updated. Therefore the following template with the correct version have to be copied in the current changelog file (the latest version always has the most "on-top" position in the text file):

<![CDATA[openengsb-VERSION
------------------

Add a General Description

### Highlights
  * [e.g.] org.openengsb.domain.scm.doSomething() is removed

### Details

Copy JIRA issues here]]>

The following sections explain shortly what changes belong to which part of the changelog.

General Description

The general description summarizes the most important changes in this release. This is a short and verbal description of the changes.

Highlights

The highlight section could be a little bit more detailed than the general description. Things which should be changed by developers could be explained here and other important points could be lined up here.

Details

The details section contains a copy of the release notes generated by Jira if a developer wants to take a detailed look at the changes included in this release.