platform-update-home/doc/new_in_2.0.2.html
Parent Directory
| 
Revision Log
Revision 1.3 - (view) (download) (as text)
| 1 : | dejan | 1.1 | |
| 2 : | <h1>Additions and changes in Eclipse Update release 2.0.2</h1> | ||
| 3 : | <h2>Introduction</h2> | ||
| 4 : | <p>Although Eclipse release 2.0.2 was mostly a bug-fixing release and didn't | ||
| 5 : | include new features elsewhere, Update team used it to deliver significant | ||
| 6 : | changes. These changes are backward compatible and feature written against the | ||
| 7 : | 2.0.0 specification still work. The changes were added to provide for more | ||
| 8 : | robust, flexible and manageable installs and updates of large and complex | ||
| 9 : | dejan | 1.2 | Eclipse products. You can read the <a href="eclipse_update_packaging.html">updated |
| 10 : | dejan | 1.1 | specifications</a> for more details. </p> |
| 11 : | <h2>Partial (branch) updates</h2> | ||
| 12 : | <p>In Eclipse 2.0.0, features were allowed to be organized in hierarchies using | ||
| 13 : | the inclusion capability (element <samp>includes</samp> in feature manifest). | ||
| 14 : | The inclusion was exact - included feature was specified using the exact | ||
| 15 : | identifier and version. The consequence of this limitation was that the only way | ||
| 16 : | to update a branch of a hierarchy was to update the root feature. </p> | ||
| 17 : | dejan | 1.3 | <p>In large, complex Eclipse products it is not always possible to provide update |
| 18 : | dejan | 1.1 | of the root feature every time there is a change somewhere in the hierarchy. For |
| 19 : | example, nodes in the tree may be Eclipse products themselves. It was needed to | ||
| 20 : | allow branches to be updated independent of the root.</p> | ||
| 21 : | <p>However, teams that own feature roots may still want to control where | ||
| 22 : | features go for updates. A feature in the hierarchy may be on a different | ||
| 23 : | schedule and may have updates available that are not yet tested with the root | ||
| 24 : | feature. For this reason, in 2.0.2 branches can be updated but must go to the | ||
| 25 : | update site of the root feature to look for updates. This way, root feature can | ||
| 26 : | control what updates are found and can publish only tested and verified | ||
| 27 : | (supported) updated of the branches.</p> | ||
| 28 : | <p>When a branch feature is updated, its version changes. This automatically | ||
| 29 : | breaks 'includes' specification unless it is somehow capable of handling this | ||
| 30 : | change. Additional attribute <samp>match</samp> was added to formally express | ||
| 31 : | this capability:</p> | ||
| 32 : | <blockquote> | ||
| 33 : | <pre><includes id="com.example.acme" version ="4.0.0" <b>match="equivalent"</b>/></pre> | ||
| 34 : | </blockquote> | ||
| 35 : | <p>In the example above, feature hierarchy will not be broken if | ||
| 36 : | com.example.acme is updated to 4.0.1, 4.0.2 and so on. However, the update | ||
| 37 : | potential is limited by the value of the <samp>match</samp> attribute. Value <samp>equivalent</samp> | ||
| 38 : | allows only service number increments. In contrast, <samp>compatible</samp> | ||
| 39 : | would allow both service and minor increments.</p> | ||
| 40 : | <p>The suggested use of this attribute is to allow only service updates. | ||
| 41 : | Anything more would be a significant change and we suggest a full root update | ||
| 42 : | instead (a service pack). Branch updates should be used as a short-term measure | ||
| 43 : | (for patches and other minor updates).</p> | ||
| 44 : | <p>By default, included feature will look for updates in the update site defined | ||
| 45 : | by the root. This can be changed by defining <samp>search_location</samp> | ||
| 46 : | attribute and setting it to <samp>self</samp>:</p> | ||
| 47 : | <blockquote> | ||
| 48 : | <pre><includes id="com.example.acme" version="4.0.0" match="equivalent" search_location="self"/></pre> | ||
| 49 : | </blockquote> | ||
| 50 : | <p>Default value of this attribute (when not specified) is <samp>root</samp>. | ||
| 51 : | When set to <samp>self</samp>, updates will be searched for in the update site | ||
| 52 : | defined by the feature itself, instead of that of a root feature.</p> | ||
| 53 : | <p><i>NOTE: match attribute is only considered when feature is part of the local | ||
| 54 : | configuration. It is ignored when on the remote server. In the example above, | ||
| 55 : | feature "com.example.acme" version "4.0.0" must be present | ||
| 56 : | on the server. It is only when it is downloaded into the Eclipse product that | ||
| 57 : | match attribute takes effect in reference resolution.</i></p> | ||
| 58 : | <h2>Optional features</h2> | ||
| 59 : | <p>All of the features included by the root one must be present within the same | ||
| 60 : | site in order to be resolved. The exception are <b>optional features</b>. | ||
| 61 : | Optional features are included features that users can opt not to install. | ||
| 62 : | Optional features are declared using the attribute <samp>optional</samp>:</p> | ||
| 63 : | <blockquote> | ||
| 64 : | <pre><includes id="com.example.acme" version="4.0.0" match="equivalent" <b>optional="true"</b>/></pre> | ||
| 65 : | </blockquote> | ||
| 66 : | <p>Optional features have the following properties:</p> | ||
| 67 : | <ul> | ||
| 68 : | <li>It is not an error if an optional feature is missing on the remote server</li> | ||
| 69 : | <li>It is not an error if an optional feature is missing in the configuration | ||
| 70 : | (it just shows as 'not installed')</li> | ||
| 71 : | <li>Users are presented with the wizard page where they can select optional | ||
| 72 : | features for install using checkboxes</li> | ||
| 73 : | <li>Only optional features that are currently installed are updated to a newer | ||
| 74 : | version during root updates</li> | ||
| 75 : | <li>When features are installed from a remote server using Update Manager, the | ||
| 76 : | URL is remembered. Optional features can be subsequently installed by | ||
| 77 : | pressing 'Install' button (Update Manager will reconnect using the stored | ||
| 78 : | URL and install it).</li> | ||
| 79 : | <li>Unlike the regular ones, optional features can be disabled when part of | ||
| 80 : | the feature hierarchy</li> | ||
| 81 : | <li>Once disabled, optional features can be re-enabled providing that their | ||
| 82 : | parent is already enabled</li> | ||
| 83 : | </ul> | ||
| 84 : | <p>When not installed, optional features are hidden using the same filter as | ||
| 85 : | disabled features and can be seen by turning the filter off (the local tool bar | ||
| 86 : | button on the Configurations view in the Update Manager).</p> | ||
| 87 : | <h2>Feature requires</h2> | ||
| 88 : | <p>In 2.0.0, install/update prerequisites for features were plug-ins only:</p> | ||
| 89 : | <blockquote> | ||
| 90 : | <pre><requires> | ||
| 91 : | <import plugin="org.eclipse.jdt" version="2.0.0" match="compatible"/> | ||
| 92 : | </requires></pre> | ||
| 93 : | </blockquote> | ||
| 94 : | <p>Since 2.0.2, feature may require other features as a precondition for | ||
| 95 : | installation:</p> | ||
| 96 : | <blockquote> | ||
| 97 : | <pre><requires> | ||
| 98 : | dejan | 1.3 | <import feature="org.eclipse.jdt" version="2.0.0" match="compatible"/> |
| 99 : | dejan | 1.1 | </requires></pre> |
| 100 : | </blockquote> | ||
| 101 : | <p>The rest of the semantics didn't change. Prior to the installation, Update | ||
| 102 : | will check all the constraints in 'requires' and block the operation if any of | ||
| 103 : | dejan | 1.3 | them is not satisfied.</p> |
| 104 : | dejan | 1.1 | <h2>Patches</h2> |
| 105 : | <p>Update version 2.0.2 introduces a notion of <b>patches</b>. Patches are | ||
| 106 : | regular features that are configured to bring partial updates to complex feature | ||
| 107 : | tree hierarchies. Prior to 2.0.2, the only way to update a branch of a feature | ||
| 108 : | tree was to update the entire hierarchy, including the root. Patches serve as | ||
| 109 : | carriers that bring in partial updates to other features without updating their | ||
| 110 : | roots.</p> | ||
| 111 : | <p>Each patch consists of at least two features: the carrier (root) and the | ||
| 112 : | update (the actual feature that has been modified). The role of the carrier is | ||
| 113 : | to represent the patch entity in the configuration and to establish the | ||
| 114 : | relationship with the hierarchy that is being patched. A patch can me more | ||
| 115 : | complex and include several features, or entire branches.</p> | ||
| 116 : | <h3>Definition</h3> | ||
| 117 : | <p>For a regular feature to be a patch, two changes have to be made:</p> | ||
| 118 : | <blockquote> | ||
| 119 : | <pre><feature id="org.eclipse.sdk.win32.e334" | ||
| 120 : | version="2.0.2" | ||
| 121 : | name="Patch e334" | ||
| 122 : | <b>colocation-affinity="org.eclipse.sdk.win32"</b>> | ||
| 123 : | ..... | ||
| 124 : | <requires> | ||
| 125 : | <import feature="org.eclipse.sdk.win32" version="2.0.2" <b>patch="true"</b>/> | ||
| 126 : | </requires> | ||
| 127 : | <includes id="org.eclipse.pde" version="2.0.2.e334" match="equivalent"/> | ||
| 128 : | </feature></pre> | ||
| 129 : | </blockquote> | ||
| 130 : | <p>The feature above will be a patch number e334. Its identifier is composed | ||
| 131 : | that way, although this is not a requirement. Similarly, patch version is not | ||
| 132 : | important but is convenient to use the same version as the feature that it | ||
| 133 : | should patch. The important part is <samp>colocation-affinity</samp> attribute. | ||
| 134 : | We used it to indicate that we want the patch installed in the same location as | ||
| 135 : | the feature it patches (note that <samp>colocation-affinity</samp> is not new - | ||
| 136 : | it is part of the 2.0.0 specification).</p> | ||
| 137 : | <p>The second important change is the dependency on the patched feature. We used | ||
| 138 : | attribute 'patch=true' to indicate that this feature is a patch for the | ||
| 139 : | dependent feature. This will cause the following consequences:</p> | ||
| 140 : | <ul> | ||
| 141 : | <li>When a patch is about to be installed, it will check the presence of the | ||
| 142 : | patched feature and will not install without it</li> | ||
| 143 : | <li>The dependency on the patched feature is 'exact' i.e. patches are always | ||
| 144 : | made for the exact versions</li> | ||
| 145 : | <li>When a patch is installed, it will seek out versions of the features that | ||
| 146 : | are older than the ones it includes, and will disable them</li> | ||
| 147 : | <li>Patch installation will fail if features that are supposed to be patched | ||
| 148 : | are newer than the ones included by the patch itself (this way, we prevent | ||
| 149 : | patches to introduce back-level code)</li> | ||
| 150 : | </ul> | ||
| 151 : | <p><b>A very important precondition for patches is that the feature hierarchy of | ||
| 152 : | a patched product is capable of accepting them.</b> In other words, all child | ||
| 153 : | features in the product must be included using the 'match' attribute other than | ||
| 154 : | 'perfect'. Partial (branch) updates must be possible for patches to be used.</p> | ||
| 155 : | <h3>Grouping</h3> | ||
| 156 : | <p>Patches can include any number of features that patch any point of the | ||
| 157 : | patched feature's tree. In addition:</p> | ||
| 158 : | <ul> | ||
| 159 : | <li>Patches can include other patches. A patch of one product can include a | ||
| 160 : | patch of another product elsewhere in the hierarchy.</li> | ||
| 161 : | <li>Patches may prerequisite other patches. This is similar to including but | ||
| 162 : | should be used when the required patch is not controlled by the same team | ||
| 163 : | (must be installed from another team's server). If your team owns both | ||
| 164 : | patches or can provide them both on the patch server, use inclusion instead.</li> | ||
| 165 : | <li>Patches may be grouped. A number of small patches can be grouped into an aggregate | ||
| 166 : | patch for easy installation.</li> | ||
| 167 : | </ul> | ||
| 168 : | <p>Patches can also be cumulative. In other words, a patch may bring an upgrade | ||
| 169 : | to a feature already patched by a previous patch. Since two patches include the | ||
| 170 : | same feature (just different versions), it is important that patches include | ||
| 171 : | their features with a <samp>match</samp> set to a value that is not <samp>perfect</samp> | ||
| 172 : | (typically <samp>equivalent</samp>). In the example above, patch e334 includes | ||
| 173 : | patched version of the PDE feature. If a newer patch (e.g. e444) also fixes PDE | ||
| 174 : | and includes version 2.0.2.e444 of it, the previously installed patch e334 will | ||
| 175 : | not be broken upon installation of e444. When expanded in the Configuration | ||
| 176 : | view, both patches will resolve to PDE version 2.0.2.e444. This is consistent | ||
| 177 : | because 2.0.2.e444 subsumes 2.0.2.e334. It is a good practice to document that | ||
| 178 : | fact in the description of the patch (something like 'this patch also includes a | ||
| 179 : | fix for problem fixed by e334').</p> | ||
| 180 : | <h3>Reverting a patch install</h3> | ||
| 181 : | <p>When a patch is installed, current configuration is saved as a backup and | ||
| 182 : | placed in the 'Saved Configurations'. This configuration has the following name | ||
| 183 : | convention:</p> | ||
| 184 : | <blockquote> | ||
| 185 : | <pre>@<id>_<version> backup</pre> | ||
| 186 : | </blockquote> | ||
| 187 : | <p>For example: </p> | ||
| 188 : | <blockquote> | ||
| 189 : | <pre>@org.eclipse.sdk.win32.e334_2.0.2 backup</pre> | ||
| 190 : | </blockquote> | ||
| 191 : | <p>The naming convention is selected so that Update can programmatically locate | ||
| 192 : | this configuration for cleanup. If a patch installation didn't produce a desired | ||
| 193 : | result (the fix does not solve the problem or introduces side-effects), users | ||
| 194 : | can back out of the installation by restoring this configuration. Patch install | ||
| 195 : | is a complex operation and for that reason a revert must be used for this | ||
| 196 : | (simply disabling a patch would leave the configuration in a wrong state and is | ||
| 197 : | prevented for that reason).</p> | ||
| 198 : | <h3>Cleanup</h3> | ||
| 199 : | <p>Patches have limited life span. Since they are registered for a specific | ||
| 200 : | feature ID and version, they become obsolete the moment the referenced feature | ||
| 201 : | is upgraded to a new version. When a feature is disabled, all referencing | ||
| 202 : | patches are disabled with it. In addition, all backup configurations for these | ||
| 203 : | patches are removed.</p> | ||
| 204 : | <p>It is important to understand the role patches are supposed to play in | ||
| 205 : | feature updates. Patches should be used for emergency fixes (e-fixes) between | ||
| 206 : | two official fix packs. Official fix pack is a full revision of a feature that | ||
| 207 : | starts from the root (e.g. 2.0.1, 2.0.2, 2.0.3 etc.). Between two fix packs, | ||
| 208 : | emergency fixes are used to provide a quick solution for a problem until the fix | ||
| 209 : | pack becomes available. The implicit contract for patches is that the next | ||
| 210 : | regular fix pack subsumes all the fixes provided between it and the previous fix | ||
| 211 : | pack.</p> | ||
| 212 : | <h2>Update activity log</h2> | ||
| 213 : | <p>Since 2.0.2, Update is now writing an ever-growing file called <b>.install-log | ||
| 214 : | </b>in the ./metadata/.config directory of the active workspace. This file | ||
| 215 : | records all install activities as they are performed in the platform and is not | ||
| 216 : | subject to configuration history limit set in the Update preferences.</p> | ||
| 217 : | <h2>Configuration history timelines</h2> | ||
| 218 : | <p>Eclipse Update is designed to cope with changes on the file system and try to | ||
| 219 : | reconcile these changes with its internal state. When these changes are | ||
| 220 : | considered controlled (e.g. when a new feature is added by a native installer), | ||
| 221 : | it reconciles the change within the same <b>timeline</b>. A <b>timeline</b> is a | ||
| 222 : | sequence of installation events that are considered mutually compatible. Stable | ||
| 223 : | states in the timeline (shown as configurations in the history) can be subject | ||
| 224 : | to the 'revert' operation (i.e. it is allowed to revert to any configuration | ||
| 225 : | within the same timeline).</p> | ||
| 226 : | <p>Sometimes, the change made to the file system is considered so radical | ||
| 227 : | (location has changed, critical platform files have changed etc.) that Update | ||
| 228 : | throws the towel and initiates full reconciliation. Full reconciliation discards | ||
| 229 : | previous state and re-computes it from the ground up, enabling all the features | ||
| 230 : | in the process. Full reconciliation starts a new timeline. Once that happens, it | ||
| 231 : | is not possible to go back to a previous timeline using the 'revert' command. | ||
| 232 : | Configuration elements that belong to a different timeline are clearly marked in | ||
| 233 : | the configuration history with an icon overlay.</p> | ||
| 234 : | <h2>Other changes</h2> | ||
| 235 : | <ul> | ||
| 236 : | <li>Plug-in search results are now presented in a Search Result view that | ||
| 237 : | shows up below the Details view.</li> | ||
| 238 : | <li>A number of defects have been fixed (see 2.0.2 release notes for details)</li> | ||
| 239 : | <li>Discovery sites from features that are not root are now not shown in the | ||
| 240 : | 'Sites to Visit' folder</li> | ||
| 241 : | <li>Installations that will cause duplicate features in multiple linked | ||
| 242 : | extensions to be in conflict (different versions) are flagged with a | ||
| 243 : | detailed warning dialog, allowing users to cancel the install</li> | ||
| 244 : | <li>Quick search for updates (Help->Software Updates->New Updates) is | ||
| 245 : | modified to find new versions of branches that are capable of updating | ||
| 246 : | (match!=perfect). Filter in the quick search wizard can compute the highest | ||
| 247 : | feature in the hierarchy that includes all other search results and hide the | ||
| 248 : | rest</li> | ||
| 249 : | </ul> | ||
| 250 : | <p> </p> | ||
| 251 : | <p> </p> | ||
| 252 : | <p> </p> |
| help@eclipse.org | ViewVC Help |
| Powered by ViewVC 1.0.3 |