Scenario: Updating Eclipse Install Using The Update Manager

NOTE: The test scenarios are being updated to match the F2 build structure. At present, only scenario Part 2 (Alphabet Soup) can be tried

Last Updated: June 1, 2002 2:45PM .... being updated

Objectives:

The objective of these scenarios is to illustrate the Eclipse update manager function through simple end-to-end use cases. The scenarios are divided into two parts.

Part-1 excercises updating of Eclipse itself from a test site containing Eclipse builds repackaged as downloadable features. The Eclipse feature structure is a reasonable representation of a non-trivial product. It contains a primary feature (the platform) and a number of other features ( jdt, pde, etc) and is nested.
Part-2 uses an example "product" to go through the various steps of updating and extending it using both the update manager, as well as native installation (using .zip file containing features and plugins that can be extracted directly into the file system)

Part 1: Updating Eclipse

Setup:

Available sites:

http://download.eclipse.org/updates/

*** PLEASE READ *** PLEASE READ *** PLEASE READ *** PLEASE READ ***

As part of this scenario you will be downloading and installing various versions of the Eclipse components into the running Eclipse. The update site is populated with features that have their version numbers modified as part of the build process. They are generally of the form 2.0.0.QUALIFIER, where the qualifier differs build to build. Note, however, that when you install base Eclipse (.zip downloaded from eclipse.org), all of its features and plugins only use 3 part version identifiers (generally 2.0.0). So all the 2.0.0.Q updates in fact appear more recent that the build you are running, even though they may in fact be an older build. Note, that when you update the Eclipse components from the update site and restart you may in fact now be running DIFFERENT CODE THAN WHAT YOU STARTED WITH. So it is really important that you save your starting configuration (scenario steps B) and restore it (scenario steps F) when told by the scenario, or any time you have in fact updated the Eclipse Paltform feature (includes the update manager support). It is suggested that you always use a second install of Eclipse running with a different workspace to actually run through these scenarios.

When openning Bugzilla defects, use the platform/update component. Please ALWAYS specify the failing scenario step, and include a .zip of the <workspace>/.metadata/ directory

Steps:

Install second copy of Eclipse to run these scenarios ... do not use your development copy of Eclipse for this.
either use the default workspace created by the second Eclipse copy, or specify (-data) a new workspace for these scenarios

A. Startup new Eclipse

A.1. startup Eclipse. On the initial startup with new workspace you should see the splash come up, be taken down down, and come up again before it is finally taken down before the Workbench appears. This is due to Eclipse restart when new features are detected on startup.
A.2. go to update manager and verify that the features corresponding to the baseline install appear in the "Current Configuration"

B. Save baseline configuration

B.1. in "Configuration" view, expand "Configuration History"
B.2. select the current configuration (at this point it should be the only one)
B.3. popup menu, Save
B.4. expand "Saved Configurations"
B.5. select the configuration you have just saved
B.6. popup, Properties, change name to "Baseline"

C. View the test site

C.1. create new site bookmark (popup in Updates view, New> Site Bookmark...)
C.2. type in a name (eg. Eclipse Updates) and copy the test site URL as specified in the scenario "Setup"
C.3. New site bookmark appears ... expand it. You should see categories representing various available updates.

Note: the content of the site will be changing (ie. will be growing) as new builds become available

C.4. select the category representing the latest build and expand the list of individual features
C.5. you should see features corresponding to the updates
C.6. uncheck the "Show matching features only" .... you should not see other platform-specific features that do not match you environment
C.7. check the "Show matching features only" again (to reduce the clutter)

Note: at various points in the scenarios you are asked to verify the configuration state of features. To see disabled (unconfigured) features you need to press the "Show disabled features" button in the Configuration view tool bar

D. Update JDT and its source

Note: JDT is "middle of the stack" feature

