platform-core-home/documents/plugin-versioning.html
Parent Directory
| 
Revision Log
Revision 1.5 - (view) (download) (as text)
| 1 : | jeff | 1.5 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN2"> |
| 2 : | jeff | 1.2 | <html> |
| 3 : | <head> | ||
| 4 : | jeff | 1.5 | <title>Plug-in Versioning</title> |
| 5 : | <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> | ||
| 6 : | <meta http-equiv="Content-Style-Type" content="text/css"> | ||
| 7 : | <link href="http://dev.eclipse.org/default_style.css" rel="stylesheet" type="text/css"> | ||
| 8 : | jeff | 1.1 | </head> |
| 9 : | jeff | 1.5 | <body bgcolor="#ffffff"> |
| 10 : | jeff | 1.1 | |
| 11 : | jeff | 1.5 | <table width="100%"> |
| 12 : | <tr><td style="background:#0080C0"><b><span style="color:white">Proposal</span></b></td></tr> | ||
| 13 : | </table> | ||
| 14 : | <h1>Eclipse Plug-in Versioning</h1> | ||
| 15 : | jeff | 1.1 | <blockquote> |
| 16 : | <p><b>Summary</b> <br> | ||
| 17 : | jeff | 1.2 | The Eclipse team currently changes their plug-in version numbers to match each |
| 18 : | major release of Eclipse (e.g., 2.1, 3.0). This is a convenient | ||
| 19 : | way of understanding the origin of plug-ins but do not capture the actual | ||
| 20 : | semantics of the changes which occurred. For | ||
| 21 : | example, the change from 2.1 to 3.0 indicates a major and incompatible change. | ||
| 22 : | Of | ||
| 23 : | course, this | ||
| 24 : | is | ||
| 25 : | generally not what was intended as most 3.0 plug-ins are in fact compatible | ||
| 26 : | with their 2.1 versions. Here we outline the current use of version numbers | ||
| 27 : | and propose a new process for | ||
| 28 : | using | ||
| 29 : | plug-in | ||
| 30 : | jeff | 1.5 | version numbering to better indicate levels of compatibility.</p> |
| 31 : | <p>Last Modified: | ||
| 32 : | November 21, 2004</p> | ||
| 33 : | jeff | 1.1 | </blockquote> |
| 34 : | |||
| 35 : | <h2>Problem Definition</h2> | ||
| 36 : | jeff | 1.5 | <p>Current Eclipse practice calls for the teams to increment plug-in version |
| 37 : | numbers to match the upcoming release of Eclipse. For example, some months | ||
| 38 : | ago we | ||
| 39 : | changed our plug-in version numbers from 3.0.0 to 3.1.0. In May 2005 we will | ||
| 40 : | ship Eclipse 3.1 and all plug-ins (save a few third party ones) will be version | ||
| 41 : | 3.1.0. This is convenient because it allows people to look at the plug-in version | ||
| 42 : | dj | 1.4 | number and immediatly understand what version of Eclipse that plug-in is from.</p> |
| 43 : | jeff | 1.1 | <p>This approach has several drawbacks however</p> |
| 44 : | <ul> | ||
| 45 : | <li>Incrementing the major (first) | ||
| 46 : | dj | 1.4 | version segment renders the plug-in "incompatible" with |
| 47 : | all previous versions of that plug-in. Dependent plug-ins which specify a version | ||
| 48 : | jeff | 1.1 | number (e.g., <import plugin="org.eclipse.foo" version="2.1.0"/>) |
| 49 : | dj | 1.4 | will not resolve against version 3.0.0 of the prerequisite plug-in. Unresolved |
| 50 : | plug-ins cannot participate in a running Eclipse environment. Even though | ||
| 51 : | we have worked hard to make the content of the 3.0 plug-ins binary backward | ||
| 52 : | jeff | 1.1 | compatible, |
| 53 : | dj | 1.4 | 2.1 based third party plug-ins (which specify prereq version numbers) require |
| 54 : | jeff | 1.1 | changes to work in 3.0.</li> |
| 55 : | <li>This approach does not set a good example. People building on top of | ||
| 56 : | Eclipse look to us to understand how they should structure their world. | ||
| 57 : | Following this | ||
| 58 : | dj | 1.4 | model, plug-ins like EMF and GEF should increment their version numbers |
| 59 : | jeff | 1.1 | to match the Eclipse version numbers regardless of whether they changed |
| 60 : | at all. This | ||
| 61 : | has the nasty side effect of rendering all of their users incompatible | ||
| 62 : | as well. It also does not scale well as a little change at the bottom then | ||
| 63 : | ripples all | ||
| 64 : | the way up.</li> | ||
| 65 : | <li> Eclipse is getting away with this because a) we are at the bottom of | ||
| 66 : | the stack, b) we ship a single wad that is built, packaged and distributed | ||
| 67 : | in unison | ||
| 68 : | and c) we do not use version numbered prerequisites ourselves. It is | ||
| 69 : | really this last point which hurts the most. By not using versioned prereqs, | ||
| 70 : | we | ||
| 71 : | are not eating our own dog food. Clearly we do not mean that the resources | ||
| 72 : | dj | 1.4 | plug-in |
| 73 : | jeff | 1.1 | from 3.0 will run on ANY version of the Eclipse runtime. People who build |
| 74 : | dj | 1.4 | and distribute plug-ins are not generally able to play it quite so fast |
| 75 : | jeff | 1.1 | and loose.</li> |
| 76 : | <li> Features are not the cure. To address some of this, we use features and | ||
| 77 : | dj | 1.4 | their abilily to group plug-ins. The assumption is that if the feature |
| 78 : | constraints are met, then the underlying plug-ins will all be happy and thus | ||
| 79 : | jeff | 1.1 | versioned |
| 80 : | dj | 1.4 | plug-in dependencies are not needed. This works but assumes that the feature |
| 81 : | jeff | 1.1 | writer |
| 82 : | dj | 1.4 | (may not be related to the plug-in authors) can understand the plug-in |
| 83 : | jeff | 1.1 | constraints well enough to define the feature. In practice this means that |
| 84 : | dj | 1.4 | the plug-ins |
| 85 : | jeff | 1.1 | in the feature all have similar constraints such that they can be distilled |
| 86 : | to a smaller set of inter feature constraints. Features are a packaging | ||
| 87 : | dj | 1.4 | mechanism for plug-ins. Pushing constraint satisfaction up to the packaging |
| 88 : | jeff | 1.1 | layer puts |
| 89 : | a significant load both on the people creating the packages (e.g., features) | ||
| 90 : | jeff | 1.5 | as well as the packaging (e.g., feature) mechanism. And finally, features |
| 91 : | are an update mechanism and update is not required to be in a running configuration.</li> | ||
| 92 : | jeff | 1.1 | </ul> |
| 93 : | <h2>Proposal</h2> | ||
| 94 : | <p> To address these concerns, we propose that the Eclipse SDK team start using | ||
| 95 : | dj | 1.4 | the version number semantics defined by Eclipse for all their plug-ins. The |
| 96 : | numbering process works as follows:- new plug-ins start as 0.0.0 and go through | ||
| 97 : | jeff | 1.1 | various version numbers (<1.0.0) |
| 98 : | until they are ready for their first release. At that time, developers may | ||
| 99 : | choose to set the version number to 1.0.0. This is mostly cosmetic and is not | ||
| 100 : | required. Prior to first release the numbering process depends mostly on how | ||
| 101 : | widely availability and use of the early versions. For example, a beta at 0.9 | ||
| 102 : | sets a good tone and might encourage release at 1.0.0. </p> | ||
| 103 : | <ul> | ||
| 104 : | dj | 1.4 | <li> Immediately after a release, plug-ins continue with the same number as |
| 105 : | jeff | 1.1 | they had in the release (e.g., 1.0.0). </li> |
| 106 : | jeff | 1.5 | <li> As the plug-in is developed (whether for a new release or for maintenance), |
| 107 : | the first three segments of the version number is changed to accurately reflect | ||
| 108 : | those | ||
| 109 : | changes. | ||
| 110 : | For | ||
| 111 : | example, if some | ||
| 112 : | minor | ||
| 113 : | fixes | ||
| 114 : | jeff | 1.1 | are done, |
| 115 : | the service (third) segment should be incremented (e.g., 1.0.1). If significant | ||
| 116 : | but compatible rework is done and/or new function added, the minor (second) | ||
| 117 : | segment should be incremented. (e.g., 1.1.0). Note that in this example, | ||
| 118 : | the significant work overshadows the service fixes so the service (third) | ||
| 119 : | segment | ||
| 120 : | is set to 0. If major rework is done such that the new version is incompatible | ||
| 121 : | with previous versions then the major (first) segment should be incremented | ||
| 122 : | (e.g., 2.0.0) Note that the minor and service numbers are 0 here as well.</li> | ||
| 123 : | dj | 1.4 | <li> A plug-in's version number need only be incremented to distinguish one |
| 124 : | release from another. For example, if we release 1.0.0 of a plug-in and then | ||
| 125 : | jeff | 1.1 | do some |
| 126 : | bug fixes for a milestone (say M3), we increment the version to 1.0.1. | ||
| 127 : | dj | 1.4 | If that plug-in were eventually released, people could look at the version |
| 128 : | jeff | 1.1 | number and |
| 129 : | see that a) it is different from 1.0.0 and b) that some bug fixes were | ||
| 130 : | done. If instead, further bug fixes are done for M5, there is no need to | ||
| 131 : | further | ||
| 132 : | jeff | 1.2 | increment in the version number (i.e., to 1.0.2). Leaving the version at |
| 133 : | 1.0.1 still conveys the important information to users of the | ||
| 134 : | next | ||
| 135 : | release. | ||
| 136 : | jeff | 1.5 | Of course, teams could increment the version further if needed/desired. </li> |
| 137 : | dj | 1.4 | <li> Plug-in version number changes are solely at the discretion of the plug-in |
| 138 : | jeff | 1.1 | development team. They are in the best position to understand their changes |
| 139 : | and the scope of impact.</li> | ||
| 140 : | dj | 1.4 | <li> Features are used to group together plug-ins and label them with a particular "product" release |
| 141 : | jeff | 1.1 | version (e.g., 3.0). The org.eclipse.platform 3.0.0 feature contains a complete |
| 142 : | jeff | 1.5 | and precise specification of the plug-ins in the 3.0 platform.</li> |
| 143 : | </ul> | ||
| 144 : | <h3>Use of the qualifier</h3> | ||
| 145 : | <p>The current versioning scheme is effectively highlighting <em> release | ||
| 146 : | families</em>. | ||
| 147 : | A release family is a set of releases which form a substantial and separable | ||
| 148 : | effort. For example, Eclipse 2.0, 2.1, 3.0 and 3.1 are all different release | ||
| 149 : | families. The life of release family continues after its initial release (e.g., | ||
| 150 : | 3.0) to include maintenance releases (e.g., 3.0.1, 3.0.2, ...). Using family | ||
| 151 : | numbers as the base for plugin version numbers is convenient and easy to | ||
| 152 : | relate to but, as we have seen, conflicts with the Eclipse | ||
| 153 : | versioning semantics. The proposal outlined above summarily dumps release family | ||
| 154 : | notions | ||
| 155 : | in favour of semantically correct version numbers. This is has its own | ||
| 156 : | problems.</p> | ||
| 157 : | <p>For example, assume we have implemented the proposal above.</p> | ||
| 158 : | <ul> | ||
| 159 : | <li>On June 25, 2004 Eclipse 3.0 is released. org.eclipse.foo is version 1.2.0</li> | ||
| 160 : | <li> The next day a maintenance stream is created in CVS to continue development | ||
| 161 : | for the 3.0.x family of releases.</li> | ||
| 162 : | <li>On June 29, 2004 someone does a minor bug | ||
| 163 : | fix to org.eclipse.foo in HEAD and ups the plugin version number to 1.2.1 | ||
| 164 : | (correctly capturing the nature of the change)</li> | ||
| 165 : | <li>On July 7, 2004 someone does a | ||
| 166 : | different minor bug fix to org.eclipse.foo in the maintenance stream | ||
| 167 : | and ups the plugin version number to 1.2.1 (correctly capturing the nature | ||
| 168 : | of the change)</li> | ||
| 169 : | <li>nothing | ||
| 170 : | else happens to org.eclipse.help before both Eclipse 3.0.1 and Eclipse | ||
| 171 : | 3.1 ship.</li> | ||
| 172 : | </ul> | ||
| 173 : | <p>In this case we have to different sets of content for org.eclipse.foo but | ||
| 174 : | the version number is the same. In the current model the plugins would have | ||
| 175 : | version numbers based on their release family and so their intended target | ||
| 176 : | would be clear. The question then is how to mix-in the release family progression | ||
| 177 : | with the plugin content progression. The first three segments of the version | ||
| 178 : | number have clearly | ||
| 179 : | defined semantics which do not match the needs for identifying releases or | ||
| 180 : | release families. The qualifier (fourth segment) however has no particular | ||
| 181 : | semantics and so is free for use.</p> | ||
| 182 : | <p>We propose the use of a convention where the release | ||
| 183 : | family is the first two digits of the qualifier. In the above example this | ||
| 184 : | gives the following version numbers | ||
| 185 : | (respectively)</p> | ||
| 186 : | <blockquote> | ||
| 187 : | <p>1.2.1.31<br> | ||
| 188 : | 1.2.1.30</p> | ||
| 189 : | </blockquote> | ||
| 190 : | <p>These are both semantically correct (i.e., numbering indicates the degree | ||
| 191 : | of change) and easily understood as being related to 3.1 and 3.0. This story | ||
| 192 : | is sufficient if we are only concerned about comparing version numbers from | ||
| 193 : | release to release. The other way in which the current (and above) scheme fall | ||
| 194 : | down is that during the development cycle, the version number of a plugin never | ||
| 195 : | changes even though its content may change dramatically. This makes it nearly | ||
| 196 : | impossible for the Update technology to be used successfully on milestone or | ||
| 197 : | integration builds. A refinement to the use of the qualifier resolves this.</p> | ||
| 198 : | <p>Noticing that plugin version numbers are intended to relate to content, the | ||
| 199 : | qualifier should | ||
| 200 : | include the version tag from the map file used for the build. Eclipse is built | ||
| 201 : | by reading a map file which lists a CVS repository location and a version tag | ||
| 202 : | to use when fetching the content. If a team has no input for a build, they | ||
| 203 : | do not update the map file and the version (and thus the plugin) remains unchanged | ||
| 204 : | and identical plug-ins will not be duplicated on the update site and consumers | ||
| 205 : | will not have | ||
| 206 : | to download them if they already | ||
| 207 : | have them.</p> | ||
| 208 : | <p>Using this approach the qualifier looks like <release family>_<tag>. In the | ||
| 209 : | example from above this approach give the following version numbers respectively:</p> | ||
| 210 : | <blockquote> | ||
| 211 : | <p> 1.2.1.31_v20040629<br> | ||
| 212 : | 1.2.1.30_v20040707</p> | ||
| 213 : | </blockquote> | ||
| 214 : | <p>This approach gives version numbers which correctly reflect the progression | ||
| 215 : | of the content and respects the release family progression.</p> | ||
| 216 : | <h2>Issues</h2> | ||
| 217 : | <h3>Generating the warm fuzzies</h3> | ||
| 218 : | <p>The main issue that arises from this proposal is that some people | ||
| 219 : | have been getting a warm fuzzy feeling from the current state where plugin | ||
| 220 : | version numbers do "match" the release version number. | ||
| 221 : | Unfortunately this sense of happiness is false. </p> | ||
| 222 : | <ul> | ||
| 223 : | <li> Between releases the plugin contents change but the numbers stay the same. | ||
| 224 : | This apparent matching is only relevant for final GA releases.</li> | ||
| 225 : | <li>Some plugins | ||
| 226 : | (e.g., 3rd party) do not have matching numbers (e.g., lucene) </li> | ||
| 227 : | <li>No warmth | ||
| 228 : | is generated regarding additions or deletions of plugins or features. | ||
| 229 : | Sure they are all numbered nicely but are the right things there?</li> | ||
| 230 : | jeff | 1.1 | </ul> |
| 231 : | jeff | 1.5 | The true warmth generator is a relatively simple tool that checks |
| 232 : | the installed set of pluigns/features against a bill of materials generated | ||
| 233 : | as part of the build. The output of this tools shows up in the Configuration | ||
| 234 : | Details | ||
| 235 : | dialog to warm service personel and in the | ||
| 236 : | feature/plugins views of the About dialog to warm users. For example, in the | ||
| 237 : | configuration details, any discrepencies are highlighted while in the About | ||
| 238 : | dialog the matchin is rendered, for example, | ||
| 239 : | as a green check mark beside plugins that match the bill of materials. | ||
| 240 : | <h3>Existing uses of the qualifier</h3> | ||
| 241 : | <p>In some cases we currently use the qualifier to indicate emergency fixes or | ||
| 242 : | patches. Version numbers such as 3.0.1.1 indicate an emergency change made | ||
| 243 : | for 3.0.1 while it was in the field. This proposal does not conflict with that | ||
| 244 : | approach though it does indicate a different approach. 3.0.1.1 as a version | ||
| 245 : | number does generate some warmth as a minor fix to 3.0.1. Under our proposal | ||
| 246 : | the version numbering would look more like:</p> | ||
| 247 : | <blockquote> | ||
| 248 : | <p>1.2.1.30_v20040911 = base version in the 3.0.1 release<br> | ||
| 249 : | 1.2.1.30_v20041004 = | ||
| 250 : | patch for the plugin in the 3.0.1 release</p> | ||
| 251 : | </blockquote> | ||
| 252 : | <p>Again, rather than using the version numbers themselves to generate (a somewhat | ||
| 253 : | false) warmth, the simple reporting tool would correctly identify the configuration | ||
| 254 : | as having been patched.</p> | ||
| 255 : | jeff | 1.1 | <h2>Action</h2> |
| 256 : | jeff | 1.5 | <p>The main action required is to decide we want to do this and refine/document |
| 257 : | the details of the structure and process. PDE build would need some very minor | ||
| 258 : | modifications to accomodate the addition of the release family number but otherwise | ||
| 259 : | there are no technological hurdles. This approach dovetails nicely with a proposal | ||
| 260 : | 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> | ||
| 261 : | <p>Going forward teams would be responsible for updating the plugin version just | ||
| 262 : | as they are responsible for updating their | ||
| 263 : | copyright | ||
| 264 : | dates, etc. Note however that these changes are done | ||
| 265 : | very infrequently and will not be a particular burden.</p> | ||
| 266 : | <h3>Transitioning</h3> | ||
| 267 : | <p>If we decide to follow this new policy we can retrofit the 3.1 | ||
| 268 : | plug-ins with "correct" version | ||
| 269 : | jeff | 1.1 | numbers or start the new approach immediately following the release of Eclipes |
| 270 : | jeff | 1.5 | 3.1. Starting now avoids situations where Eclipse 3.0 based plug-ins do not |
| 271 : | work on the released 3.1 because of resolution problems (rather than because | ||
| 272 : | jeff | 1.1 | of actual incompatibilities). However, it may adversely affect people in the |
| 273 : | jeff | 1.5 | community who have already come to know, like and use the 3.1.0 version numbers.</p> |
| 274 : | <p>A concrete proposal for how to do this follows:</p> | ||
| 275 : | <ol> | ||
| 276 : | <li>Assume that the baseline version number is 3.0.0</li> | ||
| 277 : | <li>All teams do a quick review of their plugin changes and update their plugin | ||
| 278 : | version numbers correctly reflect the degree of change since <strong>3.0.0</strong>.</li> | ||
| 279 : | <li>All version numbers are updated to have a ".qualifier" suffix (e.g., 3.0.1.qualifier).</li> | ||
| 280 : | <li>The line "qualifier = context" is added to all build.properties | ||
| 281 : | files</li> | ||
| 282 : | <li>PDE build is setup to add "31_" to the qualifier context for current builds<br> | ||
| 283 : | </li> | ||
| 284 : | </ol> | ||
| 285 : | jeff | 1.1 | </body> |
| 286 : | </html> |
| help@eclipse.org | ViewVC Help |
| Powered by ViewVC 1.0.3 |