<h1>Additions and changes in Eclipse Update release 2.0.2</h1>
<h2>Introduction</h2>
<p>Although Eclipse release 2.0.2 was mostly a bug-fixing release and didn't
include new features elsewhere, Update team used it to deliver significant
changes. These changes are backward compatible and feature written against the
2.0.0 specification still work. The changes were added to provide for more
robust, flexible and manageable installs and updates of large and complex
Eclipse products. You can read the <a href="eclipse_update_packaging.html">updated
specifications</a> for more details.&nbsp;</p>
<h2>Partial (branch) updates</h2>
<p>In Eclipse 2.0.0, features were allowed to be organized in hierarchies using
the inclusion capability (element <samp>includes</samp> in feature manifest).
The inclusion was exact - included feature was specified using the exact
identifier and version. The consequence of this limitation was that the only way
to update a branch of a hierarchy was to update the root feature.&nbsp;</p>
<p>In large, complex Eclipse products it is not always possible to provide update
of the root feature every time there is a change somewhere in the hierarchy. For
example, nodes in the tree may be Eclipse products themselves. It was needed to
allow branches to be updated independent of the root.</p>
<p>However, teams that own feature roots may still want to control where
features go for updates. A feature in the hierarchy may be on a different
schedule and may have updates available that are not yet tested with the root
feature. For this reason, in 2.0.2 branches can be updated but must go to the
update site of the root feature to look for updates. This way, root feature can
control what updates are found and can publish only tested and verified
(supported) updated of the branches.</p>
<p>When a branch feature is updated, its version changes. This automatically
breaks 'includes' specification unless it is somehow capable of handling this
change. Additional attribute <samp>match</samp> was added to formally express
this capability:</p>
<blockquote>
  <pre>&lt;includes id=&quot;com.example.acme&quot; version =&quot;4.0.0&quot; <b>match=&quot;equivalent&quot;</b>/&gt;</pre>
</blockquote>
<p>In the example above, feature hierarchy will not be broken if
com.example.acme is updated to 4.0.1, 4.0.2 and so on. However, the update
potential is limited by the value of the <samp>match</samp> attribute. Value <samp>equivalent</samp>
allows only service number increments. In contrast, <samp>compatible</samp>
would allow both service and minor increments.</p>
<p>The suggested use of this attribute is to allow only service updates.
Anything more would be a significant change and we suggest a full root update
instead (a service pack). Branch updates should be used as a short-term measure
(for patches and other minor updates).</p>
<p>By default, included feature will look for updates in the update site defined
by the root. This can be changed by defining <samp>search_location</samp>
attribute and setting it to <samp>self</samp>:</p>
<blockquote>
  <pre>&lt;includes id=&quot;com.example.acme&quot; version=&quot;4.0.0&quot; match=&quot;equivalent&quot; search_location=&quot;self&quot;/&gt;</pre>
</blockquote>
<p>Default value of this attribute (when not specified) is <samp>root</samp>.
When set to <samp>self</samp>, updates will be searched for in the update site
defined by the feature itself, instead of that of a root feature.</p>
<p><i>NOTE: match attribute is only considered when feature is part of the local
configuration. It is ignored when on the remote server. In the example above,
feature &quot;com.example.acme&quot; version &quot;4.0.0&quot; must be present
on the server. It is only when it is downloaded into the Eclipse product that
match attribute takes effect in reference resolution.</i></p>
<h2>Optional features</h2>
<p>All of the features included by the root one must be present within the same
site in order to be resolved. The exception are <b>optional features</b>.
Optional features are included features that users can opt not to install.
Optional features are declared using the attribute <samp>optional</samp>:</p>
<blockquote>
  <pre>&lt;includes id=&quot;com.example.acme&quot; version=&quot;4.0.0&quot; match=&quot;equivalent&quot; <b>optional=&quot;true&quot;</b>/&gt;</pre>
</blockquote>
<p>Optional features have the following properties:</p>
<ul>
  <li>It is not an error if an optional feature is missing on the remote server</li>
  <li>It is not an error if an optional feature is missing in the configuration
    (it just shows as 'not installed')</li>
  <li>Users are presented with the wizard page where they can select optional
    features for install using checkboxes</li>
  <li>Only optional features that are currently installed are updated to a newer
    version during root updates</li>
  <li>When features are installed from a remote server using Update Manager, the
    URL is remembered. Optional features can be subsequently installed by
    pressing 'Install' button (Update Manager will reconnect using the stored
    URL and install it).</li>
  <li>Unlike the regular ones, optional features can be disabled when part of
    the feature hierarchy</li>
  <li>Once disabled, optional features can be re-enabled providing that their
    parent is already enabled</li>