D.1. select "Eclipse Java Development Tools"
D.2. Click [Update] in the Preview and follow the Install Wizard (taking defaults) to install the feature.
D.3. DO NOT restart the workbench when prompted (on completion of the installation)
D.4. select "Eclipse Java Development Tools SDK"
D.5. Click [Update] in the Preview and follow the Install Wizard (taking defaults) to install the feature.
D.6. Restart the workbench when prompted (on completion of the installation)
D.7. workbench should restart automatically, and open into Update manager
D.8. expand "Current Configuration" and verify you now recognize the new versions of the 2 features that were updated. Click on the "Show Disabled Features" button to see the prior versions of the features (different icon). The unconfigured feature should show a warning overlay (but may not, depending on the combination of the base build and the update). If they do, select the feature, right click, Show Status ... The error dialog shows details (in this case reporting the fact that if this feature were to be configured it would result in multiple versions of the same plugin being configured)

confusing message text, defect 16712

D.9. go to Help> About dialog, [About Plug-Ins] and verify you are in fact running updated versions of the JDT plugins.

E. Update PDE

Note: PDE is a "top of the stack" feature

E.0. expand the update site bookmark (in Updates view) to show the available individual features for the latest build
E.1. select "Eclipse Plug-In Development Environment"
E.2. Click [Update] in the Preview and follow the Install Wizard (taking defaults) to install the feature.
E.3. Restart the workbench when prompted (on completion of the installation)
E.4. workbench should restart automatically, and open into Update manager
E.5. expand "Current Configuration" and verify you now recognize the new version of the feature that was updated
E.6. go to Help> About dialog, [About Plug-Ins] and verify you are in fact running updated versions of the PDE plugins.

F. Restoring Original Configuration

F.1. expand "Saved Configurations"
F.2. select "Baseline" created in step B
F.3. press restore
F.4. Restart the workbench when prompted
F.5. workbench should restart automatically, and open into Update manager
F.6. expand "Current Configuration" and verify all configured features are the baseline feature versions (generally 2.0.0)
F.7. click the "Show disabled features" button in the Configuration view tool bar
F.8. verify "Current Configuration" shows the features updated in steps D and E as disabled (different icon)
F.9. go to Help> About dialog, [About Plug-Ins] and verify you are in fact running the baseline plugins (all 2.0.0, except for the "special cases" like xerces, ant, luce, tomcat, etc)

G. [removed]

H. [removed]

I. Update the platform

Note: platform is a "bottom of the stack" feature, and is the primary feature

I.0. expand the configuration view. Select the "Eclipse Platform" feature. In preview, click [Disable] ... should be notified you cannot disable the platform or a primary feature (our selection is both)
I.1. expand the update site bookmark (in Updates view) to show the available individual features for the latest build
I.1. select "Eclipse Platform"
I.2. Click [Update] in the Preview and follow the Install Wizard (taking defaults) to install the feature.
I.3. Restart the workbench when prompted (on completion of the installation)
I.4. workbench should restart automatically, and open into Update manager

PLEASE NOTE: at this point you are no longer executing the update manager code you started with, but rather are running a version of the update manager that was contained in the update (along with the rest of the platform plugins). If you did not select the latest build from the update site (and instead selected some old build) the platform may not even restart, and you may need to reinstall eclipse to continue. Do not report defects in this step unless you did get the latest available update.

I.5. expand "Current Configuration" and verify you now recognize the new version of the platform that was updated
I.5.1. go to Help> About> [About Plug-Ins] to verify you are running new version of the platform.
I.6. repeat step F to restore the original configuration (ie. the code you are testing)

J. [removed]

K. "Natively" installed extension

Note: if you performed Step I, make sure you repeat step F (revert to original configuration) and then shot down.

K.0. in the first 2 steps you will be performing manually a linking task typically done by the extension native installer (end users will never need to do this)
K.1. unzip the "RedDot" extension somewhere into the file system (the .zip contains a root directory RedDotInstall)
K.2. manually create a link file in the Eclipse install you are using

in the eclipse/ directory, create links/ subdirectory
in the links/ subdirectory create a file called "reddot.link"
edit the file and type in a line

Note: the path value is a file path to the target install directory using native OS format. On Win, double up backslashes, eg. path=c:\\temp\\RedDotInstall

