Revision as of 22:52, 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

About 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.

Target Platforms in Rifidi

Each major Rifidi project in the Rifidi suite should have its own target platform. For example, there is a target platform called org.rifidi.emulator.target. There should be a directory in the target platform called rifidi where all the bundle binaries that are required for that particular project.

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.

Note that it is not necessary to change the version numbers any time you submit. It is only necessary to modify the version numbers if the changes are relatively well tested and stable. For example, you might want to make some changes then submit the changes back to the trunk for another developer to look at, test, or modify. If you don't expect to make any further changes to the code, the you should modify the version number

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

    When a stable version of a bundle is reached, the code should be placed in a sub directory that has the name of the bundle's version. See Development and Release Process#Tags for a description of when to create a new tag

    • org.rifidi.bundle.a
      • 1.0.0 - contains eclipse project
      • 1.1.0 - contains eclipse project
      • 2.0.0 - contains eclipse project
    • org.rifidi.bundle.b
      • 1.0.0 - contains eclipse project
  • trunk

    The trunk contains the latest code for each bundle. It might be unstable. All changes to code should be made to the bundles located in the trunk

    • org.rifidi.bundle.a - contains eclipse project
    • org.rifidi.bundle.b - contains eclipse project

Tags

The purpose of tagging a bundle is to save the code at a stable point so that future changes can be reversed if they introduce a bug that older versions did not have. A new tag must be created in svn when either the major or the minor version number of the plugin is incremented. It is not required to create a new tag when the point version number is incremented, but it is ok to do so.

Product File

A product file defines the required plugins for a particular project. It is used to build the project. It is important to keep this file updated as new plugins are added or old ones are removed.

Processes

Setting up a development environment

1. Download the target platform for the project you are working with. For example, if you are developing a plugin for emulator, you would download the target platform for emulator
2. Download any bundles that you need to modify. For example, if you are making changes to the alien reader, download org.rifidi.emulator.reader.alien
3. Set the target platform as the target platform work the workspace
4. Clean the workspace

Modifying an Existing Bundle

Suppose you have modified an existing bundle and the changes are relatively stable and tested, and you are ready to integrate them back in with the rest of the project.

1. If the changes you have made require a version change make sure that is done
2. If you had to change the major or the minor version number, create a new svn tag for the plugin.
3. Export the bundle as a binary bundle using the export wizard on the Manifest.MF file for the plugin
4. Replace the bundle in the rifidi directory of the target platform
5. Add the bundle to the rifidi directory of the build target platform
6. submit bundle changes and target platform changes back to trunk.

If you have made changes to a bundle but are not ready to integrate them back into, you can do one of two things:

1. Submit them back to the trunk, but don't change the version numbers. This is ok to do because everyone else should be using tagged stable bundles in the target platform.
2. Create a folder in the branches directory and put it there. Only do this if multiple developers are modifying the same plugin at the same time.

Creating a new Bundle

Releasing a Product