How to create and announce a Karaf release.

Required tools, practices and resources

Versioning

Sample versioning:

SNAPSHOT

RELEASE

1.0.0-SNAPSHOT

1.0.0

1.1.0-SNAPSHOT

1.1.0

1.1.1-SNAPSHOT

1.1.1

1.1.2-SNAPSHOT

1.1.2

2.0.0-SHAPSHOT

2.0.0

Prepare

To prepare and perform a release you must be at least at Apache Karaf Committer.

Your settings.xml should look like:

<settings>
  ...
  <profiles>
    <profile>
      <id>release</id>
      <properties>
        <gpg.passphrase> <!-- YOUR KEY PASSPHRASE --> </gpg.passphrase>
      </properties>
    </profile>
  </profiles>
  ...
  <servers>
    <!-- To publish a snapshot of some part of Maven -->
    <server>
      <id>apache.snapshots.https</id>
      <username> <!-- YOUR APACHE SVN USERNAME --> </username>
      <password> <!-- YOUR APACHE SVN PASSWORD --> </password>
    </server>
    <!-- To stage a release of some part of Maven -->
    <server>
      <id>apache.releases.https</id>
      <username> <!-- YOUR APACHE SVN USERNAME --> </username>
      <password> <!-- YOUR APACHE SVN PASSWORD --> </password>
    </server>
    ...
  </servers>
</settings>

Community awareness message(s).

In the lead up towards a release candidate the user base should be given some notification.

In the case of dot zero release a new maintenance branch may be created with trunk continuing new development. The maintenance branch may be used for stabilization of the code base before a release candidate is cut. A notification message to the dev & user lists may be warranted.

To: "Karaf Developers List" <dev@karaf.apache.org>
Subject: [NOTICE] Karaf trunk branched to create X.Y.0 maintenance branch. 

Hi,

We've just branched off X.Y.0 from trunk and started to stabilize it; latest artifacts are
available via apache-snapshot repo... simply add the following repo to your pom,
change the version to and provide us with feedback.

<<insert short description of the reason for branching here>>

Thanks,

-The Karaf team

A few weeks later the following message would be sent:

To: "Karaf Developers List" <dev@karaf.apache.org>
Subject: [UPDATE] Karaf X.Y.0 release branch status.

Hi,

Thanks for all your feedback; we've fixed XX bugs/problems on the release branch
and will start a release about next week; Thanks again for all your contributions.

-The Karaf Team

Staging the Release Candidate

  1. Grab the latest source 
    svn co https://svn.apache.org/repos/asf/karaf/trunk
  2. Prepare your POMs for release:
    1. make sure there is no snapshots in the POMs to be released
    2. make sure everything builds fine
    3. check that your POMs will not lose content when they are rewritten during the release process: 
      mvn release:prepare -DdryRun
      Please diff the original pom.xml with the one named pom.xml.tag to see if the license or any other info has been removed. This has been known to happen if the starting <project> tag is not a single line. The only things that should be different between these files are the <version> and <scm> elements. If there are any other changes, you must fix the original pom.xml file and commit before proceeding with the release.
    4. publish a snapshot 
      $ mvn deploy
...
[INFO] [deploy:deploy]
[INFO] Retrieving previous build number from apache.snapshots.https
...
  3. Prepare the release 
    mvn release:clean
mvn release:prepare
  4. Stage the release for a vote 
    mvn release:perform
  5. Close the staging repository
  6. Verify the staged artifacts

Starting the vote

Propose a vote on the dev list with the closed issues, the issues left, and the staging repository - for example:

To: "Karaf Developers List" <dev@karaf.apache.org>
Subject: [VOTE] Release Karaf version X.Y.Z

Hi,

We solved N issues in this release:
http://issues.apache.org/jira/...

There are still some outstanding issues:
http://issues.apache.org/jira/...

Staging repository:
https://repository.apache.org/content/repositories/karaf-staging-[YOUR REPOSITORY ID]/

Please vote to approve this release:

[ ] +1 Approve the release
[ ] -1 Veto the release (please provide specific comments)

This vote will be open for 72 hours.

Wait for the Results

From Votes on Package Releases:

Votes on whether a package is ready to be released follow a format similar to majority approval - except that the decision is officially determined solely by whether at least three +1 votes were registered. Releases may not be vetoed. Generally the community will table the vote to release if anyone identifies serious problems, but in most cases the ultimate decision, once three or more positive votes have been garnered, lies with the individual serving as release manager. The specifics of the process may vary from project to project, but the 'minimum of three +1 votes' rule is universal.

The list of binding voters is available at http://karaf.apache.org/team.html.

If the vote is successful, post the result to the dev list - for example:

To: "Karaf Developers List" <dev@karaf.apache.org>
Subject: [RESULT] [VOTE] Release Karaf version X.Y.Z

Hi,

The vote has passed with the following result :

  +1 (binding): <<list of names>>
  +1 (non binding): <<list of names>>

I will copy this release to the Karaf dist directory and
promote the artifacts to the central Maven repository.

Canceling the Release

If the vote fails, or you decide to redo the release:

  1. remove the release tag from Subversion (svn del ...)
  2. login to https://repository.apache.org using your Apache SVN credentials. Click on Staging on the left. Then click on org.apache.karaf in the list of repositories. In the panel below you should see a closed repository that is linked to your username and IP (if it's not yet closed you need to right click and select Close). Right click on this repository and select Drop.
  3. rollback the version in the pom.xml and commit any fixes you need to make

Promoting the Release

If the vote passes:

  1. copy the released artifacts to the Karaf dist directory (/x1/www/www.apache.org/dist/karaf) on people.apache.org
  2. delete the old release from the Karaf dist directory (it's archived)
  3. login to https://repository.apache.org with your Apache SVN credentials. Click on Staging. Find your closed staging repository, right click on it and choose Promote. Select the Releases repository from the drop-down list and click Promote.
  4. next click on Repositories, select the Releases repository and validate that your artifacts are all there
  5. update the news section on the website at news
  6. update the download page on the website at downloads to point to the new release.

For the last two tasks, it's better to give the mirrors some time to distribute the uploaded artifacts (one day should be fine). This ensures that once the website (news and download page) is updated, people can actually download the artifacts.

Update JIRA

Go to Admin section on the Karaf JIRA and mark the X.Y.Z version as released - create version X.Y.Z+1, if that hasn't already been done.

Announcing the Karaf Release

To: "Karaf Developers List" <dev@karaf.apache.org>
Subject: [ANN] Karaf version X.Y.Z Released

The Karaf team is pleased to announce the release of Karaf version X.Y.Z

<<insert short description of important updates>>

  http://karaf.apache.org/

This release is available from http://karaf.apache.org/downloads and Maven:

  <dependency>
    <groupId>org.apache.karaf</groupId>
    <artifactId>org.apache.karaf.XXX</artifactId>
    <version>X.Y.Z</version>
  </dependency>

Release Notes:

<<insert release notes in text format from JIRA>>

Enjoy!

-The Karaf team

Remember to forward this announcement to users@karaf.apache.org - try not to cross-post (CC announcements to both user and dev lists.

Add blog entry to Karaf news.

Please add a simple blog entry to the Karaf news feed, you may use the following format:

The Karaf team is pleased to announce the availability of Karaf X.Y.Z.
This release includes a number of new features, improvements and bug fixes. (Adjust to reflect motivation behind release)
For more information, please see the release notes.