K.3. start Eclipse. Should observe Eclipse restarting (doing the "2 splash dance")
K.4. workbench opends with a dialog saying we have detected changes.
K.5. click [OK] to open Update Manager
K.6. Configuration Changes wizard shows. Check the changes you want to apply (check the box beside the change, should only see one change)
K.7. Click [Finish] and restart the workbench when prompted
K.8. workbench should restart automatically. Open the update manager (if not opened already ... depends if it was opened when the change was detected)
K.9. expand "Current Configuration" and verify you now recognize the new extension site and it contains configured RedDot feature
K.10. Window> Customize Perspective...> Other> check Red Dot Set, [OK]
K.11. verify new tool button appears, and a dialog shows when the button is clicked.

Part 2: Alphabet Soup

Setup:

Available sites:

http://dev.eclipse.org/viewcvs/index.cgi/%7Echeckout%7E/platform-update-home/site/

The above site contains prebuilt features used as part of the following scenario steps. It also includes several .zip files (containing features and plugins) that are used to simulate native installer steps.

*** PLEASE READ *** PLEASE READ *** PLEASE READ *** PLEASE READ ***

When openning Bugzilla defects, use the platform/update component. Please ALWAYS specify the failing scenario step, and include a .zip of the <workspace>/.metadata/ directory

Description:

The Alphabet Soup is a simple application packaged as an Eclipse product, plus several extensions. The application installs a tool button, and a menu ("Alphabet Soup") that can be used to query the content of the "soup bowl" and interact with the individual installed "letters" (each letter in the bowl corresponds to a separate plugin)

base product is a nested feature, my.alphabet, containing two sub-features with base sets of "letters"
3 extension features containing additional "letters" (plugins). The features have a dependency relationship as follows:

"round letters" extension pack requires the base to be installed
"straight letters" extension pack requires "round letters" extension pack to be installed
"numbers" extension pack requires both "round letters" extension pack and "straight letters" extension pack to be installed

Just follow the steps and you'll get the idea.

Steps:

Install second copy of Eclipse to run these scenarios ... do not use your development copy of Eclipse for this.
either use the default workspace created by the second Eclipse copy, or specify (-data) a new workspace for these scenarios

O. Completing the install

O.1. after you have installed baseline eclipse, unzip the Aplhabet Soup product features from my.alphabet_1.0.0.zip into the eclipse/ installation directory. The unzip should overwrite the install.ini file that is packaged with Eclipse (sets the Alphabet Soup feature as the primary feature). The product feature .zips can be found in http://dev.eclipse.org/viewcvs/index.cgi/%7Echeckout%7E/platform-update-home/site/native/
O.2. start eclipse .... after "Completing the install ..." the platform restarts as "Alphabet Soup" application (own Welcome, About)
O.3. Click on the "Alphabet Soup" button in the tool bar ... you should have letters A, B, C and E (all 1.0.0) in your bowl.
O.4. Go to the "Alphabet Soup" menu and verify you can interact with each letter (one action per letter on the menu)
O.5. Open Help> Software Updates> Update Manager
O.6. Expand "Current Configuration". Verify "Alphabet Soup 1.0.0" is configured, and it contains 2 subfeatures (Round and Straight letters)
O.7. click on each of the features and view more details about each freature
O.8. select "Alphabet Soup 1.0.0" and press [Disable]. You should be notified that you cannot disable the primary feature (if this is not the case, [Cancel] the disable action and report a defect).

P. Updating the primary feature using update manager

P.1. expand "Sites to Visit", and "Alphabet Soup Update Site" and "Alphabet Soup Category"

wait for it to expand, even after the "hourglass" disappears - defect 16487

P.2. Select "Alphabet Soup 1.0.0" ... preview should not show [Update] button
P.3. Select "Alphabet Soup 1.0.1" and select [Update]. Go through the install wizard accepting defaults.
P.4. Restart the workbench when prompted. Will restart with update manager open.
P.5. Expand "Current Configuration" .... verify you now have Alphabet Soup 1.0.1 installed and configured.
P.6. Click the "Show disabled features" filter button .... should see both versions (one configured, the other unconfugured (icon with grey "stop" overlay))
P.7. click the "Alphabet Soup" tool button ... should show new versions of the base letters (1.0.1). The actions on "Alphabet Soup" menu should also indicate we are running the new version.
P.8. close update manager
P.9. shut down the workbench

