Configuration Management Support in Eclipse Process Framework

Version 1.0


Introduction

This document outlines the usage of a supported Configuration Managment (CM) System with Eclipse Process Composer (EPF).

Support for CM Systems

EPF provides limited support for 2 code management (CM) systems:

Before EPF can be to make changes to a local copy of the Method Library, the source files that make up that library must be writable. CM systems usually maintain local files with read-only access unless they have been explicitly marked for editing through the process of checking-out individual files. Source files in the Method Library must be checked-out before they can be edited.

Note: EPF users in CM-integrated environments should be aware that relatively simple changes to method library elements may affect more than one source file. This implies that multiple files may have to be checked-out before individual method elements can be modified.

Information from the method library is cached in memory when a new library is opened. If library source files are updated outside of EPF the version cached in memory will not be refreshed. In that situation users should reload the entire method library. Alternately the libary files can be updated from within the Resource perspective.

As soon as the method library is opened EPF will create two files named .lock and .project at the same level as library.xmi. These two files should NOT be placed under version control.

Support for Rational ClearCase

Initial Setup

Integration with IBM(R) Rational ClearCase requires the SCM Adapter plug-in for Eclipse 3.1 be installed and activated in EPF. The SCM Adapter can be downloaded from http://www-128.ibm.com/developerworks/rational/library/content/03July/2500/2834/ClearCase/clearcase_plugins.html. Make sure this is downloaded and unzipped locally before proceeding.

Upon launch EPF will prompt the user to supply the location of the method library. Since the local copy of the method libray under source control hasn't been set up yet the user should simply accept the default choice. This will allow EPF to complete the launch process. Once EPF has launched use the following instructions to set up a source-controlled copy of the method library:

  1. Use the Help menu at the top of the EPF window.
  2. Select Software Updates > Manage Software Configuration... The "Product Configuration" window will appear.
  3. In the Product Configuration window, click Add an Extension Location. The extension in this case is the SCM adapter.
  4. Use the Browse for Folder dialog box to navigate to the folder with the SCM adapter.
  5. Select the Eclipse folder and click OK.
  6. The "Install/Update" dialog prompts the user to restart EPF. Click Yes.
  7. When EPF restarts the user will be prompted to supply to location of the method library. Use the default (temporary) selection.
  8. In the EPF main tool bar window, click Window > Customize Perspective....
  9. In the Customize Perspective dialog box, click the Commands tab.
  10. In the Available command groups column, check the box for ClearCase and click OK.

The main tool bar at the top of the Eclipse window will now include a new pull-down menu labeled “ClearCase"?. At this point users can create their ClearCase snapshot view.

  1. Use the ClearCase menu and select Connect to Rational ClearCase. A small check mark will appear next to this selection in the menu when the connection is successful.
  2. Use the ClearCase menu and select Create New View.... The standard ClearCase view creation wizard will then guide the user through the rest of the setup.
  3. Select the appropriate VOB to load and click OK. VOB elements are loaded.
  4. Click OK. A dialog box should appear with the message “View successfully created"?.
  5. At this point a local copy of the method library has been created but the EPF application is still pointed to the temporary library opened earlier. Use the File menu at the top of the EPF window and select Open.
  6. Navigate to the location of the snapshot view and open the newly-created copy of the method library.

Editing a Method Element

  1. Make sure the Authoring perspective is being used. Method elements can only be edited from within this perspective.
  2. When a user tries to edit an existing element a dialog box will appear with a message prompting the user to check-out the appropriate library source file.
  3. As edits are made the tab at the top of the editing window will display a "*" next to the element name. This indicate that changes have been made but not saved at this point. When the file is saved through the File - Save command the "*" will disappear.
  4. Switch to the Resource perspective.
  5. Use the ClearCase menu and select Find checkouts. Check in all changed files at once.

Note: It is very important to check in all files in one batch. If this isn't possible then don't check in any files.

Adding a Method Element

  1. Make sure the Authoring perspective is being used. New method elements can only be added from within this perspective.
  2. Use the tree-browser to navigate to the area where the new element will reside.
  3. Right-click on the target location to bring up secondary menu and select Add new element.
  4. The “Add to source control"? dialog box will appear.
  5. Note: If prompted to Add to Source Control the .lock and .project files, deselect them in the “Add to source control"? dialog box.

Deleting a Method Element

  1. Before deleting a method element, make sure that it and any files that depend on it are checked-in. If the file is not checked-in it may be left behind in the file system.
  2. Make sure the Authoring perspective is being used. Method elements can only be deleted from within this perspective.
  3. Right-click on the target element to bring up secondary menu and select Delete.

Support for Rational CCRC 7.0

Initial Setup