</ul>
<p>When not installed, optional features are hidden using the same filter as
disabled features and can be seen by turning the filter off (the local tool bar
button on the Configurations view in the Update Manager).</p>
<h2>Feature requires</h2>
<p>In 2.0.0, install/update prerequisites for features were plug-ins only:</p>
<blockquote>
  <pre>&lt;requires&gt;
	&lt;import plugin=&quot;org.eclipse.jdt&quot; version=&quot;2.0.0&quot; match=&quot;compatible&quot;/&gt;
&lt;/requires&gt;</pre>
</blockquote>
<p>Since 2.0.2, feature may require other features as a precondition for
installation:</p>
<blockquote>
  <pre>&lt;requires&gt;
&lt;import feature=&quot;org.eclipse.jdt&quot; version=&quot;2.0.0&quot; match=&quot;compatible&quot;/&gt;
&lt;/requires&gt;</pre>
</blockquote>
<p>The rest of the semantics didn't change. Prior to the installation, Update
will check all the constraints in 'requires' and block the operation if any of
them is not satisfied.</p>
<h2>Patches</h2>
<p>Update version 2.0.2 introduces a notion of <b>patches</b>. Patches are
regular features that are configured to bring partial updates to complex feature
tree hierarchies. Prior to 2.0.2, the only way to update a branch of a feature
tree was to update the entire hierarchy, including the root. Patches serve as
carriers that bring in partial updates to other features without updating their
roots.</p>
<p>Each patch consists of at least two features: the carrier (root) and the
update (the actual feature that has been modified). The role of the carrier is
to represent the patch entity in the configuration and to establish the
relationship with the hierarchy that is being patched. A patch can me more
complex and include several features, or entire branches.</p>
<h3>Definition</h3>
<p>For a regular feature to be a patch, two changes have to be made:</p>
<blockquote>
  <pre>&lt;feature 	id=&quot;org.eclipse.sdk.win32.e334&quot; 
		version=&quot;2.0.2&quot; 
		name=&quot;Patch e334&quot; 
		<b>colocation-affinity=&quot;org.eclipse.sdk.win32&quot;</b>&gt;
.....
     &lt;requires&gt;
        &lt;import feature=&quot;org.eclipse.sdk.win32&quot; version=&quot;2.0.2&quot; <b>patch=&quot;true&quot;</b>/&gt;
     &lt;/requires&gt;
     &lt;includes id=&quot;org.eclipse.pde&quot; version=&quot;2.0.2.e334&quot; match=&quot;equivalent&quot;/&gt;
&lt;/feature&gt;</pre>
</blockquote>
<p>The feature above will be a patch number e334. Its identifier is composed
that way, although this is not a requirement. Similarly, patch version is not
important but is convenient to use the same version as the feature that it
should patch. The important part is <samp>colocation-affinity</samp> attribute.
We used it to indicate that we want the patch installed in the same location as
the feature it patches (note that <samp>colocation-affinity</samp> is not new -
it is part of the 2.0.0 specification).</p>
<p>The second important change is the dependency on the patched feature. We used
attribute 'patch=true' to indicate that this feature is a patch for the
dependent feature. This will cause the following consequences:</p>
<ul>
  <li>When a patch is about to be installed, it will check the presence of the
    patched feature and will not install without it</li>
  <li>The dependency on the patched feature is 'exact' i.e. patches are always
    made for the exact versions</li>
  <li>When a patch is installed, it will seek out versions of the features that
    are older than the ones it includes, and will disable them</li>
  <li>Patch installation will fail if features that are supposed to be patched
    are newer than the ones included by the patch itself (this way, we prevent
    patches to introduce back-level code)</li>