Q. Updating the primary feature using "native" install (.zip)

Q.1. unzip the Aplhabet Soup product features from my.alphabet_1.1.0.zip into the eclipse/ installation directory (look into the features/ or plugins/ subdirectory to veify you see new 1.1.0 versions)
Q.2. start Eclipse (a.k.a. Alphabet Soup). You'll see the splash comming up twice as the platfrom is updating the configuration. Workbench will come up, with a dialog informing you have changes. Click [OK] to open the update manager change dialog.
Q.3. check the change (so it is applied) and press [Finish]

nested structure not shown - defect 16496

Q.4. restart the workbench when prompted
Q.5. click the "Alphabet Soup" tool button and trigger "Alphabet Soup" menu action to see you have the new version (1.1.0) of the "soup bowl and letters"
Q.6. Open update manager and expand "Current Configuration". Should see Alphabet Soup 1.1.0 configured, and the other 2 unconfigured (click the "Show disabled features").

showing 2 features as configured - defect 16502

R. Adding an extension using the update manager

R.1. expand "Sites to Visit", "Alphabet Soup Update Site", "Alphabet Soup Fun Pack - Round Letters"

wait for expansion (defect 16487 as in P.1.), ignore duplicate sites (defect 16502 as in Q.6.)

R.2. select "Alphabet Soup Round Letters Extension Pack 1.0.0" and click [Install]. Accept defaults in wizard and [Finish]. Restart workbench when prompted.
R.3. click of the "Alphaber Soup" tool button and interact with "Alphabet Soup" menu to see new round letters (D and G). Note: may need to go to Window> Costomize Perspective...> Other and select the action sets for the new letters
R.4. expand Current Configuration ans verify the new feature is showing as configured.
R.4. close the update manager and shut down the workbench

S. Adding an extension using "native" install (.zip) and link file

S.0. Note: the first 3 steps will typically be performed by a native installer. Since you are simulating these steps you need to do this manually.
S.1. Set up a new install directory somewhere in your file system. Create eclipse/ subdirectory under it. Unzip the Aplhabet Soup Straight Letters extension from my.alphabet.more.straight.letters_1.0.0.zip into the eclipse/ subdirectory. You should end up with

<some new install directory>/

S.2. In the original eclipse install (the one that contains the platform and Alphabet Soup), create a new directory called "links" as a peer to features/ and plugins/. You should end up with

<eclipse platform install directory>/

S.3. within the links/ subdirectory, create a file called my.alphabet.link and add a single line into it

path=<some new install directory>

Note: the path should be an absolute path using local file system syntax. The .link file is loaded as a Java properties file, so on Windows you need to double up the back-slashes (eg. path=c:\\temp\\install)

S.4. start eclipse (Alphabet Soup). You'll see the splash comming up twice as the platfrom is updating the configuration. Workbench will come up, with a dialog informing you have changes. Click [OK] to open the update manager change dialog.
S.5. check the change (so it is applied) and press [Finish]
S.6. restart the workbench when prompted
S.7. click the "Alphabet Soup" tool button and trigger "Alphabet Soup" menu action to see you have the new letters.

Note

S.8. Open update manager and expand "Current Configuration". Should see a new site representing the extension install, and it should contain the extension feature you've installed.

side note: the symptoms of defect 16502 (Q.6.) disappear

T. Installing another extension using the update manager (with environment filtering)

T.1. expand "Sites to Visit", "Alphabet Soup Update Site", "Alphabet Soup Fun Pack - Numbers"

wait for expansion (defect 16487 as in P.1.)

