| [stellation-res] WVCM Article Cited by a Rational STP doc |
I found it while reading STP-025, a Rational doc about WVCM API Test Strategy. Seems like a useful short reference, assuming it's accurate. Mark, as our resident WVCM guru, maybe you could give an opinion about it?And let us know if there are any glaring (or not-so-glaring) errors? (If there are,
we should probably communicate them to Geoff or ???, since some Rational guys may be using it as a reference of sorts...) - Jim -- Jim Wright, IBM T.J. Watson Research Center *** The Stellation project: Advanced SCM for Collaboration *** http://www.eclipse.org/stellation*** Work Email: jwright@xxxxxxxxxxxxxx ------- Personal Email: jim.wright@xxxxxxx Title: Untitled
by Benoy Jose
This article is cited as a reference by the Rational document STP-025 "STP R1.0 WVCM API Test Strategy."
It is available at http://javaboutique.internet.com/articles/versioning/
There are a ton of products in the market for versioning and configuration management. Tools like Visual source safe, PVCS, Rational Clearcase, CCC Harvest to name a few provide all that is needed to companies for versioning and configuration management. The major drawback of these products is their ability to be accessible over the Internet and their rigidity of being accessible only within the intranet. Moreover all these applications need some kind of thin client installation on the client machines which ties them to the specific machines.
In todays market when outsourcing is becoming more and more popular, work is done at different geographical locations and in different time zones. An integrated workspace and robust versioning system is of great importance. The biggest challenge of the outsourcing model is to integrate and assemble all the pieces at one place and deliver it to the customer. Often a good amount of time is spent refactoring and integrating code done elsewhere into one system and trying to get the system up and running. The main reason for this is the inconsistencies of code used by different teams which does not surface until integration is done. A distributed, over the web workspace will ease the difficulty and provide an up to date and common code base that will have minimal problems during integration and deployment.
The WVCM API (Workspace Versioning and Configuration Management API) seeks to address this issue by providing a common API that will provide basic versioning functions. The API addresses basic workspace management, version history management, baseline management, activity management and namespace versioning.
The WVCM API is designed to work specifically for versioning and for this reason it is usually run on a versioning server.
Versioning is a mechanism by which previous states of a resource can be traced and retrieved. Versioning allows multiple users to privately work on common resources and publish them when they are done. Versioning can help track changes made by individual users and can help in effectively merging those changes into a single document. It can also help to track all the previous versions of a particular resource so that they can be retrieved and used.
Lets start with some basic terms:
Several workspaces can be created to contain different versions of a set of version-controlled resources. Changes made to one resource in a workspace are not reflected automatically in the other workspaces. To achieve this synchronization a version controlled resource in one workspace should be checked in after changes are made to the resource. All the other users in the same workspace need to refresh their copy of the resource with the new copy on the server to get the changes that were made. In the same way the other workspaces also need to do a synchronization of the resource copy they have with the copy on the other workspace to reflect the changes made to resource. For proper baselining and merging (to be discussed shortly) a workspace can have only one version controlled resource for a given version history. When the doMerge method is called on a resource the user needs to identify which version controlled resource on the server needs to be chosen for the merger.
To create a new workspace a client needs to specify a location on the client machine (local machine) to point to the root folder of the workspace. After that the client needs to specify a location on the server for the checked-in controlled resource which will be shared with other workspaces. To share changes of a resource with other workspaces the client needs to first put the resource under version control. This can be done by invoking the doControl method of the WVCM API on the resource. To make changes to the resource the client needs to check the file out using the doCheckout method. When the changes are done and the client wishes to publish the changes to the server it calls the doCheckin method of the WVCM API. The changed local file is copied onto the server if no change has been made to the resource by another client while the file was checked out by the present client. If a change has been made to the resource by another client, and has been published to the server, the present client has to back up his existing copy of the resource and get the latest copy of the resource from the server. The client then needs to do a merge of the existing copy with his changes before he can make the doCheckin call again.
When the doControl request is made it creates a new version history resource. The new version history resource is assigned a new distinct and unique location on the server. It then creates a new version resource and adds it to the previously created version history resource. The content of this version resource is a copy of the initial resource on which doControl was applied. The new version resource is assigned a distinct and unique location on the server. Finally it converts the initial resource into a version-controlled resource. During the conversion it adds a CheckedIn property that will identify the new version resource.
To modify the content of a version controlled resource it must be first checked out. When the resource is checked back in, a new version is created in the version history of the version controlled resource and the version that was checked out is marked as predecessor of the new version that is checked in.
Just like resources, folders also can be versioned. When a folder is placed under version control a version history resource is created to hold the versions of the folder. A version of a folder cannot be modified. A folder version does not contain all the versions and the data of all the resources within the folder; instead it stores the information about all the version controlled resources within the folder. The folder stores the binding name and the version history resource of all the members of the folder. If any member or resource inside a version controlled folder is modified, a new version of the folder need not be created. However the binding name and the version history resource of the changed resource are stored inside the folder version resource of the folder.
A set of version controlled resources can be grouped as a configuration. A configuration will contain all the resources under the root folder except the resources that are part of another configuration. Baseline is the process of storing the state of every version controlled member of a configuration. A Baseline history contains a version history of baselines. Baselines are made by creating a version controlled resource called the version controlled configuration. A client can place a folder under baseline control by invoking the doBaselineControl method which in turn makes the folder a baseline controlled folder. All versions of resources under the folder become part of the baseline. As the number of resources in a configuration increase the size of the configuration becomes large. To make large configurations easy to manage they can be broken down into logical blocks which can be made into smaller configurations. To make these smaller configurations part of the larger configuration they can be stored as sub- baselines of the main configuration baseline.
Usually when different workspaces need to be synchronized, it makes sense to consolidate changes made in one workspace into a logical unit and then try to merge the changes with the other workspace. For this purpose a set of related activities need to be clubbed together.
An activity is one such process that allows us to select multiple versions, with the condition that all the selected versions are part of a single line of decent. A line of decent is created when a sequence of versions have a successor and predecessor relationship between them.
Traditional versioning systems do the same thing, but call them differently. When an activity is used to make a logical change it is called a change set and when it is used to capture a line of decent it is called a branch.
Usually when a milestone is reached there is a need to tag all resources together so that they are identifiable, this can be done by using a version label on a particular version in the version history. A version label identifies a single version from all the other versions in the version history. The version label can be assigned automatically by the server or can be assigned by the client to reflect a milestone. A version label can be assigned to at most one version in a given version history.