</ul>
<p><b>A very important precondition for patches is that the feature hierarchy of
a patched product is capable of accepting them.</b> In other words, all child
features in the product must be included using the 'match' attribute other than
'perfect'. Partial (branch) updates must be possible for patches to be used.</p>
<h3>Grouping</h3>
<p>Patches can include any number of features that patch any point of the
patched feature's tree. In addition:</p>
<ul>
  <li>Patches can include other patches. A patch of one product can include a
    patch of another product elsewhere in the hierarchy.</li>
  <li>Patches may prerequisite other patches. This is similar to including but
    should be used when the required patch is not controlled by the same team
    (must be installed from another team's server). If your team owns both
    patches or can provide them both on the patch server, use inclusion instead.</li>
  <li>Patches may be grouped. A number of small patches can be grouped into an aggregate
    patch for easy installation.</li>
</ul>
<p>Patches can also be cumulative. In other words, a patch may bring an upgrade
to a feature already patched by a previous patch. Since two patches include the
same feature (just different versions), it is important that patches include
their features with a <samp>match</samp> set to a value that is not <samp>perfect</samp>
(typically <samp>equivalent</samp>). In the example above, patch e334 includes
patched version of the PDE feature. If a newer patch (e.g. e444) also fixes PDE
and includes version 2.0.2.e444 of it, the previously installed patch e334 will
not be broken upon installation of e444. When expanded in the Configuration
view, both patches will resolve to PDE version 2.0.2.e444. This is consistent
because 2.0.2.e444 subsumes 2.0.2.e334. It is a good practice to document that
fact in the description of the patch (something like 'this patch also includes a
fix for problem fixed by e334').</p>
<h3>Reverting a patch install</h3>
<p>When a patch is installed, current configuration is saved as a backup and
placed in the 'Saved Configurations'. This configuration has the following name
convention:</p>
<blockquote>
  <pre>@&lt;id&gt;_&lt;version&gt; backup</pre>
</blockquote>
<p>For example:&nbsp;</p>
<blockquote>
  <pre>@org.eclipse.sdk.win32.e334_2.0.2 backup</pre>
</blockquote>
<p>The naming convention is selected so that Update can programmatically locate
this configuration for cleanup. If a patch installation didn't produce a desired
result (the fix does not solve the problem or introduces side-effects), users
can back out of the installation by restoring this configuration. Patch install
is a complex operation and for that reason a revert must be used for this
(simply disabling a patch would leave the configuration in a wrong state and is
prevented for that reason).</p>
<h3>Cleanup</h3>
<p>Patches have limited life span. Since they are registered for a specific
feature ID and version, they become obsolete the moment the referenced feature
is upgraded to a new version. When a feature is disabled, all referencing
patches are disabled with it. In addition, all backup configurations for these
patches are removed.</p>
<p>It is important to understand the role patches are supposed to play in
feature updates. Patches should be used for emergency fixes (e-fixes) between
two official fix packs. Official fix pack is a full revision of a feature that
starts from the root (e.g. 2.0.1, 2.0.2, 2.0.3 etc.). Between two fix packs,
emergency fixes are used to provide a quick solution for a problem until the fix
pack becomes available. The implicit contract for patches is that the next
regular fix pack subsumes all the fixes provided between it and the previous fix
pack.</p>
<h2>Update activity log</h2>
<p>Since 2.0.2, Update is now writing an ever-growing file called <b>.install-log
</b>in the ./metadata/.config directory of the active workspace. This file
records all install activities as they are performed in the platform and is not
subject to configuration history limit set in the Update preferences.</p>
<h2>Configuration history timelines</h2>
<p>Eclipse Update is designed to cope with changes on the file system and try to
reconcile these changes with its internal state. When these changes are
considered controlled (e.g. when a new feature is added by a native installer),
it reconciles the change within the same <b>timeline</b>. A <b>timeline</b> is a
sequence of installation events that are considered mutually compatible. Stable
states in the timeline (shown as configurations in the history) can be subject
to the 'revert' operation (i.e. it is allowed to revert to any configuration
within the same timeline).</p>
<p>Sometimes, the change made to the file system is considered so radical
(location has changed, critical platform files have changed etc.) that Update
throws the towel and initiates full reconciliation. Full reconciliation discards
previous state and re-computes it from the ground up, enabling all the features
in the process. Full reconciliation starts a new timeline. Once that happens, it
is not possible to go back to a previous timeline using the 'revert' command.
Configuration elements that belong to a different timeline are clearly marked in
the configuration history with an icon overlay.</p>
<h2>Other changes</h2>
<ul>
  <li>Plug-in search results are now presented in a Search Result view that
    shows up below the Details view.</li>
  <li>A number of defects have been fixed (see 2.0.2 release notes for details)</li>
  <li>Discovery sites from features that are not root are now not shown in the
    'Sites to Visit' folder</li>
  <li>Installations that will cause duplicate features in multiple linked
    extensions to be in conflict (different versions) are flagged with a
    detailed warning dialog, allowing users to cancel the install</li>
  <li>Quick search for updates (Help-&gt;Software Updates-&gt;New Updates) is
    modified to find new versions of branches that are capable of updating
    (match!=perfect). Filter in the quick search wizard can compute the highest
    feature in the hierarchy that includes all other search results and hide the
    rest</li>
</ul>
<p>&nbsp;</p>
<p>&nbsp;</p>
<p>&nbsp;</p>