T.2. The Numbers extension specifies an OS in its feature definition. The update site contains features for Win and Linux. On those two platforms you should see a list of features designated for than platform. On other platforms you are out of luck ... you don't get to play with numbers (skip the rest of this step)
T.3. uncheck the "Show matching features only" filter .... should now see all the features for both platforms. Check the filter back again.
T.4. select "Alphabet Soup Numbers Extension Pack for <OS>1.0.1" and click [Install]. Accept defaults in wizard. In the location selection page ensure the extension location created in steps S is not offered as a choice. Press [Finish]. Restart workbench when prompted.
T.5. click of the "Alphabet Soup" tool button and interact with "Alphabet Soup" menu to see new numbers (3 and 5). Note: may need to go to Window> Costomize Perspective...> Other and select the action sets for the new numbers
T.6. expand Current Configuration ans verify the new feature is showing as configured in the original install site
T.7. close the update manager and shut down the workbench

"Free-form" testing

the above scenarios describe a path through the update support. Run through it once as described. There is lot's of opportunity to do thing in different order, click on ither buttons, try other features in the UI. Go ahead an explore. Remember, is you see something that does not work, is not correct, or is not what you'd expected, open Bugzilla defects in the platform/update component. Please ALWAYS specify the steps leading up to the failure, and include a .zip of the <workspace>/.metadata/ directory

Part-3: Adopting Eclipse

Setup:

Available sites:

http://klicnik.torolab.ibm.com/shrek/

Note: this site is not available on the public internet. It is a test site containing an example of Eclipse packaged as a nested feature. The data on the site contains only Eclipse support for Windows.

Description:

This scenario starts with base eclipse install. It is then updated with new feature definitions that "adopt" the features in the base build into a nested structure. The base nested feature containing Eclipse runtime support is then updated to a new version.

Steps:

Install second copy of Eclipse to run these scenarios ... do not use your development copy of Eclipse for this.
either use the default workspace created by the second Eclipse copy, or specify (-data) a new workspace for these scenarios

V. Adopting "Flat" Eclipse

V.1. startup Eclipse. On the initial startup with new workspace you should see the splash come up, be taken down down, and come up again before it is finally taken down before the Workbench appears. This is due to Eclipse restart when new features are detected on startup.
V.2. go to update manager and verify that the features corresponding to the baseline install appear in the "Current Configuration"
V.3. create new site bookmark (popup in Updates view, New> Site Bookmark...)
V.4. type in a name (eg. Nested Updates) and copy the test site URL as specified in the scenario "Setup"
V.5. New site bookmark appears ... expand it. You should see a category "Adopt Flat Eclipse". Expand it, and select "Eclipse Runtime for Windows". Note this is a nested feature. Click on the [+] to see its content. Note that is you select any of the child features you cannot perform update functions on these (no action buttons in preview). If you select the parent you should see [Install]
V.6. Click [Install] when the parent feature is selected and and follow the Install Wizard (taking defaults) to install the feature. The install should be very fast, since all the plugins referenced by the nested structure are already installed (they are the base 2.0.0 versions)
V.7. Restart the workbench when prompted (on completion of the installation)
V.8. workbench should restart automatically, and open into Update manager
V.9. expand "Current Configuration" and verify the baseline features have been "adopted" into the nested structure. The baseline SDK features remain non-nested (top level features)
V.10. go to Help> About> [About Plug-Ins] and verify you are still running the baseline versions of all plugins (ie. the update only affected the feature structure)
V.11. Expand "Current Configuration". Select the nested feature and press [Disable] in the preview. You should be notified that you cannot disable the feature (contains the platform).

W. Updating the nested Eclipse

W.1. Expand the update site bookmarked in the previous step. This time expand the NESTED category corresponding to the latest build. Select "Eclipse Runtime for Windows".
W.2. Click [Update] when the parent feature is selected and and follow the Install Wizard (taking defaults) to install the feature. The install should be slow, since we are downloading all new features and plugins (they are the 2.0.0.QUALIFIER versions). Do not do this step unless you have a reasonably fast connection.
W.3. Restart the workbench when prompted (on completion of the installation)
W.4. workbench should restart automatically, and open into Update manager
W.5. expand "Current Configuration" and verify you now have an updated version of the nested feature (new parent version as well as new children)
W.5. go to Help> About> [About Plug-Ins] and verify that all runtime plugins have in fact been updated to the new version (the SDK plugins have not)