NOTE: This proposal is obsolete. See the new Eclipse Plug-in Versioning proposal that has been adopted in Eclipse 3.2.

Eclipse Plug-in Versioning

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: November 21, 2004

Problem Definition

Current Eclipse practice calls for the teams to increment plug-in version numbers to match the upcoming release of Eclipse. For example, some months ago we changed our plug-in version numbers from 3.0.0 to 3.1.0. In May 2005 we will ship Eclipse 3.1 and all plug-ins (save a few third party ones) will be version 3.1.0. This is convenient because it allows people to look at the plug-in version number and immediatly understand what version of Eclipse that plug-in is from.

This approach has several drawbacks however


To address these concerns, we propose that the Eclipse SDK team start using the version number semantics defined by Eclipse for all their plug-ins. The numbering process works as follows:- new plug-ins 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.

Use of the qualifier

The current versioning scheme is effectively highlighting release families. A release family is a set of releases which form a substantial and separable effort. For example, Eclipse 2.0, 2.1, 3.0 and 3.1 are all different release families. The life of release family continues after its initial release (e.g., 3.0) to include maintenance releases (e.g., 3.0.1, 3.0.2, ...). Using family numbers as the base for plugin version numbers is convenient and easy to relate to but, as we have seen, conflicts with the Eclipse versioning semantics. The proposal outlined above summarily dumps release family notions in favour of semantically correct version numbers. This is has its own problems.

For example, assume we have implemented the proposal above.

In this case we have to different sets of content for but the version number is the same. In the current model the plugins would have version numbers based on their release family and so their intended target would be clear. The question then is how to mix-in the release family progression with the plugin content progression. The first three segments of the version number have clearly defined semantics which do not match the needs for identifying releases or release families. The qualifier (fourth segment) however has no particular semantics and so is free for use.

We propose the use of a convention where the release family is the first two digits of the qualifier. In the above example this gives the following version numbers (respectively)

These are both semantically correct (i.e., numbering indicates the degree of change) and easily understood as being related to 3.1 and 3.0. This story is sufficient if we are only concerned about comparing version numbers from release to release. The other way in which the current (and above) scheme fall down is that during the development cycle, the version number of a plugin never changes even though its content may change dramatically. This makes it nearly impossible for the Update technology to be used successfully on milestone or integration builds. A refinement to the use of the qualifier resolves this.

Noticing that plugin version numbers are intended to relate to content, the qualifier should include the version tag from the map file used for the build. Eclipse is built by reading a map file which lists a CVS repository location and a version tag to use when fetching the content. If a team has no input for a build, they do not update the map file and the version (and thus the plugin) remains unchanged and identical plug-ins will not be duplicated on the update site and consumers will not have to download them if they already have them.

Using this approach the qualifier looks like <release family>_<tag>. In the example from above this approach give the following version numbers respectively:

This approach gives version numbers which correctly reflect the progression of the content and respects the release family progression.


Generating the warm fuzzies

The main issue that arises from this proposal is that some people have been getting a warm fuzzy feeling from the current state where plugin version numbers do "match" the release version number. Unfortunately this sense of happiness is false.

The true warmth generator is a relatively simple tool that checks the installed set of pluigns/features against a bill of materials generated as part of the build. The output of this tools shows up in the Configuration Details dialog to warm service personel and in the feature/plugins views of the About dialog to warm users. For example, in the configuration details, any discrepencies are highlighted while in the About dialog the matchin is rendered, for example, as a green check mark beside plugins that match the bill of materials.

Existing uses of the qualifier

In some cases we currently use the qualifier to indicate emergency fixes or patches. Version numbers such as indicate an emergency change made for 3.0.1 while it was in the field. This proposal does not conflict with that approach though it does indicate a different approach. as a version number does generate some warmth as a minor fix to 3.0.1. Under our proposal the version numbering would look more like: = base version in the 3.0.1 release = patch for the plugin in the 3.0.1 release

Again, rather than using the version numbers themselves to generate (a somewhat false) warmth, the simple reporting tool would correctly identify the configuration as having been patched.


The main action required is to decide we want to do this and refine/document the details of the structure and process. PDE build would need some very minor modifications to accomodate the addition of the release family number but otherwise there are no technological hurdles. This approach dovetails nicely with a proposal to enhance Eclipse's use of the update technology. See Update Site Proposal for more details.

Going forward teams would be responsible for updating the plugin version just as they are responsible for updating their copyright dates, etc. Note however that these changes are done very infrequently and will not be a particular burden.


If we decide to follow this new policy we can retrofit the 3.1 plug-ins with "correct" version numbers or start the new approach immediately following the release of Eclipes 3.1. Starting now avoids situations where Eclipse 3.0 based plug-ins do not work on the released 3.1 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.1.0 version numbers.

A concrete proposal for how to do this follows:

  1. Assume that the baseline version number is 3.0.0
  2. All teams do a quick review of their plugin changes and update their plugin version numbers correctly reflect the degree of change since 3.0.0.
  3. All version numbers are updated to have a ".qualifier" suffix (e.g., 3.0.1.qualifier).
  4. The line "qualifier = context" is added to all files
  5. PDE build is setup to add "31_" to the qualifier context for current builds