EPF integration with IBM(R) Rational CCRC 7.0 requires a CCWeb enabled ClearCase 7.0 (with IFIX1) server and the installation of an additional plugin. Enabling CCWeb is out of the scope of this document. Please contact your ClearCase administrator for CCWeb enablement. Once CCWeb is enabled and functional, The CCRC plugin can be downloaded from http://www3.software.ibm.com/ibmdl/pub/software/rationalsdp/clearcase/ccrc/70/update/. Make sure this URL can be resolved before proceeding but do not download it at this time.

Upon launch EPF will prompt the user to supply the location of the method library. Since the local copy of the method libray hasn't been set up yet users should simply accept the default choice. This will allow EPF to complete the launch process. Once EPF has launched the plugin can be installed by following these instructions:

  1. Use the Help menu at the top of the Eclipse window and select Software Updates.
  2. From the submenu select Find and Install…. The "Install/Updatge" window will appear.
  3. Select Search for new features to install then click Next.
  4. Select New remote site. The "New update site" window will appear.
  5. Enter these values in the "New update site" window:
  6. Expand the selections menu until the correct plugin is exposed. Select "Rational ClearCase Remote Client 7.0.1 for Eclipse" then click Next.
  7. Agree to the conditions in the license statement and click Next.
  8. Make sure the installer is pointing to the location of EPF and click Finish. The "Verification" window will appear.
  9. Click on Install All when prompted. The "Install/Update" window will appear.
  10. Click Yes to restart the workbench (EPF).

At this point the CCRC plugin has been installed but some additional configuration is needed. In routine usage EPF will create temporary files in the same folder as the library source files. CCRC will detect these temporary files and prompt the user to add them to source control, which should not be done. To avoid this, the CCRC preferences should be set to ignore new resources when added.

  1. Use the Window menu then select Preferences.
  2. Expand the ClearCase Remote Client tree node.
  3. Select Editors/Workspace.
  4. Make the following change to the default Editors/Workspace settings:

A new perspective called "ClearCase" will be available and new icons should appear in the main tool bar at the top of the EPF window. At this point users can create their ClearCase snapshot view. It is a good practice to create the snapshot view outside of the default EPF workspace.

  1. Switch to the ClearCase perspective.
  2. Click on the icon that looks like a magnifying glass with a plus sign on it. The "Create Base ClearCase View" dialog box will appear.
  3. Enter the URL of the ClearCase Web server and the user authentication credentials, then click Next.
  4. Select load rules to populate the new view with the appropriate VOBs.

The EPF workspace is now populated with library source files managed by CCRC.

Editing a Method Element

  1. Make sure the Authoring perspective is being used. Method elements can only be edited from within this perspective.
  2. When a user tries to edit an existing element a dialog box will appear with a message prompting the user to check-out the appropriate library source file.
  3. As edits are made the tab at the top of the editing window will display a "*" next to the element name. This indicates that changes have been made but not saved at this point. When the file is saved using the File - Save menu the "*" will disappear.
  4. Switch to the Resource perspective.
  5. Use the ClearCase menu and select Find checkouts. Check in all changed files at once.

Adding a Method Element

  1. Make sure the Authoring perspective is being used. New method elements can only be added from within this perspective.
  2. Use the tree-browser to navigate to the area where the new element will reside. Identify the parent node of the new elment.
  3. Right-click on the parent element to bring up secondary menu and select New Method Plug-in. The “Add to source control"? dialog box will appear.
  4. If prompted to check-out the .lock and .project files, deselect them in the “Add to source control"? dialog box.

Deleting a Method Element

  1. Before deleting a method element, make sure that it and any files that depend on it are checked-in. If the file is not checked-in it may be left behind in the file system.
  2. Make sure the Authoring perspective is being used. Method elements can only be deleted from within this perspective.
  3. Right-click on the target element to bring up secondary menu and select Delete.

Support for CVS

Initial Setup

EPF provides out-of-box support for CVS (Code Versioning System) so no additional software extensions are needed. Use the following instructions to configure CVS integration with EPF:

  1. Use the Window menu at the top of the EPF window and select Preferences.... The "Preferences" configuration window will appear.
  2. Expand the tree menu for Team in the left-hand side of the Preferences window then expand the submenu for CVS.
  3. Click on Watch/Edit. The Watch/Edit check boxes should be set as follows:
    1. Settings for CVS Watch/Edit: Check Configure projects to use Watch/Edit on checkout.
    2. When read-only files are modified in an editor: Check Send a CVS edit notification to the server.
    3. Before a CVS edit notification is sent to the server: Check Always prompt.
    4. Update edited files: Check Prompt to update if out of date.
  4. Click OK.
  5. Switch perspective to CVS Repository Exploring. This perspective shows files on the CVS server.
  6. Right-click in the blank window area.
  7. Select the New repository location. The "Add a new CVS Repository" dialog box appears.
  8. Enter settings supplied by CVS system administrator. These settings should include the following:
Now the snapshot view can be populated.
  1. Switch to the CVS Repository Exploring perspective.
  2. Go to the HEAD or Branch nodes.
  3. Right-click and select Check out to check out the desired library.
  4. By default the library is checked out in the EPF workspace.

Editing a Method Element

  1. Make sure the Authoring perspective is being used. Elements can only be edited from within this perspective.
  2. Use the tree-browser to find library element you want to edit.
  3. Double click on the element name to bring its contents into Editor window.
  4. As soon as changes are made to an element a "*" will appear on the tab at the top of the Editor window next to teh name of the element.
  5. Use the File menu then select Save to save changes. The "*" symbol will disappear indicating the local filesystem has been updated with the version currently cached in memory.
  6. When prompted to send a CVS notification answer Yes.
  7. If the file is currently being edited by another user a dialog box will appear with the option to continue or not. Answer No or else the files will have to be merged later.
  8. Switch to the Resources perspective. In this perspective files that have been modified and need to be checked-in are marked with a ">" symbol.
  9. Right-click to bring up Team menu, then Commit.

Note: Users should either check-in all files or else don't check-in any of them.

Adding a Method Element

  1. Make sure the Authoring perspective is being used. New elements can only be added from within this perspective.
  2. Use tree browser to locate the area where the new element will be added.
  3. Right-click on the parent element. A submenu will appear.
  4. Select Add.
  5. Enter content for the new element in the Editor window. A "*" symbol will appear next to the name of the new element in the tab at the top of the Editor wndow. This indicates the version cached in memory is out-of-synch with the local filesystem.
  6. After entering content for the new element use File menu and select Save. The "*" symbol will disappear indicating that the copy in the local filesystem has been updated with the verison cached in memory.
  7. Switch to the Team Synchronizing perspective.
  8. The new element should be listed there along with any dependent files. The dependent files may include plugin.xmi. Make sure this file is also updated.
  9. Richt-click on the element to be added and select Commit....

Deleting a Method Element

  1. Make sure the Authoring perspective is being used. Elements can only be deleted from within this perspective.
  2. Locate the element you wish to delete in the tree browser.
  3. Right-click on the name of the element and select Delete from the submenu.
  4. Use the File menu at the top of the EPF window and select Save.
  5. Switch to Team Synchronizing perspective. 1 or more files will be listed there. Look for a special icon next to files marked for deletion.
  6. Right-click on the file to be deleted and select Commit.... The file should disappear from the list on the right.

Known Issues

Library imports require all files be checked-in.

Before attempting to import a secondary library onto a base library all files in the base library must be checked in. All other users should be notified to not perform any operations that would affect this file. The person doing the import should update all local files and then make a backup copy of the entire method library. During the import process files that are no longer used will be deleted, so if the import fails for any reason they will need to be restored. When the import has completed sucessfully the entire library should be carefully checked for integrity. The merged library can then be checked back into the CM system.

Concurrent changes to library.xmi may cause problems.

If 2 users make changes to library.xmi concurrently their changes will have to be merged. There are several operations that impact this file including adding a new configuration or plugin. It is very difficult to merge changes to library.xmi so steps should be taken to avoid this situation. Before making changes which impact this file it is recomended that all users check-in their files. After the changes are made the new version should be synched with the CM server and then email can be sent to all users notifiying them that they can resume making edits.

Checking in files outside of EPF will not refresh icons.

If files are checked-in to the EPF workspace by using the tools under the ClearCase menu icons in the Resource perspective will not be updated to show the new status. The check-in operation will succeed but files will still appear to be checked-out. In this situation use the Refresh Status menu item on the file being checked-in.

Cannot add new library to ClearCase VOBs using Share Project

The ClearCase "Share Project" command can not be used to upload a new library to the VOB. Users will have to use ClearCase tools to perfrom this operation. Contact your local ClearCase Administrator for help with this activity.

Do not check in or commit .project and .lock files.

Do not check in (using ClearCase) or commit (using CVS) the .project and .lock files. These temporary files should not be put under source control. Both of these files need to be writable before the method library can be opened.

Unresolved errors in library view can occur during automatic updates.

If a warning message appears during editing about a newer version of a file on the server, update the entire local snapshot to ensure that library.xmi, plugin.xmi, and method element files are synchronized with the server.

Using Team Share

A library can be added into CVS using Team - Share Project. When that library is checked-out it will automatically be placed inside the EPF default workspace. For ClearCase users the Team -Share Project operation doesn't work.

Checking out old files in CCRC may require a merge.

CCRC will let you check out older versions of files which will require a merge during check-in if other users have made modifications and checked them in.