Version Numbering Galileo Update

This document describes updates to the Eclipse Version Numbering guidelines that were made for the Galileo simultaneous release. Specifically, this document revises the version numbering guidelines to reflect the impact of p2 provisioning technology that has been in the Eclipse platform since the Ganymede simultaneous release. These changes have been integrated into the Version Numbering document, but this document remains as a reference describing what changes were made and the rationale for those changes.

Explanation of changes

Requiring features versus requiring bundles

Prior to Ganymede, the Eclipse platform used the original Eclipse provisioning technology, commonly referred to as Update Manager. In Update Manager, features were the atomic unit of installable function, and Update Manager analyzed dependencies and version numbers exclusively at the feature level. This led to unwieldy duplication of dependency data at both the feature and plug-in levels. Only feature dependencies were used at install-time, and only plug-in dependencies were used at run-time. This led to frequent problems where feature installed successfully, only to fail at run-time, or conversely failed to install features that would have succeeded at run-time.

p2 addresses this duplication problem by performing full dependency analysis at the plug-in level. This means a bundle or feature will be successfully installed if and only if it will correctly resolve at run-time. The consequence of this change is that dependencies no longer need to be expressed at the feature level if they are already expressed at the plug-in level. Feature-level dependencies are still useful in p2 to express additional dependencies that are not present at the plug-in level. For example, you may want your feature to include documentation, source code, or other artifacts from other plug-ins that are not strictly required by any plug-ins in your feature.

Dependencies on third party libraries

The versioning guidelines are only intended for versioning of Eclipse bundles, and for expressing dependency on bundles that follow the Eclipse versioning guidelines. We should specifically call this out in the guidelines, and offer some guidance on how to handle third party bundles. See bug 262018 for further discussion.

Changes

The following sections are proposed replacements for the corresponding sections in the Version Numbering guidelines. Each section of the proposed changes was started with the original guideline text, so you can review the specific changes by comparing the current revision of this document to previous revisions.

To require features or to require bundles

A feature can express its external dependencies as required features, required plug-ins, or a combination of the two. How dependencies are expressed has consequences on the install-time behavior of your feature, so it is important to understand the different approaches. These approaches are described below along with a discussion of their effect. It is important to note that since Ganymede (Eclipse 3.4), feature dependencies do not have to express dependencies that are already expressed at the plug-in level. Such duplication or further refinement of dependency information between features and plug-ins may unnecessarily restrict the ability to install the feature. With the classic Eclipse Update Manager that was the default install/update technology prior to Eclipse 3.4, dependency information was required at the feature level because the provisioning technology only reasoned at the level of features.

Require bundles

If your feature only requires a subset of plug-ins from another feature, you should express your dependencies at the plug-in level. This avoids the brittleness caused by version changes in required features, and allows system integrators to deliver the required plug-ins using different features if desired. Note that feature plug-in dependencies are only needed for plug-ins that are not already required by plug-ins in your feature. In other words, plug-in dependencies at the feature level are for expressing "soft" dependencies on plug-ins that are not strictly required by the plug-ins in your feature, such as documentation.

Expressing dependencies directly at the plug-in level has the benefit of isolating feature authors from changes that do not impact them, thus resulting in greater reusability of the feature.

Example:

 Case 1: Assuming the feature org.eclipse.gef is as follows:
    requires feature org.eclipse.platform	3.1.0
    contains plugins:
      org.eclipse.draw2d	3.1.0
      org.eclipse.gef		3.1.0
 
 Case 2: It is better to express this as:
     contains plugins:
       org.eclipse.draw2d	3.1.0
       org.eclipse.gef		3.1.0  
     requires plugins:
       org.eclipse.core.runtime [3.1.0, 4.0.0)
       org.eclipse.ui.views     [3.1.0, 4.0.0)
       org.eclipse.ui.workbench [3.1.0, 4.0.0)
       org.eclipse.jface        [3.1.0, 4.0.0)
       org.eclipse.swt		[3.1.0, 4.0.0)

In case 1, if the version of the org.eclipse.platform feature changes to 4.0.0 (because org.eclipse.core.resources changes its major version number), org.eclipse.gef is required to deliver a new version of its features. In case 2, such changes are transparent to the author of GEF.

• Note: The example above is for the purpose of illustration only. In practice the "requires" dependencies mentioned above are already expressed at the GEF bundle level, so they do not need to be repeated at the feature level:
  • MANIFEST.MF of org.eclipse.draw2d already "requires" org.eclipse.swt
  • MANIFEST.MF of org.eclipse.gef already "requires" org.eclipse.core.runtime, org.eclipse.ui.views, org.eclipse.ui.workbench, org.eclipse.jface

Require features

Use required features when you want another entire feature to be present when your feature is installed. This typically results in a user-level awareness of the required feature, rather than a hidden implementation detail of your feature. For example, users installing J2EE tools from the Web tools project also require Java development tools. This is not just because their plug-ins depend on plug-ins in JDT, but because users of the J2EE tools really expect the full JDT to be there, including documentation, help content, and possibly source. In this case the dependency should be expressed at the feature level to ensure the entire required feature is installed. Feature-level dependencies are also required if you are targeting a platform using the classic Eclipse Update Manager, which operated purely at the level of feature dependencies.

Dependency on plug-ins that wrap external libraries

The version range guidelines above are only effective if the required bundle or feature follows the Eclipse version number evolution guidelines outlined in this document. When specifying a dependency on third party libraries, be sure you understand the semantics of that library's version numbers, and specify your version range accordingly. In the absence of any well defined version evolution semantics, you should just specify the version number you require.

Example: JFace requires a third party library wrapped in bundle com.xyz.widgets, and is compiled against version 3.8.1 of that bundle. It should specify its dependency as follows: Require-Bundle: com.xyz.widgets;version="3.8.1"