platform-core-home/documents/plugin-versioning.html
Parent Directory
| 
Revision Log
Revision 1.3 - (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 : | <p>Current Eclipse practice calls for the teams to increment plugin version numbers | ||
| 33 : | to match the upcoming release of Eclipse. For example, about 6 months ago we | ||
| 34 : | changed our plugin version numbers from 2.1 to 3.0.0. In June 2004 we will | ||
| 35 : | ship Eclipse 3.0.0 and all plugins (save a few third party ones) will be version | ||
| 36 : | 3.0.0. This is convenient because it allows people to look at the plugin version | ||
| 37 : | number and immediatly understand what version of Eclipse that plugin is from.</p> | ||
| 38 : | <p>This approach has several drawbacks however</p> | ||
| 39 : | <ul> | ||
| 40 : | <li>Incrementing the major (first) | ||
| 41 : | version segment renders the plugin "incompatible" with | ||
| 42 : | all previous versions of that plugin. Dependent plugins which specify a version | ||
| 43 : | number (e.g., <import plugin="org.eclipse.foo" version="2.1.0"/>) | ||
| 44 : | will not resolve against version 3.0.0 of the prerequisite plugin. Unresolved | ||
| 45 : | plugins cannot participate in a running Eclipse environment. Even though | ||
| 46 : | we have worked hard to make the content of the 3.0 plugins binary backward | ||
| 47 : | compatible, | ||
| 48 : | 2.1 based third party plugins (which specify prereq version numbers) require | ||
| 49 : | 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 : | model, plugins like EMF and GEF should increment their version numbers | ||
| 54 : | 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 : | plugin | ||
| 68 : | from 3.0 will run on ANY version of the Eclipse runtime. People who build | ||
| 69 : | and distribute plugins are not generally able to play it quite so fast | ||
| 70 : | and loose.</li> | ||
| 71 : | <li> Features are not the cure. To address some of this, we use features and | ||
| 72 : | their abilily to group plugins. The assumption is that if the feature | ||
| 73 : | constraints are met, then the underlying plugins will all be happy and thus | ||
| 74 : | versioned | ||
| 75 : | plugin dependencies are not needed. This works but assumes that the feature | ||
| 76 : | writer | ||
| 77 : | (may not be related to the plugin authors) can understand the plugin | ||
| 78 : | constraints well enough to define the feature. In practice this means that | ||
| 79 : | the plugins | ||
| 80 : | 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 : | mechanism for plugins. Pushing constraint satisfaction up to the packaging | ||
| 83 : | 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 : | the version number semantics defined by Eclipse for all their plugins. The | ||
| 90 : | numbering process works as follows:- new plugins start as 0.0.0 and go through | ||
| 91 : | 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 : | <li> Immediately after a release, plugins continue with the same number as | ||
| 99 : | they had in the release (e.g., 1.0.0). </li> | ||
| 100 : | <li> As the plugin is developed for the next release, the version number is | ||
| 101 : | 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 : | <li> A plugin's version number need only be incremented to distinguish one | ||
| 112 : | release from another. For example, if we release 1.0.0 of a plugin and then | ||
| 113 : | do some | ||
| 114 : | bug fixes for a milestone (say M3), we increment the version to 1.0.1. | ||
| 115 : | If that plugin were eventually released, people could look at the version | ||
| 116 : | 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 : | jeff | 1.1 | <li> Plugin version number changes are solely at the discretion of the plugin |
| 130 : | development team. They are in the best position to understand their changes | ||
| 131 : | and the scope of impact.</li> | ||
| 132 : | <li> Features are used to group together plugins and label them with a particular "product" release | ||
| 133 : | version (e.g., 3.0). The org.eclipse.platform 3.0.0 feature contains a complete | ||
| 134 : | and precise specification of the plugins in the 3.0 platform.</li> | ||
| 135 : | </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 : | responsible for incrementing their plugin versions. These changes are done | ||
| 141 : | very infrequently so will not be a particular burden.</p> | ||
| 142 : | <p>If we decide to follow this new policy we can retrofit the 3.0 plugins with "correct" version | ||
| 143 : | numbers or start the new approach immediately following the release of Eclipes | ||
| 144 : | 3.0. Starting now avoids situations where Eclipse 2.1 based plugins do not | ||
| 145 : | 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 |