Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "Version Numbering Galileo Update"
(New page: This document describes updated to the Eclipse Version Numbering guidelines from the Galileo simultaneous release. Specifically, this document revises the version numbering guideli...) |
|||
| Line 1: | Line 1: | ||
| − | This document describes | + | This document describes proposed updates to the Eclipse [[Version Numbering]] guidelines from 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. |
| + | |||
| + | = Background = | ||
| + | |||
| + | 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 install 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. | ||
| + | |||
| + | = Changes = | ||
| + | |||
| + | The following sections are proposed replacements for the corresponding sections in the [[Version Numbering]] guidelines. The initial draft of this document contained the original guideline text, so you can review the specific changes by comparing the current revision of this document with the first revision. | ||
| + | |||
| + | === To Require Features or To Require Bundles === | ||
| + | |||
| + | ==== Require Bundles ==== | ||
| + | |||
| + | To avoid the brittleness caused by version changes in required features, we recommend feature authors favor the expression of their dependencies at the plug-in level, rather than at the feature level. To be more precise, all the immediate plug-ins required by the plug-ins included in a feature should be listed as plug-in prerequisite of the feature. This approach has the benefit of isolating feature authors from changes that do not impact them. | ||
| + | |||
| + | <span id="feature_example"></span><b>Example:</b> | ||
| + | |||
| + | <pre> | ||
| + | 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) | ||
| + | |||
| + | </pre> | ||
| + | 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. | ||
| + | |||
| + | ==== Require Features ==== | ||
| + | |||
| + | Consider what your user wants or needs. For example, those in WTP (JST in particular) need JDT ... and it is not just that their code bundles need some of the bundles in JDT ... JST users really would expect the full JDT to be there, including docs, infopops-help, and source (if SDK). So, there may be some cases for a feature to not require only bundles, but whole features. | ||
Revision as of 11:27, 2 January 2009
This document describes proposed updates to the Eclipse Version Numbering guidelines from 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.
Contents
Background
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 install 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.
Changes
The following sections are proposed replacements for the corresponding sections in the Version Numbering guidelines. The initial draft of this document contained the original guideline text, so you can review the specific changes by comparing the current revision of this document with the first revision.
To Require Features or To Require Bundles
Require Bundles
To avoid the brittleness caused by version changes in required features, we recommend feature authors favor the expression of their dependencies at the plug-in level, rather than at the feature level. To be more precise, all the immediate plug-ins required by the plug-ins included in a feature should be listed as plug-in prerequisite of the feature. This approach has the benefit of isolating feature authors from changes that do not impact them.
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.
Require Features
Consider what your user wants or needs. For example, those in WTP (JST in particular) need JDT ... and it is not just that their code bundles need some of the bundles in JDT ... JST users really would expect the full JDT to be there, including docs, infopops-help, and source (if SDK). So, there may be some cases for a feature to not require only bundles, but whole features.