Releasing Apache Celix

Note: This information is only of use to Apache Celix Release Managers!

Steps to follow:

  • Create signing KEYs
  • Update release related files
  • Compile and test
  • Create SVN tag
  • Create, sign and publish artefacts
  • Run the vote
  • Post the vote results
  • Roll out the release artefacts
  • Announce the release

Interesting links:

Create signing KEYs

Each Release Manager must have his own signing keys. Information about and instruction for the generation of these keys can be found on the Signing Releases page and How To OpenPGP. Be sure to follow the information provided on that site and its references.

The generated key can be uploaded to the MIT PGP Public Key Server.

Next, the public key signature must be added to the KEYS file. Again, read the Signing Releases page for more information. This updated file needs to be uploaded to SVN, be sure to upload it to:

For every release the related files must be updated. The following files are relevant:

  • CHANGES

    Add a list of fixed issues which can be created using Jira.

  • RELEASE_NOTES

    Add additional notes regarding this release, eg known short comings.

  • BUILDING

    Even though the BUILDING file doesn't have any specific release information, it should be verified before making a release.

  • NOTICE

    If needed, add any new license related information to this file.

Besides this information, the version needs to be bumped. Even though every bundle has its own version, a release is made with one overall version. This version is defined in the top-level CMakeLists.txt file. Update the following pieces:

SET(CELIX_MAJOR "X")
SET(CELIX_MINOR "Y")
SET(CELIX_MICRO "Z")
SET(CELIX_QUALIFIER "incubating")

While Celix is in incubation, the qualifier should (at least) always contain "incubating" as text.

Note: The DEFAULT_VERSION property is used as default version for new bundles and as such does not need to be updated when making a release.

Compile and test

Before creating a branch, be sure that the source compiles and tests run successfully. If there are any known shortcomings, make sure they are listed in the RELEASE_NOTES. Details for compiling and testing are available in the BUILDING file.

// Create a directory as sibling of the celix release directory
> mkdir celix-build
> cd celix-build
// Run CMake to generate the makefiles. Enable all BUILD options.
> ccmake ../celix
> make
> make deploy
> make test

Also verify that the provides examples work as expected. If needed ask other committers to test parts, eg the GTK examples.

// Go to the deploy directory to see all examples
> cd deploy
// Test the different examples, eg
> cd hello_world
> sh run.sh
// Depending on the example the output might be different. Most examples provide a shell to inspect the framework.
// To list the commands use the "help" command.
-> help
....

After verifying the build, run Apache RAT to check for any licensing problems. If Apache RAT is configured in the CMake build the "rat" target can be used to run the check.

// From the celix-build directory
// Run CMake to set the APACHE_RAT library (path to the JAR file).
> ccmake ../celix
// Run RAT
> make rat

Apache RAT should not raise any concers, if there are, check the source files for a license header. If it is a false positive update the rat-excludes.txt file in the root of the project. Be sure it is a false positive! If in doubt, ask the mailing list! Third party licenses may need to be mentioned in the NOTICE file.

Create SVN tag

After changing all files a tag for the new release must be made. Before doing so, make sure all changed files are committed.

The tag should be named like this: celix-X.Y.Z.incubating

To make a tag use the following command:

svn copy http://svn.apache.org/repos/asf/incubator/celix/trunk/ \
    http://svn.apache.org/repos/asf/incubator/celix/tags/celix-X.Y.Z.incubating \
    -m "X.Y.Z release of the Apache Celix project."

Note: Make sure there are no new changes made on trunk while working on the release. Discuss: Use a branch for staging the release and the files? Or possibly use a revision nr?

Create, sign and publish artefacts

Since Celix only releases source artefacts, creating the artefact is simple and straightforward

// Create symbolic link so the archive has a directory with version information
> ln -s celix celix-X.Y.Z.incubating
// Create GZip archive
> tar -hczf celix-X.Y.Z.incubating.tar.gz celix-X.Y.Z.incubating
// The create symbolic link can be removed
> celix celix-X.Y.Z.incubating

