platform-core-home/documents/plugin-versioning.html

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.3, Tue Feb 17 16:55:22 2004 UTC revision 1.4, Wed Feb 18 18:30:02 2004 UTC
# Line 29  Line 29 
29  </blockquote>  </blockquote>
30    
31  <h2>Problem Definition</h2>  <h2>Problem Definition</h2>
32  <p>Current Eclipse practice calls for the teams to increment plugin version numbers  <p>Current Eclipse practice calls for the teams to increment plug-in version numbers
33    to match the upcoming release of Eclipse. For example, about 6 months ago we    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    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 plugins (save a few third party ones) will be version    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 plugin version    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 plugin is from.</p>  number and immediatly understand what version of Eclipse that plug-in is from.</p>
38  <p>This approach has several drawbacks however</p>  <p>This approach has several drawbacks however</p>
39  <ul>  <ul>
40    <li>Incrementing the major (first)    <li>Incrementing the major (first)
41        version segment renders the plugin &quot;incompatible&quot; with        version segment renders the plug-in &quot;incompatible&quot; with
42        all previous versions of that plugin. Dependent plugins which specify a version        all previous versions of that plug-in. Dependent plug-ins which specify a version
43        number (e.g., &lt;import plugin=&quot;org.eclipse.foo&quot; version=&quot;2.1.0&quot;/&gt;)        number (e.g., &lt;import plugin=&quot;org.eclipse.foo&quot; version=&quot;2.1.0&quot;/&gt;)
44        will not resolve against version 3.0.0 of the prerequisite plugin. Unresolved        will not resolve against version 3.0.0 of the prerequisite plug-in. Unresolved
45        plugins cannot participate in a running Eclipse environment. Even though        plug-ins 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        we have worked hard to make the content of the 3.0 plug-ins binary backward
47        compatible,        compatible,
48        2.1 based third party plugins (which specify prereq version numbers) require        2.1 based third party plug-ins (which specify prereq version numbers) require
49      changes to work in 3.0.</li>      changes to work in 3.0.</li>
50    <li>This approach does not set a good example. People building on top of    <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.        Eclipse look to us to understand how they should structure their world.
52      Following this      Following this
53          model, plugins like EMF and GEF should increment their version numbers          model, plug-ins like EMF and GEF should increment their version numbers
54        to match the Eclipse version numbers regardless of whether they changed        to match the Eclipse version numbers regardless of whether they changed
55      at all. This      at all. This
56          has the nasty side effect of rendering all of their users incompatible          has the nasty side effect of rendering all of their users incompatible
# Line 64  Line 64 
64      really this last point which hurts the most. By not using versioned prereqs,      really this last point which hurts the most. By not using versioned prereqs,
65      we      we
66        are not eating our own dog food. Clearly we do not mean that the resources        are not eating our own dog food. Clearly we do not mean that the resources
67        plugin        plug-in
68          from 3.0 will run on ANY version of the Eclipse runtime. People who build          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        and distribute plug-ins are not generally able to play it quite so fast
70      and loose.</li>      and loose.</li>
71    <li> Features are not the cure. To address some of this, we use features and    <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          their abilily to group plug-ins. The assumption is that if the feature
73      constraints are met, then the underlying plugins will all be happy and thus      constraints are met, then the underlying plug-ins will all be happy and thus
74      versioned      versioned
75        plugin dependencies are not needed. This works but assumes that the feature        plug-in dependencies are not needed. This works but assumes that the feature
76        writer        writer
77          (may not be related to the plugin authors) can understand the plugin          (may not be related to the plug-in authors) can understand the plug-in
78      constraints well enough to define the feature. In practice this means that      constraints well enough to define the feature. In practice this means that
79      the plugins      the plug-ins
80          in the feature all have similar constraints such that they can be distilled          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          to a smaller set of inter feature constraints. Features are a packaging
82        mechanism for plugins. Pushing constraint satisfaction up to the packaging        mechanism for plug-ins. Pushing constraint satisfaction up to the packaging
83        layer puts        layer puts
84          a significant load both on the people creating the packages (e.g., features)          a significant load both on the people creating the packages (e.g., features)
85        as well as the packaging (e.g., feature) mechanism.</li>        as well as the packaging (e.g., feature) mechanism.</li>
86  </ul>  </ul>
87  <h2>Proposal</h2>  <h2>Proposal</h2>
88  <p>  To address these concerns, we propose that the Eclipse SDK team start using  <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      the version number semantics defined by Eclipse for all their plug-ins. The
90      numbering process works as follows:- new plugins start as 0.0.0 and go through      numbering process works as follows:- new plug-ins start as 0.0.0 and go through
91      various version numbers (&lt;1.0.0)      various version numbers (&lt;1.0.0)
92    until they are ready for their first release. At that time, developers may    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    choose to set the version number to 1.0.0. This is mostly cosmetic and is not
# Line 95  Line 95 
95    widely availability and use of the early versions. For example, a beta at 0.9    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>    sets a good tone and might encourage release at 1.0.0. </p>
97  <ul>  <ul>
98    <li> Immediately after a release, plugins continue with the same number as    <li> Immediately after a release, plug-ins continue with the same number as
99      they had in the release (e.g., 1.0.0). </li>      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    <li> As the plug-in is developed for the next release, the version number is
101      changed to accurately reflect those changes. For example, if some minor fixes      changed to accurately reflect those changes. For example, if some minor fixes
102      are done,      are done,
103        the service (third) segment should be incremented (e.g., 1.0.1). If significant        the service (third) segment should be incremented (e.g., 1.0.1). If significant
# Line 108  Line 108 
108        is set to 0. If major rework is done such that the new version is incompatible        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        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>        (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    <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 plugin and then      release from another. For example, if we release 1.0.0 of a plug-in and then
113      do some      do some
114        bug fixes for a milestone (say M3), we increment the version to 1.0.1.        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      If that plug-in were eventually released, people could look at the version
116      number and      number and
117        see that a) it is different from 1.0.0 and b) that some bug fixes were        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      done. If instead, further bug fixes are done for M5, there is no need to
# Line 126  Line 126 
126      used (e.g., 1.0.1.M3      used (e.g., 1.0.1.M3
127      vs 1.0.1.M5)      vs 1.0.1.M5)
128        to differentiate between builds of the same version.</li>        to differentiate between builds of the same version.</li>
129    <li> Plugin version number changes are solely at the discretion of the plugin    <li> Plug-in version number changes are solely at the discretion of the plug-in
130        development team. They are in the best position to understand their changes        development team. They are in the best position to understand their changes
131        and the scope of impact.</li>        and the scope of impact.</li>
132    <li> Features are used to group together plugins and label them with a particular &quot;product&quot; release    <li> Features are used to group together plug-ins and label them with a particular &quot;product&quot; release
133      version (e.g., 3.0). The org.eclipse.platform 3.0.0 feature contains a complete      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>      and precise specification of the plug-ins in the 3.0 platform.</li>
135  </ul>  </ul>
136  <h2>Action</h2>  <h2>Action</h2>
137  <p>The only action required is to decide we want to do this and refine/document  <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.    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    Just as teams are responsible updating their copyright dates, they would be
140    responsible for incrementing their plugin versions. These changes are done    responsible for incrementing their plug-in versions. These changes are done
141    very infrequently so will not be a particular burden.</p>    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 &quot;correct&quot; version  <p>If we decide to follow this new policy we can retrofit the 3.0 plug-ins with &quot;correct&quot; version
143    numbers or start the new approach immediately following the release of Eclipes    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    3.0. Starting now avoids situations where Eclipse 2.1 based plug-ins do not
145    work on the released 3.0 because of resolution problems (rather than because    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    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>    community who have already come to know, like and use the 3.0.0 version numbers.<br>
Legend:
Removed from v.1.3  
changed lines
  Added in v.1.4