Revision as of 21:28, 15 December 2008

This document describes the development and release processes for the products in the Rifidi Suite as well as various conventions that developers should be following. This document is intended for developers who are fairly familiar with the Rifidi code base, especially with eclipse and OSGi concepts.

Goals

1. Standardize the development and release processes for Rifidi Developers
2. Enable a relatively lightweight release process that is able to be extended later by a fully automatic build tool like maven
3. Define a common set of conventions to use when checking in, checking out, and tagging code.

Concepts

Target Platforms

A target platform is the set of base plugins that your application depends on. Normally when you build a project in eclipse that uses eclipse functionality (SWT, JFace, etc), eclipse gets that functionality from the plugins and features folder located in you eclipse installation. Therefore it is using your eclipse base installation as your target platform. However, it is possible to define your own target platform for the application you are building rather than relying on the default one. Doing this is useful for several reasons

1. It creates a separation between the plugins you use in your developing environment and the plugins used by your application. This means that you can, for example, upgrade the eclipse you use as your IDE without upgrading the plugins used by your application. Also, you can add plugins to your application without using them in your IDE. For example suppose you want to use the GEF bundles in your application, but you don't want them inside your eclipse development environment.
2. A closely related advantage is that you can limit the plugins that are available to your application. If you use the base eclipse installation as your target platform, all of the plugins are available to your application. This makes it easy for application developers to simply add dependencies as they like. However, because an added dependency often means changes to other things, such as build processes, adding bundle dependencies should require some deliberation. Having a target platform simply makes bundle dependencies more explicit.
3. It is possible to place more than just eclipse base plugins in the custom target platform. You can put bundles in there that you have built that are required for you application. This means that you could put, for example, tagged, stable versions of all of the plugins in your application in your target platform. Then when you need to modify a plugin, you can check out the source code from svn. Because eclipse will look in your workspace before it looks in your target platform, it will find that plugin first. This means developers only have to check out code for bundles that they want to modify, which forces him to think about the code that he wants to write. It also means that, because the code in the target platform is tagged and stable, that if one developer checks in code with a change in it that breaks another plugin, that other developers can continue developing with the stable bundles in the target platform.

Bundle Versioning

All bundles in OSGi have version numbers, with the following form 1.2.3, where 1 is the major version, 2 is the minor version, and 3 is the point version. The Rifidi project uses the following conventions:

1. The major version should be increased only if there is a major API change for the bundle. This will almost always be the result of a design session and will be defined in an iteration.
2. The minor version should be increased if there is a minor API change. For example, a method signature is changed or another convenience method is added. A good rule of thumb is that if bundle X depends on bundle Y and bundle X was modified as a result of the changes to bundle Y, then bundle Y had a minor API change. For example, suppose bundle Y has a method called foo(). Suppose bundle X, for some reason, needs to pass in a string to foo(). So you modify foo() to become foo(String string). This was a minor change in bundle Y.
3. The point version should be increased for small internal changes and bug fixes. Mostly point releases happen when the changes that are made do not require that other bundles change.

Dependencies

In OSGi there are two ways of specifying dependencies.

1. Requre-Bundle should be used for dependencies to bundles that are maintained by the Rifidi project. This is anything that begins with org.rifidi.*, but could also be a third party library that we have made into a bundle and are supporting that bundle, for example, edu.uark.csce.llrp.
2. Import-Package should be used for for dependencies to bundles that are not maintained by the Rifidi project, for example, to eclipse base plugins such as SWT or GEF. It is also possible to find certain third party libraries that have already been made into a plugin at the eclipse eclipse orbit project.

The advantage to using Import-Package over Require-Bundle is that Import-Package is more flexible. The plugin is more flexible because it could use any loaded OSGi bundle that exposes that particular plugin with the given version constraints. In addition, because importing packages is more granular than requiring bundles, it makes the developer think a little more about the dependencies his is using.

In both Require-Bundle and Import-Package dependencies, the minimum version must be specified. It is also recommended that the maximum version is specified as well. This is because it is possible for more than one bundle with the same name but different versions to be loaded by OSGi during runtime. So if an incorrect version of a bundle is already loaded, but the bundle that requires that bundle does not specify the version it needs, bad things might happen.

SVN Structure

The main svn for Rifid development is called rep-external and has the following structure:

• readme

  a project that contains a text file that describes what all the bundles in trunk are used for

• rifidi

  The code for the Rifidi project

  • branches

  If a developer want to add a major feature that requires alot of time, and he wants to check the code into the svn before he is ready to integrate the code back into the trunk, he can check the code into the branches directory

  • tags
    • Bundle A
      • 1.0.0
      • 1.1.0
      • 2.0.0
    • Bundle B
      • 1.0.0
  • trunk

Tags

Product File

Processes

Setting up development environment

Modifying an Existing Bundle

Creating a new Bundle

Releasing a Product