After creating the artefact, the file has to be signed. More information about signing can be found at (http://www.apache.org/dev/release-signing.html).

// Generate MD5 checksum
> md5 celix-X.Y.Z.incubating.tar.gz > celix-X.Y.Z.incubating.tar.gz.md5
// Generate SHA512 checksum
> gpg --print-md SHA512 celix-X.Y.Z.incubating.tar.gz > celix-X.Y.Z.incubating.tar.gz.sha
// Generate ASCII signature
> gpg --armor --output celix-X.Y.Z.incubating.tar.gz.asc --detach-sig celix-X.Y.Z.incubating.tar.gz

Copy the archive of the source to the Apache Celix release development area (using SVN).

See the Apache Release Guide for more information.

Run the vote

Before a release is official a vote has to be held. More information on voting can be found on Apache Voting Process. Since Apache Celix is still in incubation, both the PPMC and the IPMC have to vote for it.

The first vote has to be done on the public mailinglist of the project itself (celix-dev@incubator.apache.org). The following template must be used for this vote:

================================================================================================================

To: celix-dev@incubator.apache.org
Subject: [VOTE] Release Celix version X.Y.Z

This is the release vote for Apache Celix, version X.Y.Z.

It fixes the following issues:
{Create Release Note link using https://issues.apache.org/jira/secure/ReleaseNote.jspa?version=12323511}

Source files:
https://dist.apache.org/repos/dist/dev/incubator/celix/celix-X.Y.Z-incubating/

The tag to be voted upon:
http://svn.apache.org/repos/asf/incubator/celix/tags/celix-X.Y.Z-incubating/

Celix's keys can be found at:
https://dist.apache.org/repos/dist/dev/incubator/celix/KEYS

Information for voting on a release can be found at http://www.apache.org/dev/release.html#approving-a-release

Please vote to approve this release:

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

This vote will be open for at least 72 hours.

================================================================================================================

After this first vote the results must be posted to the "dev" list, see below for more information.

The second vote has to go to the general incubator list, this is to give the IPMC a chance to verify the release. This vote can only be published if the PPMC has had enough time to review the release, following the defacto standard, this is at least 72 hours.

The template provided above can be reused for this, but needs to be extended, the following template contains all information.

================================================================================================================

To: general@incubator.apache.org
Subject: [VOTE] Release Celix version X.Y.Z

This is the release vote for Apache Celix, version X.Y.Z.

This release has already been approved by:

+1 Name of Approver (apache ID) (binding|not binding)
+1 Name of Approver (apache ID) (binding|not binding)
...

See {Create link to the archive of Celix release thread using http://incubator.markmail.org/search/?q=list%3Aorg.apache.incubator.celix-dev} for their votes.

It fixes the following issues:
{Create Release Note link using https://issues.apache.org/jira/secure/ReleaseNote.jspa?version=12323511}

Source files:
https://dist.apache.org/repos/dist/dev/incubator/celix/celix-X.Y.Z-incubating/

The tag to be voted upon:
http://svn.apache.org/repos/asf/incubator/celix/tags/celix-X.Y.Z-incubating/

Celix's keys can be found at:
https://dist.apache.org/repos/dist/dev/incubator/celix/KEYS

Information for voting on a release can be found at http://www.apache.org/dev/release.html#approving-a-release

Please vote to approve this release:

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

This vote will be open for at least 72 hours.

================================================================================================================

Note: Be sure to use the [VOTE] tag, this is used by the automated vote tracking system to keep track of outstanding vote threads.

Post the vote results

As mentioned before, after each vote the results must be posted to the corresponding list. This "Result" vote contains the number of votes made, including wether a vote is binding or not. For a successful vote the following template can be used.

================================================================================================================

To: general@incubator.apache.org, celix-dev@incubator.apache.org
Subject: [RESULT][VOTE] Release Celix version X.Y.Z

The vote has passed with the following result:

+1 Name of Approver (apache ID) (binding|not binding)
+1 Name of Approver (apache ID) (binding|not binding)
...

{include additional details if needed}

The released artifact will be moved to the release area for mirroring. After the mirroring period the release will be announced.

Thanks for voting.

================================================================================================================

Note: Be sure to post the vote result with the same topic as the original message. Also prepend the subject with [RESULT]. This is, again, needed to be able to keep track of vote threads. See Voting Status and Voting Status Howto

Roll out release artefacts

If the vote is passed successfully the release can be moved from the "dev" area to "release". The automated svnpubsub will move the artifact to the correct server for mirroring. Mirroring typically can take up to 24 hours.

Besides uploading the new release, the old release should be archived. Since archiving is already automated, it is only needed to delete the previous version from the release area. See the Apache Release Guide for more information.

See the Apache Release Guide for more information.

After these 24 hours the release can be announced.

Announce the release

Update website's News and Download sections to include the new release.

On the "Download" page, the old release can be replaced with the new one, there is no need to keep a link to archived versions. The "News" section can simply be extended with an additional entry.

Additionally it is a good idea to post a message to "announce@apache.org" and "celix-dev@incubator.apache.org". (note: the from address must be a ...@apache.org address).

The following template must be used:

================================================================================================================

To: announce@apache.org, celix-dev@incubator.apache.org
Subject: [ANNOUNCE] Apache Celix X.Y.Z.incubating released

The Apache Celix team is pleased to announce the release of Celix X.Y.Z.incubating.

Celix is an implementation of the OSGi specification adapted to C. It will follow the API as close as possible, but since the OSGi specification is written primarily for Java, there will be differences. An important aspect of the implementation is interoperability between Java and C. This interoperability is achieved by porting and implementing the Remote Services specification in Celix.

This new release focusses on .... {add additional information for this release}

The release is available here:
http://incubator.apache.org/celix/download.cgi

The full change log is available here:
{Create Release Note link using https://issues.apache.org/jira/secure/ReleaseNote.jspa?version=12323511}

We welcome your help and feedback. For more information on how to report problems, and to get involved, visit the project website at http://incubator.apache.org/celix/

The Apache Celix Team

================================================================================================================

Requirements

  • CMake (2.8.4)
  • GCC (4.2.1)
  • GNU Make (3.81)
  • ZLib
  • CUnit
  • Celix Source