Eclipse Plug-in Versioning Proposal

Summary
The Eclipse team currently changes their plug-in version numbers to match each major release of Eclipse (e.g., 2.1, 3.0). This is a convenient way of understanding the origin of plug-ins but do not capture the actual semantics of the changes which occurred. For example, the change from 2.1 to 3.0 indicates a major and incompatible change. Of course, this is generally not what was intended as most 3.0 plug-ins are in fact compatible with their 2.1 versions. Here we outline the current use of version numbers and propose a new process for using plug-in version numbering to better indicate levels of compatibility.
Last Modified: 1200 February 17, 2004

Problem Definition

Current Eclipse practice calls for the teams to increment plugin version numbers to match the upcoming release of Eclipse. For example, about 6 months ago we changed our plugin version numbers from 2.1 to 3.0.0. In June 2004 we will ship Eclipse 3.0.0 and all plugins (save a few third party ones) will be version 3.0.0. This is convenient because it allows people to look at the plugin version number and immediatly understand what version of Eclipse that plugin is from.

This approach has several drawbacks however

• Incrementing the major (first) version segment renders the plugin "incompatible" with all previous versions of that plugin. Dependent plugins which specify a version number (e.g., <import plugin="org.eclipse.foo" version="2.1.0"/>) will not resolve against version 3.0.0 of the prerequisite plugin. Unresolved plugins cannot participate in a running Eclipse environment. Even though we have worked hard to make the content of the 3.0 plugins binary backward compatible, 2.1 based third party plugins (which specify prereq version numbers) require changes to work in 3.0.
• This approach does not set a good example. People building on top of Eclipse look to us to understand how they should structure their world. Following this model, plugins like EMF and GEF should increment their version numbers to match the Eclipse version numbers regardless of whether they changed at all. This has the nasty side effect of rendering all of their users incompatible as well. It also does not scale well as a little change at the bottom then ripples all the way up.
• Eclipse is getting away with this because a) we are at the bottom of the stack, b) we ship a single wad that is built, packaged and distributed in unison and c) we do not use version numbered prerequisites ourselves. It is really this last point which hurts the most. By not using versioned prereqs, we are not eating our own dog food. Clearly we do not mean that the resources plugin from 3.0 will run on ANY version of the Eclipse runtime. People who build and distribute plugins are not generally able to play it quite so fast and loose.
• Features are not the cure. To address some of this, we use features and their abilily to group plugins. The assumption is that if the feature constraints are met, then the underlying plugins will all be happy and thus versioned plugin dependencies are not needed. This works but assumes that the feature writer (may not be related to the plugin authors) can understand the plugin constraints well enough to define the feature. In practice this means that the plugins in the feature all have similar constraints such that they can be distilled to a smaller set of inter feature constraints. Features are a packaging mechanism for plugins. Pushing constraint satisfaction up to the packaging layer puts a significant load both on the people creating the packages (e.g., features) as well as the packaging (e.g., feature) mechanism.

Proposal

To address these concerns, we propose that the Eclipse SDK team start using the version number semantics defined by Eclipse for all their plugins. The numbering process works as follows:- new plugins start as 0.0.0 and go through various version numbers (<1.0.0) until they are ready for their first release. At that time, developers may choose to set the version number to 1.0.0. This is mostly cosmetic and is not required. Prior to first release the numbering process depends mostly on how widely availability and use of the early versions. For example, a beta at 0.9 sets a good tone and might encourage release at 1.0.0.

• Immediately after a release, plugins continue with the same number as they had in the release (e.g., 1.0.0).
• As the plugin is developed for the next release, the version number is changed to accurately reflect those changes. For example, if some minor fixes are done, the service (third) segment should be incremented (e.g., 1.0.1). If significant but compatible rework is done and/or new function added, the minor (second) segment should be incremented. (e.g., 1.1.0). Note that in this example, the significant work overshadows the service fixes so the service (third) segment is set to 0. If major rework is done such that the new version is incompatible with previous versions then the major (first) segment should be incremented (e.g., 2.0.0) Note that the minor and service numbers are 0 here as well.
• A plugin's version number need only be incremented to distinguish one release from another. For example, if we release 1.0.0 of a plugin and then do some bug fixes for a milestone (say M3), we increment the version to 1.0.1. If that plugin were eventually released, people could look at the version number and see that a) it is different from 1.0.0 and b) that some bug fixes were done. If instead, further bug fixes are done for M5, there is no need to further increment in the version number (i.e., to 1.0.2). Leaving the version at 1.0.1 still conveys the important information to users of the next release. Of course, teams could increment the version further if needed/desired. Either way, the qualifier (fourth) version segment can be used (e.g., 1.0.1.M3 vs 1.0.1.M5) to differentiate between builds of the same version.
• Plugin version number changes are solely at the discretion of the plugin development team. They are in the best position to understand their changes and the scope of impact.
• Features are used to group together plugins and label them with a particular "product" release version (e.g., 3.0). The org.eclipse.platform 3.0.0 feature contains a complete and precise specification of the plugins in the 3.0 platform.

Action

The only action required is to decide we want to do this and refine/document the details of the structure and process. There are no technological hurdles. Just as teams are responsible updating their copyright dates, they would be responsible for incrementing their plugin versions. These changes are done very infrequently so will not be a particular burden.

If we decide to follow this new policy we can retrofit the 3.0 plugins with "correct" version numbers or start the new approach immediately following the release of Eclipes 3.0. Starting now avoids situations where Eclipse 2.1 based plugins do not work on the released 3.0 because of resolution problems (rather than because of actual incompatibilities). However, it may adversely affect people in the community who have already come to know, like and use the 3.0.0 version numbers.