platform-core-home/documents/plugin-versioning.html
Parent Directory
| 
Revision Log
Revision 1.4 - (view) (download) (as text)
| 1 : | jeff | 1.2 | <html> |
| 2 : | <head> | ||
| 3 : | <title>Using Plug-in Versions</title> | ||
| 4 : | <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> | ||
| 5 : | <link rel="stylesheet" href="http://eclipse.org/default_style.css" type="text/css"> | ||
| 6 : | jeff | 1.1 | </head> |
| 7 : | |||
| 8 : | <body bgcolor="#FFFFFF" text="#000000"> | ||
| 9 : | |||
| 10 : | <h1>Eclipse Plug-in Versioning Proposal</h1> | ||
| 11 : | <blockquote> | ||
| 12 : | <p><b>Summary</b> <br> | ||
| 13 : | jeff | 1.2 | The Eclipse team currently changes their plug-in version numbers to match each |
| 14 : | major release of Eclipse (e.g., 2.1, 3.0). This is a convenient | ||
| 15 : | way of understanding the origin of plug-ins but do not capture the actual | ||
| 16 : | semantics of the changes which occurred. For | ||
| 17 : | example, the change from 2.1 to 3.0 indicates a major and incompatible change. | ||
| 18 : | Of | ||
| 19 : | course, this | ||
| 20 : | is | ||
| 21 : | generally not what was intended as most 3.0 plug-ins are in fact compatible | ||
| 22 : | with their 2.1 versions. Here we outline the current use of version numbers | ||
| 23 : | and propose a new process for | ||
| 24 : | using | ||
| 25 : | plug-in | ||
| 26 : | version numbering to better indicate levels of compatibility.<br> | ||
| 27 : | jeff | 1.3 | Last Modified: |
| 28 : | jeff | 1.2 | 1200 February 17, 2004</p> |
| 29 : | jeff | 1.1 | </blockquote> |
| 30 : | |||
| 31 : | <h2>Problem Definition</h2> | ||
| 32 : | dj | 1.4 | <p>Current Eclipse practice calls for the teams to increment plug-in version numbers |
| 33 : | jeff | 1.1 | to match the upcoming release of Eclipse. For example, about 6 months ago we |
| 34 : | dj | 1.4 | changed our plug-in version numbers from 2.1 to 3.0.0. In June 2004 we will |
| 35 : | ship Eclipse 3.0.0 and all plug-ins (save a few third party ones) will be version | ||
| 36 : | 3.0.0. This is convenient because it allows people to look at the plug-in version | ||
| 37 : | number and immediatly understand what version of Eclipse that plug-in is from.</p> | ||
| 38 : | jeff | 1.1 | <p>This approach has several drawbacks however</p> |
| 39 : | <ul> | ||
| 40 : | <li>Incrementing the major (first) | ||
| 41 : | dj | 1.4 | version segment renders the plug-in "incompatible" with |
| 42 : | all previous versions of that plug-in. Dependent plug-ins which specify a version | ||
| 43 : | jeff | 1.1 | number (e.g., <import plugin="org.eclipse.foo" version="2.1.0"/>) |
| 44 : | dj | 1.4 | will not resolve against version 3.0.0 of the prerequisite plug-in. Unresolved |
| 45 : | plug-ins cannot participate in a running Eclipse environment. Even though | ||
| 46 : | we have worked hard to make the content of the 3.0 plug-ins binary backward | ||
| 47 : | jeff | 1.1 | compatible, |
| 48 : | dj | 1.4 | 2.1 based third party plug-ins (which specify prereq version numbers) require |
| 49 : | jeff | 1.1 | changes to work in 3.0.</li> |
| 50 : | <li>This approach does not set a good example. People building on top of | ||
| 51 : | Eclipse look to us to understand how they should structure their world. | ||
| 52 : | Following this | ||
| 53 : | dj | 1.4 | model, plug-ins like EMF and GEF should increment their version numbers |
| 54 : | jeff | 1.1 | to match the Eclipse version numbers regardless of whether they changed |
| 55 : | at all. This | ||
| 56 : | has the nasty side effect of rendering all of their users incompatible | ||
| 57 : | as well. It also does not scale well as a little change at the bottom then | ||
| 58 : | ripples all | ||
| 59 : | the way up.</li> | ||
| 60 : | <li> Eclipse is getting away with this because a) we are at the bottom of | ||
| 61 : | the stack, b) we ship a single wad that is built, packaged and distributed | ||
| 62 : | in unison | ||
| 63 : | and c) we do not use version numbered prerequisites ourselves. It is | ||
| 64 : | really this last point which hurts the most. By not using versioned prereqs, | ||
| 65 : | we | ||
| 66 : | are not eating our own dog food. Clearly we do not mean that the resources | ||
| 67 : | dj | 1.4 | plug-in |
| 68 : | jeff | 1.1 | from 3.0 will run on ANY version of the Eclipse runtime. People who build |
| 69 : | dj | 1.4 | and distribute plug-ins are not generally able to play it quite so fast |
| 70 : | jeff | 1.1 | and loose.</li> |
| 71 : | <li> Features are not the cure. To address some of this, we use features and | ||
| 72 : | dj | 1.4 | their abilily to group plug-ins. The assumption is that if the feature |
| 73 : | constraints are met, then the underlying plug-ins will all be happy and thus | ||
| 74 : | jeff | 1.1 | versioned |
| 75 : | dj | 1.4 | plug-in dependencies are not needed. This works but assumes that the feature |
| 76 : | jeff | 1.1 | writer |
| 77 : | dj | 1.4 | (may not be related to the plug-in authors) can understand the plug-in |
| 78 : | jeff | 1.1 | constraints well enough to define the feature. In practice this means that |
| 79 : | dj | 1.4 | the plug-ins |
| 80 : | jeff | 1.1 | in the feature all have similar constraints such that they can be distilled |
| 81 : | to a smaller set of inter feature constraints. Features are a packaging | ||
| 82 : | dj | 1.4 | mechanism for plug-ins. Pushing constraint satisfaction up to the packaging |
| 83 : | jeff | 1.1 | layer puts |
| 84 : | a significant load both on the people creating the packages (e.g., features) | ||
| 85 : | as well as the packaging (e.g., feature) mechanism.</li> | ||
| 86 : | </ul> | ||
| 87 : | <h2>Proposal</h2> | ||
| 88 : | <p> To address these concerns, we propose that the Eclipse SDK team start using | ||
| 89 : | dj | 1.4 | the version number semantics defined by Eclipse for all their plug-ins. The |
| 90 : | numbering process works as follows:- new plug-ins start as 0.0.0 and go through | ||
| 91 : | jeff | 1.1 | various version numbers (<1.0.0) |
| 92 : | until they are ready for their first release. At that time, developers may | ||
| 93 : | choose to set the version number to 1.0.0. This is mostly cosmetic and is not | ||
| 94 : | required. Prior to first release the numbering process depends mostly on how | ||
| 95 : | widely availability and use of the early versions. For example, a beta at 0.9 | ||
| 96 : | sets a good tone and might encourage release at 1.0.0. </p> | ||
| 97 : | <ul> | ||
| 98 : | dj | 1.4 | <li> Immediately after a release, plug-ins continue with the same number as |
| 99 : | jeff | 1.1 | they had in the release (e.g., 1.0.0). </li> |
| 100 : | dj | 1.4 | <li> As the plug-in is developed for the next release, the version number is |
| 101 : | jeff | 1.1 | changed to accurately reflect those changes. For example, if some minor fixes |
| 102 : | are done, | ||
| 103 : | the service (third) segment should be incremented (e.g., 1.0.1). If significant | ||
| 104 : | but compatible rework is done and/or new function added, the minor (second) | ||
| 105 : | segment should be incremented. (e.g., 1.1.0). Note that in this example, | ||
| 106 : | the significant work overshadows the service fixes so the service (third) | ||
| 107 : | segment | ||
| 108 : | is set to 0. If major rework is done such that the new version is incompatible | ||
| 109 : | with previous versions then the major (first) segment should be incremented | ||
| 110 : | (e.g., 2.0.0) Note that the minor and service numbers are 0 here as well.</li> | ||
| 111 : | dj | 1.4 | <li> A plug-in's version number need only be incremented to distinguish one |
| 112 : | release from another. For example, if we release 1.0.0 of a plug-in and then | ||
| 113 : | jeff | 1.1 | do some |
| 114 : | bug fixes for a milestone (say M3), we increment the version to 1.0.1. | ||
| 115 : | dj | 1.4 | If that plug-in were eventually released, people could look at the version |
| 116 : | jeff | 1.1 | number and |
| 117 : | see that a) it is different from 1.0.0 and b) that some bug fixes were | ||
| 118 : | done. If instead, further bug fixes are done for M5, there is no need to | ||
| 119 : | further | ||
| 120 : | jeff | 1.2 | increment in the version number (i.e., to 1.0.2). Leaving the version at |
| 121 : | 1.0.1 still conveys the important information to users of the | ||
| 122 : | next | ||
| 123 : | release. | ||
| 124 : | Of course, teams could increment the version further if needed/desired. | ||
| 125 : | Either way, the qualifier (fourth) version segment can be | ||
| 126 : | used (e.g., 1.0.1.M3 | ||
| 127 : | jeff | 1.1 | vs 1.0.1.M5) |
| 128 : | jeff | 1.2 | to differentiate between builds of the same version.</li> |
| 129 : | dj | 1.4 | <li> Plug-in version number changes are solely at the discretion of the plug-in |
| 130 : | jeff | 1.1 | development team. They are in the best position to understand their changes |
| 131 : | and the scope of impact.</li> | ||
| 132 : | dj | 1.4 | <li> Features are used to group together plug-ins and label them with a particular "product" release |
| 133 : | jeff | 1.1 | version (e.g., 3.0). The org.eclipse.platform 3.0.0 feature contains a complete |
| 134 : | dj | 1.4 | and precise specification of the plug-ins in the 3.0 platform.</li> |
| 135 : | jeff | 1.1 | </ul> |
| 136 : | <h2>Action</h2> | ||
| 137 : | <p>The only action required is to decide we want to do this and refine/document | ||
| 138 : | the details of the structure and process. There are no technological hurdles. | ||
| 139 : | Just as teams are responsible updating their copyright dates, they would be | ||
| 140 : | dj | 1.4 | responsible for incrementing their plug-in versions. These changes are done |
| 141 : | jeff | 1.1 | very infrequently so will not be a particular burden.</p> |
| 142 : | dj | 1.4 | <p>If we decide to follow this new policy we can retrofit the 3.0 plug-ins with "correct" version |
| 143 : | jeff | 1.1 | numbers or start the new approach immediately following the release of Eclipes |
| 144 : | dj | 1.4 | 3.0. Starting now avoids situations where Eclipse 2.1 based plug-ins do not |
| 145 : | jeff | 1.1 | work on the released 3.0 because of resolution problems (rather than because |
| 146 : | of actual incompatibilities). However, it may adversely affect people in the | ||
| 147 : | community who have already come to know, like and use the 3.0.0 version numbers.<br> | ||
| 148 : | </p> | ||
| 149 : | </body> | ||
| 150 : | </html> |
| help@eclipse.org | ViewVC Help |
| Powered by ViewVC 1.0.3 |