Version Numbering Europa Update

As more projects have begun using the Eclipse project Version Numbering Guidelines, further clarification is required to capture the development processes of different projects. To this end, a number of updates have been made for the Europa Simultaneous Release since the initial guidelines were written. This document describes the changes, along with the motivation for the change.

When to increment the service segment

The initial guidelines stated that the service segment must be incremented when there is a "bug fix". This criterion is unclear, because the kind of change that constitutes a "bug fix" is open to interpretation. For example, is a documentation change or a change to compiler settings considered a bug fix? The answer is yes. The guidelines have been revised to state:

  The service segment number must be incremented whenever there have been changes to a           
  plug-in between releases that are not visible in its API. For example, a bug has been 
  fixed in the code, the plug-in manifest has changed, documentation has changed, 
  compiler settings have changed, etc.

In other words, if the bits on disk have changed, then at least your service segment must also change. This guideline ensures that the builds prior to a release can be distinguished from builds made to a maintenance stream after a release. This also ensures that the update manager and OSGi resolver will always correctly pick the version of the plug-in from the most recent release. Relying on the lexicographical order of the qualifier segment for this task is error prone, since a simple typo when tagging a project for a build could result the wrong version being chosen (for example changing from "v20060601" to "V20060602", or "v20060601" to "I20060602", or "v20051231" to "v20050101", to give just three examples of mistakes that have been made).

Managing multiple maintenance branches

The initial guidelines assumed there would only ever be one maintenance branch under active development at a time, along with one primary development branch, for a total of two branches. This assumption stemmed from the Eclipse project policy of only maintaining one maintenance branch. However, other projects can and do occasionally perform ongoing maintenance in multiple branches. For the most part, the existing guidelines continue to be useful across arbitrary simultaneous branches.

The important extra rule here is to ensure you "leave room" whenever performing maintenance on a branch that is not your oldest maintenance branch. If you have maintenance branches for releases N, N+1, and N+2, the increment by 100 rule applies in the N+1 branch, and you must increment by another 100 in the N+2 branch. This ensures there is room to make changes in the N maintenance branch without overlapping version numbers. This paragraph has been added to the guidelines to clarify this.

Minor version changes in a maintenance branch

The initial guidelines said only this about changing the minor segment of a version number in a maintenance branch:

  Such changes would not typically be made when working in a maintenance stream.

This isn't particularly useful for those who have a compelling need to introduce new API in a maintenance branch. This paragraph has been added to the guidelines to clarify how this should be handled.

Correction of feature versioning example

There was an error in the feature versioning example that incorrectly made the org.eclipse.gef feature require the org.eclipse.platform feature:

 Case 2: In the new model it should be:
     requires feature org.eclipse.platform	3.1.0 [removed this line]
     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)

The corrected example can be found here.

Guidelines for format of qualifier segment

It was noted in bug 162559 that there is little consistency in the format of the qualifier segment across plug-ins. In practice, the format of the segment does not matter as long as the version can be traced back to a unique build input, and that the number increases lexicographically. However, it looks sloppy and is more error prone when consistent numbering isn't used. To encourage a more consistent format, the following has been added to the guidelines

  We recommend using the date formatted as vYYYYMMDD (year, month day). If you have 
  multiple builds in a day, you can add "-HHMM" (hour, minute) to ensure it is unique.

  It is also recommended that you prefix the tag on a maintenance branch with a unique 
  branch identifier to ensure that builds on that branch can be distinguished from 
  builds on the main development branch. For example, a branch for maintenance of the 
  1.0 release can use a prefix of "R10x_" so that all builds on that branch for the 
  1.0.x maintenance releases are grouped together. 

Again, these formats are not strictly required, but it looks better when projects using a consistent format. The Eclipse platform releng build tool facilitates this by automatically populating the version number combo box in the release wizard with a tag using this format. Simply open the combo and pick the first version in the list to be sure you are following the format. Some projects use a format with an "I" prefix for integration builds, and an "M" prefix for maintenance builds, but this format breaks down when there are multiple ongoing maintenance streams.

Patch features

No guidelines were initially provided for how patch features should be numbered. This paragraph has been added to describe how patch features should be versioned.

Guidelines for exported plug-ins

The initial version numbering guidelines made a simplistic assumption about the effect of exporting another plug-in. The guidelines asserted that by exporting another plug-in, you are effectively exposing that entire plug-in in your API, and must therefore increment version numbers in lock step with that plug-in in each release. This guideline proved to be impractical for projects that made extensive use of re-exports. This thread on the cross-project-issues-dev mailing list describe the problem and ensuing discussion in some detail.

In reality, when a plug-in B exports a range [X,Y) for another plug-in A, it is only promising to downstream plug-ins that some version in that range will be available at runtime. This means that clients can really only call APIs that exist in version X of plug-in A, because that is the minimal version that they can be sure to have resolved at runtime. If plug-in A changes version in a subsequent release, but stays within the [X,Y) range, then no change has been made to the contract of B.

The important question for B that arises is how changing the [X,Y) bound will affect downstream clients. It turns out that changing the upper bound Y has absolutely no effect, because as noted, downstream plug-ins can only rely on the lower bound version being present. This leaves only the question of guidelines for changing the lower bound. There are six categories of changes that can be made to the lower bound:

1. Decrease the service segment. This has no effect because versions within a service release are entirely interchangeable. There can be no changes to the API contract between the two versions, so clients are not affected by this change.
2. Decrease the minor segment. This is a breaking change. A downstream plug-in may be safely calling methods introduced in version X of plug-in A. If the range is rolled back to X-1, that API will no longer be present and a linkage error will occur at runtime.
3. Decrease the major segment. It follows from above that this is also a breaking change.
4. Increase the service segment. As in 1), plug-ins within a service stream should be interchangeable, so this has no effect on downstream plug-ins
5. Increase the minor segment. When the minor segment changes from X to X+1, downstream plug-ins can now begin calling new API introduced in version X+1. This is equivalent to introducing new compatible API, so the minor segment must be increased
6. Increase the major segment. This exposes any breaking changes made in plug-in A to plug-ins downstream from B, so it is also considered a breaking change. B must increment its major segment.

These three cases can be broken down into three simple rules:

1. Decrease service segment of lower bound: increase service segment
2. Decrease major or minor segment of lower bound: increase major segment
3. Increase lower bound: increase version by the same magnitude

These three rules have been encoded in the guidelines, along with examples. The relevant section in the guidelines is found here.