| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN2"> | |
| <html> | |
| <head> | |
| <title>Plug-in Versioning</title> | |
| <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> | |
| <meta http-equiv="Content-Style-Type" content="text/css"> | |
| <link href="http://dev.eclipse.org/default_style.css" rel="stylesheet" type="text/css"> | |
| </head> | |
| <body bgcolor="#ffffff"> | |
| <table width="100%"> | |
| <tr><td style="background:#0080C0"><b><span style="color:white">Proposal</span></b></td></tr> | |
| </table> | |
| <p> | |
| <b>NOTE:</b> This proposal is obsolete. See the new <a href="http://www.eclipse.org/equinox/documents/plugin-versioning.html"> | |
| Eclipse Plug-in Versioning</a> proposal that has been adopted in Eclipse 3.2. | |
| </p> | |
| <h1>Eclipse Plug-in Versioning</h1> | |
| <blockquote> | |
| <p><b>Summary</b> <br> | |
| 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.</p> | |
| <p>Last Modified: | |
| November 21, 2004</p> | |
| </blockquote> | |
| <h2>Problem Definition</h2> | |
| <p>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.</p> | |
| <p>This approach has several drawbacks however</p> | |
| <ul> | |
| <li>Incrementing the major (first) | |
| version segment renders the plug-in "incompatible" with | |
| all previous versions of that plug-in. Dependent plug-ins 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 plug-in. Unresolved | |
| plug-ins cannot participate in a running Eclipse environment. Even though | |
| we have worked hard to make the content of the 3.0 plug-ins binary backward | |
| compatible, | |
| 2.1 based third party plug-ins (which specify prereq version numbers) require | |
| changes to work in 3.0.</li> | |
| <li>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, plug-ins 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.</li> | |
| <li> 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 | |
| plug-in | |
| from 3.0 will run on ANY version of the Eclipse runtime. People who build | |
| and distribute plug-ins are not generally able to play it quite so fast | |
| and loose.</li> | |
| <li> Features are not the cure. To address some of this, we use features and | |
| their abilily to group plug-ins. The assumption is that if the feature | |
| constraints are met, then the underlying plug-ins will all be happy and thus | |
| versioned | |
| plug-in dependencies are not needed. This works but assumes that the feature | |
| writer | |
| (may not be related to the plug-in authors) can understand the plug-in | |
| constraints well enough to define the feature. In practice this means that | |
| the plug-ins | |
| 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 plug-ins. 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. And finally, features | |
| are an update mechanism and update is not required to be in a running configuration.</li> | |
| </ul> | |
| <h2>Proposal</h2> | |
| <p> 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. </p> | |
| <ul> | |
| <li> Immediately after a release, plug-ins continue with the same number as | |
| they had in the release (e.g., 1.0.0). </li> | |
| <li> As the plug-in is developed (whether for a new release or for maintenance), | |
| the first three segments of 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.</li> | |
| <li> A plug-in's version number need only be incremented to distinguish one | |
| release from another. For example, if we release 1.0.0 of a plug-in and then | |
| do some | |
| bug fixes for a milestone (say M3), we increment the version to 1.0.1. | |
| If that plug-in 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. </li> | |
| <li> Plug-in version number changes are solely at the discretion of the plug-in | |
| development team. They are in the best position to understand their changes | |
| and the scope of impact.</li> | |
| <li> Features are used to group together plug-ins 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 plug-ins in the 3.0 platform.</li> | |
| </ul> | |
| <h3>Use of the qualifier</h3> | |
| <p>The current versioning scheme is effectively highlighting <em> release | |
| families</em>. | |
| 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.</p> | |
| <p>For example, assume we have implemented the proposal above.</p> | |
| <ul> | |
| <li>On June 25, 2004 Eclipse 3.0 is released. org.eclipse.foo is version 1.2.0</li> | |
| <li> The next day a maintenance stream is created in CVS to continue development | |
| for the 3.0.x family of releases.</li> | |
| <li>On June 29, 2004 someone does a minor bug | |
| fix to org.eclipse.foo in HEAD and ups the plugin version number to 1.2.1 | |
| (correctly capturing the nature of the change)</li> | |
| <li>On July 7, 2004 someone does a | |
| different minor bug fix to org.eclipse.foo in the maintenance stream | |
| and ups the plugin version number to 1.2.1 (correctly capturing the nature | |
| of the change)</li> | |
| <li>nothing | |
| else happens to org.eclipse.help before both Eclipse 3.0.1 and Eclipse | |
| 3.1 ship.</li> | |
| </ul> | |
| <p>In this case we have to different sets of content for org.eclipse.foo 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.</p> | |
| <p>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)</p> | |
| <blockquote> | |
| <p>1.2.1.31<br> | |
| 1.2.1.30</p> | |
| </blockquote> | |
| <p>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.</p> | |
| <p>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.</p> | |
| <p>Using this approach the qualifier looks like <release family>_<tag>. In the | |
| example from above this approach give the following version numbers respectively:</p> | |
| <blockquote> | |
| <p> 1.2.1.31_v20040629<br> | |
| 1.2.1.30_v20040707</p> | |
| </blockquote> | |
| <p>This approach gives version numbers which correctly reflect the progression | |
| of the content and respects the release family progression.</p> | |
| <h2>Issues</h2> | |
| <h3>Generating the warm fuzzies</h3> | |
| <p>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. </p> | |
| <ul> | |
| <li> Between releases the plugin contents change but the numbers stay the same. | |
| This apparent matching is only relevant for final GA releases.</li> | |
| <li>Some plugins | |
| (e.g., 3rd party) do not have matching numbers (e.g., lucene) </li> | |
| <li>No warmth | |
| is generated regarding additions or deletions of plugins or features. | |
| Sure they are all numbered nicely but are the right things there?</li> | |
| </ul> | |
| 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. | |
| <h3>Existing uses of the qualifier</h3> | |
| <p>In some cases we currently use the qualifier to indicate emergency fixes or | |
| patches. Version numbers such as 3.0.1.1 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. 3.0.1.1 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:</p> | |
| <blockquote> | |
| <p>1.2.1.30_v20040911 = base version in the 3.0.1 release<br> | |
| 1.2.1.30_v20041004 = | |
| patch for the plugin in the 3.0.1 release</p> | |
| </blockquote> | |
| <p>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.</p> | |
| <h2>Action</h2> | |
| <p>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 <a href="http://dev.eclipse.org/viewcvs/index.cgi/%7Echeckout%7E/platform-core-home/documents/update.html">Update Site Proposal</a> for more details.</p> | |
| <p>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.</p> | |
| <h3>Transitioning</h3> | |
| <p>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.</p> | |
| <p>A concrete proposal for how to do this follows:</p> | |
| <ol> | |
| <li>Assume that the baseline version number is 3.0.0</li> | |
| <li>All teams do a quick review of their plugin changes and update their plugin | |
| version numbers correctly reflect the degree of change since <strong>3.0.0</strong>.</li> | |
| <li>All version numbers are updated to have a ".qualifier" suffix (e.g., 3.0.1.qualifier).</li> | |
| <li>The line "qualifier = context" is added to all build.properties | |
| files</li> | |
| <li>PDE build is setup to add "31_" to the qualifier context for current builds<br> | |
| </li> | |
| </ol> | |
| </body> | |
| </html> |