/
Creating New Bundles

Creating New Bundles

Dec 27, 2015

Before you start

Before starting a new Pax Tipi subproject for a given third-party library, you should always contact the original developers and kindly ask them to osgify their artifacts, offering to submit a patch or a pull request.

Only if this has no effect, use Pax Tipi to wrap and redistribute the given artifacts.

Licenses

Check if the original license permits redistribution under an Apache License v2.

JIRA Issue

Create a JIRA issue in the PAXTIPI project for the given artifact to be wrapped.

New Subproject

In your local workspace of the org.ops4j.pax.tipi project, create a new subdirectory foo-1.2.3, using the artifactId and version of the artifact you are going to wrap. Copy and adapt the POM of an existing Tipi bundle - junit-4.11/pom.xml is a good starting point.

Run mvn install and check if the generated bundle works as expected.

Versioning Scheme

Most but not all projects use a major.minor.micro versioning scheme. The maven-bundle-plugin has an algorithm for mapping Maven artifact version to OSGi bundle versions - unfortunately, the plugin does not expose the version to be reused by other Maven plugins, which is what we need to define the version of an Eclipse-compatible source bundle.

For this reason, we do not rely on the maven-bundle-plugin to compute the version and set it explicitly as major.minor.micro.qualifier, where the qualifier is a counter starting from 1. The qualifier only ever gets incremented if we need to repackage the same artifact version, e.g. when someone finds an error in the manifest headers after the release.

If the original artifact does not use the minor or micro digits, we set them to 0. Thus, for instance, for junit-4.11, the corresponding Tipi version is 4.11.0.1.

Checklist

  • Use the new bundle in an OSGi application or test. Does it resolve and work as expected?
  • Inspect the generated manifest. Are there any unwanted imports or exports? Are all packages exported with a suitable version number?
  • Use the new Tipi bundle as a dependency in another Maven project. Make sure you do not get the original Maven artifact as a transitive dependency.
  • If the wrapped bundle has dependencies, make sure they are OSGi bundles or exlude and override them by osgified dependencies in the Tipi POM. This may require wrapping additional bundles before you can proceed with the bundle you are really interested in.
  • Make sure that the generated source archive has the Eclipse-SourceBundle header and that the bundle version matches exactly the version of the wrapped bundle.

Release

How to build a release: 

  1. make sure you have at least version 1.3.0 of tipi-master selected
  2. create the release with mvn release:prepare
  3. mvn release:perform might not always work in that case follow the following steps: 
    1. change to the target/checkout/sub-module path of your desired sub-project

    2. call mvn clean install javadoc:javadoc gpg:sign deploy -P sonatype-oss-release to build, sign and generate javadocs of your current checkout

    3. now you should be able to release the artifact via oss.sonatype.org or with the nexus-staging plugin with the following command: mvn nexus-staging:release