1. 3136 - Refactoring and Synchronization with the StarTeam Plug-in for Eclipse  Jim Wogulis  Principal Architect, Borland Software Corporation

2. 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.

3. 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

4. Getting Started with the Plug-in  Download and install StarTeam Plug-in For Eclipse  http://www.borland.com/downloads/download_starteam.html 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…”

5. StarTeam Status Decoration

6. “Rollup” Status Label Decorations Current Incoming change Outgoing change Bidirectional change (both incoming and outgoing) Unknown Status

7. 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.

8. 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.

9. Status Values

10. 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”

11. Change Lock Status  Can override the lock status for each resource  Unlocked  Exclusive  Non-exclusive  Keep Current

12. 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

13. 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”

14. 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

15. Improvements over the Standalone Client  Not-in-View Folders  File/Folder moves  File/Folder renames  File/Folder deletion

16. 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”

17. 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.

18. 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.

19. 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.

20. 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.

21. Scenario: Backing out a Local Change  Make local content change to a file  Back out the change using “Conform to Remote”

22. 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”

23. 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.

24. 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.

25. 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.

26. 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?

27. 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.

28. 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.

29. 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.

30. 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.

31. 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.

32. Questions?  jim.wogulis@borland.com jim.wogulis@borland.com