CSC Proprietary and Confidential Catalyst 1 Subversion (SVN) / Subclipse Tutorial

CSC Proprietary and ConfidentialCSC Proprietary and Confidential Catalyst 1

Subversion (SVN) / Subclipse Tutorial

CSC Proprietary and Confidential Catalyst 2

Typical Client/Server System

Fundamental Concepts


The Problem to Avoid: Stepping on Each Other’s Changes



The Lock-Modify-Unlock Solution(such as check-out/check-in in VSS)

In this approach, Sallie can’t work on the file until Harry is finished and releases the lock.

Sally has to call Harry to find out when he will be finished with the file.

If Harry forgets and leaves the file locked, Sally needs to call Harry to remind him.

If Harry forgets to unlock and goes on vacation, then Sally needs to call the Administrator to intervene.



The Copy-Modify-Merge Solution(as used in Subversion)

In this approach, Harry and Sally can work on the same file at the same time and merge the changes.NOTE: A Lock command is still available for when locking is necessary (such as when doing extensive editing of a binary file like a complex graphic).



Global Revision Numbers

Revision numbers apply to the entire file system tree.

This would be revision 3 even if unchanged from revision 2



Subclipse plugin to Eclipse provides a GUI client for Subversion that is integrated with RMC

Subversion(WAN-based version

control system that is a successor to and

improvement to CVS; native command line

user interface)

Subclipse(Plugin to Eclipse that provides a graphical user

interface client for Subversion)

Eclipse(Plugin-based platform that supports

development of modeling applications)

Eclipse Process Framework Composer(Plugin to Eclipse that provides a SPEM-based

application for methodology documentation)

Rational Method Composer(Plugin to Eclipse that provides a SPEM-based

application for methodology documentation)

Central Server

Local Client

Command line interface

Graphical interface



Working Copy

Working Copy

Subversion Repository

Application(RMC)

Working copy is a ordinary directory tree with an

additional administrative subdirectory named .svn

that contains SVN metadata

To the application, the working copy looks like a

ordinary file system

Some common operations:

•Import* or Share** project•Checkout project (create working copy)•Add files to version control•Commit changes•Update working copy from repository•Status* or Synchronization view**•Resolve conflicts•Export working copy without metadata

(A more complete list of operations for Subversion and Subclipse is shown on the next two slides)

*Only in Subversion command-line interface; done differently in Subclipse graphical interface**Only in Subclipse graphical interface; done differently in Subversion command-line interface

NOTE: We will only be using the graphical user interface provided by Subclipse



svn command SVN plug-in Feature Explanationadd Team > Add to Version Control Just as with the command line, you need to

add a resource to SVN after you create it.

blame (praise, annotate, ann) SVN Annotate Viewlock Team > Lockunlock Team > Unlockcat SVN Repository Viewcheckout (co) SVN Repository View cleanup Team > Cleanupcommit (ci) Team > Commitcopy (cp) Team > Branch/Tag, Team > Copydelete (del, remove, rm) Refactoring support, SVN Repository View When you remove a file, the SVN plug-in

refactoring hook ensures that the resource is scheduled for deletion within SVN. Also, in the Repository view, you can delete resources directly, without having them checked out.

diff (di) Compare menu, and Team > Generate Patch.export Team > Export import Team > Share..., Importing a project This doesn't work quite like with the

command line, as you cannot perform the import operation in one single revision; rather the import is performed by creating the existing Eclipse project in a SVN repository and then scheduling all the project contents for addition.

info SVN Properties Page, Properties, SVN Repository View

The information is found on the resource's property page (right click on a controlled resource inside a project), and also from the repository view.

list (ls) SVN Repository View Not all details are shown.log History View

Subversion command line interfaceSubclipse plugin graphical

interface


svn command SVN plug-in Feature Explanationmerge Mergemkdir SVN Repository View From a repository node, you can right-click

and choose New > New Remote Foldermove (mv, rename, ren) SVN Repository view Support for moving and renaming have been

integrated directly into the Eclipse workbench and refactoring operations. You can also move and rename resources directly in the Repository view without having them checked out.

propdel, propedit, propget, proplist, propset SVN Properties ViewTeam > Add to svn:ignoreTeam > Set Property.

resolved Team > Mark Resolved Use this after you resolve merge conflictsrevert Team > Revert This also works if you select several

resources. But be careful, as it will work recursively on folders.

status (stat, st) Team Synchronizing Perspective File status is also shown as an icon overlay (decorator) and text annotation.

