3136 - Refactoring and Synchronization with the StarTeam Plug-in for Eclipse

Jim WogulisPrincipal Architect, Borland Software Corporation

Introduction

In a team environment, how can users synchronize their local workspace with the most recent changes in the repository?

How do I check-in/update my local changes in to the repository? StarTeam standalone client has “file status” and tools to help

synchronize files, but sometimes they are insufficient. Common software development practice of “refactoring” makes the

problem harder and more frequent. Need to handle renames, moves, deletes as well as simple content

change. Don’t want the difficulty of synchronizing files to influence our use of

important software development practices.

StarTeam Eclipse Plug-in

Provides access to artifacts in a StarTeam repository Server explorer to browse StarTeam repositories Allows you to map StarTeam projects to Eclipse projects Provides decorators to resources in package explorer Provides sophisticated tools for synchronization of local

and remote resources

Getting Started with the Plug-in

Download and install StarTeam Plug-in For Eclipse http://www.borland.com/downloads/download_starteam.html

To share an existing project: Create empty eclipse project Right click on project, select Team > Share Project… Select repository type “StarTeam” Choose the server, project, view and root folder

OR.. Open “Server Explorer View” Browse to desired StarTeam project/view/folder Right click “Check Out as Project…”

StarTeam Status Decoration

“Rollup” Status Label Decorations

Current

Incoming change

Outgoing change

Bidirectional change (both incoming and outgoing)

Unknown Status

Eclipse Synchronize List View

Based on selection in project explorer Lists resources in the selected container and below. Columns:

Resource name Status Action Dependencies

Can filter list entries to show only “Incoming” changes “Outgoing” changes or both.

Can toggle the list to show resources already in sync (“current”). Can run the synchronization process on all or just a selected set of

resources.

Synchronization List Entries

Can override default settings on a per-resource basis for: Lock Status Associated Process Item Revision Label Synchronization Action

Compare local resource changes with remote resource. Can perform synchronization on a single resource.

Status Values

Synchronization Actions

Synchronize Takes the “appropriate” action, e.g. does a check-in for an “Outgoing

Change”, will also synchronize any dependencies. Conform to Remote

Abandon local changes, e.g. “Force Check-out” Conform to Local

Ignores server changes, e.g. “Force Check-in” Mark as Merged

Tells the system that the local resource has been locally merged with the server changes.

No Action No action performed. This is selected by default for resources with

conflicting changes, e.g. “Merge”

Change Lock Status

Can override the lock status for each resource Unlocked Exclusive Non-exclusive Keep Current

Comment View

Used for associating check-in comments with resources Allows comments to be set at any time prior to

synchronization Supports a “Summary Comment” to be applied to all

resources on synchronization Supports comments for individual resources Supports specifying comments for newly added

resources

Comparison to Standalone StarTeam Client

Incoming content change (only) “Out of Date”

Outgoing content change (only) “Modified”

Incoming addition

Outgoing deletion“Missing”

Bidirectional content change (only)

“Merge”

Outgoing addition

Incoming deletion“Not in View”

Current “Current”

Unknown “Unknown”

Status Values not Available in Standalone Client

Incoming change involving a move and/or rename

Outgoing change involving a move and/or rename

Bidirectional addition

Bidirectional deletion

Bidirectional change involving a move and/or rename

Improvements over the Standalone Client

Not-in-View Folders File/Folder moves File/Folder renames File/Folder deletion

Not-in-View Folders

Commonly requested missing feature for StarTeam client

E.g. User adds a new Java package resulting in new local directories. The StarTeam client does not show those folders, nor any of the files they may contain.

Synchronization List in eclipse will show those folders and files as an “Outgoing addition”

File/Folder Moves

With the StarTeam client a user can move an individual file from one folder to another but the change is performed immediately on the server.

No way to make multiple local moves and later update those changes on the server.

If another user moves a file to a new folder you will see the old file as “Not-in-View” and the new one as “Missing”.

If you were to delete the “Not-in-View” file you could lose your local changes.

File/Folder Renames

Similar problems as move operation. Cannot accumulate local name changes and perform a

single update on all changes at a later time. If another user renames a file you have the “Not-in-View”

/ “Missing” problem.

File/Folder Deletion

Standalone client requires a user to delete local and/or repository files in a single action.

If a user performs local-only deletion the file then the status becomes “Missing”.

If a different user deletes a file in the repository your local copy is marked “Not-in-View”.

“Not-in-View” is insufficient: could mean remotely deleted in which case the local file ought to be deleted OR it could mean local file was added and needs to be added to the repository.

Scenario: Simple Content Change

Make a local change to a file’s content and check it in Status is “Modified” and is easily handled by standalone

StarTeam client.

Scenario: Backing out a Local Change

Make local content change to a file Back out the change using “Conform to Remote”

Scenario: Merge new Changes Locally

Make local changes to a file. Another user checks in a new version of the file. Use diff tool to merge changes locally Set synchronization action to “Mark as Merged”

Scenario: Create a New Local Folder

Add a new Java package, creates one or more new local folders

Standalone StarTeam client is of no help at all. Known as the “Not-in-View” folder problem.

Scenario: Simple Name Change

Refactor a file by changing its name. In eclipse I can build, run, test without committing the

rename change to the StarTeam repository. Standalone client doesn’t handle this well: my local file is

“Not-in-View” and remote file is “Missing”. I need to remember the new and old names and change it by hand.

Scenario: Change Name and Package

Similar to previous scenario. In eclipse I can build, run, test without committing

changes. When ready I can make all changes at once. Standalone client doesn’t help. Now I need to both move

and rename files and remember names and locations.

Scenario: Someone on the Team Refactors

Someone else moves and renames files/folders. In eclipse it is easy to synchronize these changes locally. Standalone client is harder: I end up with “Missing” and

“Not-in-View” files. Which do I delete locally?

Scenario: Remote Delete

Simple refactoring: someone remotely deletes a file. In eclipse, I can tell this has happened and delete my

local copy. Standalone client the file becomes “Not-in-View”. I can’t

easily tell if that file is something I created which needs to be added or if it was deleted remotely and I need to delete it.

Scenario: We Both Add the Same File

Remote user and I add the same file name to the same folder.

In eclipse, this is shown as a conflict “Outgoing Addition, Incoming Addition”. Default action is “No action”. I’ll need to manually resolve this.

Standalone client would show the file status as “Unknown”. Tells us less information about what is going on, still need to resolve it manually.

Scenario: Delete Local File

I locally delete a file that should no longer be in the project.

Eclipse shows this as an “Outgoing deletion”, default synchronization action is to delete the remote file.

In the standalone client I can delete it in the repository at the moment I delete it from disk, or delete it locally first. In the later case the file status is “Missing”, how can I know later on that I need to delete it? I may check out by mistake.

Scenario: Remote Delete with Local Change

I’m working on a local file with changes, someone deletes file from the repository.

Eclipse shows this as a conflict: “Outgoing modification, Incoming Deletion”. Default action is “No action”, I need to resolve this manually.

Standalone client shows my local file as “Not-in-View”. Do I need to add it to the repository or delete it locally?

Even if I realize I need to delete it locally I can’t tell if I have local changes I will end up losing.

Scenario: Dependency Order

Have two similar files: Ball.java and Sphere.java and want to combine them in to one.

Move code from Sphere.java to Ball.java Delete Sphere.java Rename Ball.java to Sphere.java End up with one file Sphere.java whose history includes

Ball.java’s history. Synchronization action makes sure the content change,

delete and rename happen in the proper order.

Questions?

jim.wogulis@borland.com