switch (sw) Team > Switch A switch cannot happen above the project level, since that would be outside of the Eclipse workspace.

sw --relocate Relocate, SVN Repository View This option is enabled in the SVN Repository view. Right-click on a repository location to relocate the URL and update the attached projects in your workspace.

update (up) Team > UpdateConsole output SVN Console The output from the SVN commands (or the

JNI calls) are displayed here.

Subversion command line interfaceSubclipse plugin graphical

interface


Connect to a New Repository Location

• Connect to the Subversion repository location already created on the server (which is currently http://20.137.188.153/RMC)

Basic Operations


Import (Share) a Project into the Repository

• In the Resource Navigator view of the Authoring perspective, right click the project you want to import and select Team > Share Project… from the context menu

Select SVN and reference the correct repository location and folder name. The folder name will be “CSC Practices Library” for workspace library projects and

“Standalone Method Libraries” for standalone library projects.

Need naming convention for project names

Basic Operations


Another view

• In Library view, right click on plug-in and select “Show in Resource Navigator” then select “Team” then “Share Project…”


This is an example where the workspace project is being added to the CSC Practices Library


Subversion repository structure

• There are two* CSC sections to the repository:– CSC Practices Library – where each plug-in and configuration is treated as an

SVN project. This is the workspace library approach, which is scalable and supports sharing across the enterprise.

– Standalone Method Libraries – where each library is treated as an SVN project. This is the default standalone library approach, which is not scalable, because content cannot be shared across different libraries.

• We will continue to have both types of libraries, but we should emphasize the first approach

• *There is also a third section, the IBM Practices Library, which includes EPF and IBM content used for reference and extension but not directly edited


Check Out a Project (1)

• Checkout copies a project from a repository into your local workspace. It creates a working copy

A working copy is a specially formatted folder structure which contains additional .svn folders that store SVN information, as well as a pristine

copy of each item that is checked out.

Basic Operations


Check Out a Project (2) If an Eclipse .project file already exists in the selected repository folder, the check out wizard will automatically default the method of checkout and use the project definition file.

If no project file exists in the selected repository location, the wizard will give you the option of checking out the folder as a regular Eclipse project or launching the New Project Wizard.

Basic Operations


Check Out a Project (3)

• The next step allows you to identify where the working copy should be created. • The default option is to create the working copy in your Eclipse workspace. • To select an alternative location, uncheck the use default workspace location option and

type or Browse for a new target location.

Basic Operations


Typical Work Cycle

• Edit your working copy– Library view decorations indicate status

• Yellow cylinder: untouched files (working copy is same as in the repository)• Asterisk: edited files (working copy differs from repository version)• Plus: new files (added to source control)• Minus: deleted files• Question mark: files in working copy not (yet) under source control

– “Add to source control” any new files or folders

– If exclusive access is needed (unusual), you may Lock the file

• Update your working copy with other people’s committed changes (“Update”)– SVN will attempt to merge any changes to the same file

– Any conflicts will be identified

• Resolve any conflicts and mark as resolved• Commit your changes to the repository (“Commit”)

Basic Operations


Team Synchronizing Perspective

• Team synchronization is a cross-resource, three-way* merge in which you may consider all changes at once and filter the information as needed before performing any updates or commits, with your existing working copy being the focal point – Your own local changes are called outgoing and the changes that have

happened in the repository since your last update are called incoming

– In the synchronization perspective, both incoming and outgoing changes are analyzed before they are synchronized; that is:• for incoming changes, synchronization means that your working copy is updated• for outgoing changes, synchronization means that your changes are committed.

• Launching the Team Synchronization Perspective does not update or change the status of local or repository resources automatically

*compares the original version, your changes, and others’ changes for all resources in the working copy

Basic Operations


Synchronize View

Synchronize view icon decorations (summary):• Blue arrow pointing left – outgoing changes• Gray arrow pointing right – incoming changes• Red double-headed arrow – conflicting changes• No plus or minus sign – revision• Plus sign – addition • Minus sign – deletion

Basic Operations


Synchronize View Icon Decorations (Detail)

An incoming addition means that a resource has been added to the repository. Updating will transfer the resource to your workspace.

An incoming change means that the file has changed in the repository. Updating will transfer the new file revision to your workspace.

An incoming deletion means that a resource was deleted from the server. Updating will delete your local resource.

An outgoing addition means that the file was added to your workspace and is not yet in the repository. Adding then Committing will transfer the new file to the repository.

An outgoing change means that the file was change locally. Committing the file will transfer the changes to the repository and create a new revision of the file.

An outgoing deletion is a resource that has been deleted locally. Committing these resources will cause the remote resource to be deleted.

A conflicting additions means that the resource has been added locally and remotely.

A conflicting change means that the file has been changed locally and remotely. A manual or automatic merge will be required. Also, any entries in the view that contain children that are conflicts will also be decorated with the conflict icon. This is done to make conflicts easy to find.

A conflicting deletion means that the resource was deleted locally and remotely.

Basic Operations


Ideal Work Flow

• Start fresh. Before starting work, update the resources in the workspace with the current state. If you are sure that you have no local work that you care about, the fastest way to get caught up is to select the projects you are interested in and select Checkout (or Replace with > Latest from Repository if the projects already exist locally). This will overwrite your local resources with those from the repository.

• Make changes. Work locally in RMC, creating new resources, modifying existing ones, saving locally as you go.

• Synchronize. When you are ready to commit your work, synchronize with the repository to identify differences.

• Update. Examine incoming changes and add them to your local working copy. This allows you to determine if there are changes which might affect the integrity of what you are about to commit. Resolve conflicts. Test again and run integrity checkers (such as checking for broken hypertext links).

• Commit. Now that you are confident that your changes are well integrated with the latest branch contents, commit your changes to the repository. To be prudent, you may repeat the previous step if there are new incoming changes.

Basic Operations


Resolving Conflicts Using the Compare Editor

– Supports a three-way comparison of inbound and outbound changes versus a common ancestor

– Allows you to review the inbound and outbound changes in a resource in addition to the lines that are in conflict

– Provides features that allow you to selectively merge the differences between the file variants

The best practice is to coordinate the work to minimize conflicts.

Core plugins are most likely place for conflicts, because of sharing and reuse. Practice plugins are the next most likely.

Element names, brief descriptions, and relationships are maintained in same plugin.xmi file and are a source of potential conflicts.

Basic Operations


Other Functions(See Help for more information)

• Create and apply patches (share changes outside SVN)• Show history (of any folder or resource)• Show annotation• Set property and show properties• Add to svn:ignore (i.e., don’t mark unversioned file with a question mark)• Branch (parallel work on different releases; mainline vs. bug fix)• Tag (label a release version) • Switch• Configure branches/tags• Copy• Revert (return to an earlier revision)• Cleanup (complete interrupted operations)• Disconnect (remove local project from SVN)


Troubleshooting Synchronization Problems

• Don’t use “quick fix” -- research and fix the problem• The most frequent causes of synchronization problems

– Failure to check in: Someone created a new plug-in and referenced it from an existing plug-in but didn’t check in the new plug-in to the SVN repository. You updated your version of the referencing plug-in in your workspace, but the referenced plug-in is missing from the repository and thus from your workspace

– Failure to check out: Someone created a new plug-in and referenced it from an existing plug-in and checked the new plug-in to the SVN repository. You updated your version of the referencing plug-in, but you didn’t know to check out the new referenced plug-in, so it is missing from your workspace

• Less frequent– Name change: The name of the plug-in was changed in the repository and you

are linked [brackets in resource navigator view] to an old name.

– Path change: The plug-in was checked into the wrong location and then moved and you are linked to the resource in the old path.


Troubleshooting Configuration Problems

• Don’t use “quick fix” – research and fix the problem• Frequent causes of configuration problems

– Publish, process, practice, or core plug-in referenced by the configuration specification is missing from the workspace

– Publish, process, practice, or core plug-in needed is in the workspace but missing from the configuration specification• Core plug-in referenced by practice, process, or publish plug-in is missing from the

configuration specification• Practice plug-in referenced by process or publish plug-in is missing from the

configuration specification• Process, practice, or core plug-in referenced by the publish plug-in is missing from the

configuration specification• Publish plug-in is missing from the configuration specification


What If Disaster Strikes

• Subversion is designed to survive network crashes, system crashes, and other such processing interruptions

• The entire revision to the tree is treated as an atomic transaction: either it all goes or none of it does

• This is important because a single change in RMC can affect multiple files, and these files must be kept in sync

• The transaction is journaled and committed only after the entire transaction has been processed

• If the transaction is interrupted, the Cleanup command will complete any unprocessed parts of the transaction when processing resumes

• A pristine copy of each resource file is maintained as part of the working copy of the project

• Worse case, you can revert to an earlier version of a resource


Documents

CSC Proprietary and Confidential Catalyst 1 Subversion (SVN) / Subclipse Tutorial