Difference between revisions of "ALF/SCM Vocabulary"

Revision as of 20:33, 16 May 2006

Introduction

ALF is a web-services based framework for tools integration. In order for ALF to realize its full potential, standardized vocabularies will be needed for each class of tool. With such vocabularies, tools within a given class will be interoperable in the ALF framework. The purpose of this document is to define a standard ALF SCM vocabulary.

SCM (Software Configuration Management) refers to a class of tools providing the following services: version control of artifacts (i.e. tracking the series of revisions to each artifact), shared development of a set of artifacts (i.e. locking, branching, and merging of changes when different users attempt to make changes in parallel), and general services to support development of software by teams (e.g. user/group management, access control, support of specific development processes, etc). Some well-known examples of SCM tools are: CVS, Subversion, ClearCase, Perforce, and AccuRev, among others.

Usually the artifacts managed by SCM tools are source files, though the tools are applicable to any set of file-based artifacts (e.g., XML docs, test scripts in some testing language, HTML pages, Word documents, object files, executables, etc). At this time we are restricting ourselves to artifacts that are representable as files. Extending this vocabulary to deal with configuration management of other sorts of entities is left for the future.

The services defined by this document are both subsettable and extendable. The intent of this standard is not to force any particular SCM model on all SCM vendors, but rather, to ensure that vendors which provide a particular SCM service all do so in the same way.

The SCM ALF interface being defined here could be used as the basis of the client/server protocol for the GUI of an SCM tool itself, though that is not its primary goal. The main goal is to facilitate interaction between different classes of tools.

The outlines of the rest of this document is as follows: First a section on the general architecture that we have in mind, intended to set the stage for the detail-level concepts that follow. Then a section defining the objects in the SCM object model – for example files, elements, versions, branches, etc. One goal of this section is to agree on a standard term for each sort of object – for example we may agree to all use “change-set” even though some tools call this object a “change-package” and some call it an “activity”. More significantly, we will define what each object is operationally, and list some of the attributes of each object. Following the objects section will be a use cases section, listing the possible operations on these objects. Then a schema section, defining the XML schema for the web services we are defining. Finally a WSDL section, giving the WSDL definitions for the ALF SCM web services.

Architecture

Before getting into the detail-level concepts, we need an architectural framework.

The web services interface we are defining is a SOAP-based interface between clients and servers. Let’s begin with an architectural picture which shows these basic concepts, and also introduces the SCM notions of “workspace” and “repository” and shows where these live:

(Picture to be inserted)

The picture above shows 3 ALF-enabled tools. For example, one might be an issue-tracking tool, one might be a testing tool, and one might be a build tool. These may be running on 3 different machines shown by the 3 boxes at the top. Note these tools might have client and server components, and might be issuing SCM requests from any of their components, but from the perspective of the SCM tool these are all clients of the SCM system.

A key concept in SCM is the notion of a workspace, which is an area on the filesystem of the SCM client where the SCM system operates. For instance, if one of the clients issues an update workspace request to the SCM system, it expects the files to be materialized in the filesystem of the requester. In this regard, SCM systems differ from many of the other ALF tools. An issue tracking system is concerned mainly with accessing and updating server-side databases, and thus does not have the problem of transferring large numbers of files to/from the requesting machine.

The ALF SCM interface is concerned with transmitting the request itself - update workspace for example - and the status - update successful for example. The ALF SCM interface is not concerned with the internal details of how the request is implemented. In particular, we will not stream the actual file contents through the ALF interface, nor will we be concerned with exchanging low-level information like file-CRC's and so on. Workspace management, and moving files around, is the internal problem of the SCM system.

Objects

The concepts that follow are loosely based on JSR 147, which is a standard Java API for SCM worked out by a consortium of SCM vendors not too long ago. It might be helpful to build on their work rather than starting from scratch.

File, Directory, Filesystem

Let’s reserve these terms to refer to actual files and directories on an operating system filesystem. Files may or may not be under source control.

Element

An SCM object that is created when a file is put under source control.

Version

A SCM object representing a version of an element. Versions are typically created through “checkin” or “keep” operations. Versions have contents, which are an immutable sequence of bytes, and correspond to the file contents at the tim of the “checkin”/”keep”. Versions are linked up into a graph via predessor/successor relationships.

Change-Set (Activity)

A set of versions (i.e. changes from previous version) that logically go together, e.g. all part of the same defect fix.

Branch

Within a version graph of a single element, a branch would be a named linear sequence forming one path in the version graph. Typically many elements share the same set of named branches (in ClearCase terminology, the branches have the same branch-type), and then we speak collectively as in “latest versions on branch MAINTENANCE”.

Stream

Conceptually similar to a branch (we speak of a “stream of development”), streams also connote a particular development model. Streams form a hierarchy, and versions are promoted up through the stream hierarchy. ClearCase UCM and AccuRev (and probably others) implement a stream model.

Workspace (View, Sandbox)

Workspaces are an environment by which users can make changes to the persistent SCM objects (e.g. create new versions). A workspace corresponds to a directory tree on the filesystem, containing files that are under source control. Files in a workspace correspond to versions of elements. New versions are created by keeping/checking in files in a workspace.

Configuration

Loosely speaking, a configuration refers to the rules specifying what versions of what elements should be loaded into a workspace. In base ClearCase, this corresponds to a “config spec”, while in stream-based models such as ClearCase UCM and AccuRev, the configuration is determined strictly by the workspace’s position in the stream hierarchy.

Baseline (Snapshot)

A fixed set of versions, one per element, which can be later reconstructed.

Repository (Vob, Depot)

The persistent store housing all the SCM systems metadata.

Use Cases

Build Server Use Cases

Create a workspace(sandbox) (view)

A workspace is characterized by a place on your local filesystem where the files correlate to objects under SCM control. Workspaces are a sharing mechanism: Different users have different workspaces (views) into the same set of underlying objects.

   "mkws" – AccuRev
   "co" – CVS, SVN (creates and populates the sandbox)
   "mkview" – ClearCase

Remove a workspace(sandbox) (view)

   "rmws" – AccuRev
    nothing – CVS, SVN (just delete the files)
   "rmview" – ClearCase
   

Put a set of files under source control.

This create elements corresponding to each file, and creates an initial version of each element whose contents come from the file.

   "add" - AccuRev, CVS, SVN
   "mkelem" - ClearCase

Remove elements from source control

Could be implemented by just hiding the elements, if the SCM system doesn’t want to destroy information.

  "defunct" - AccuRev, 
  "remove" - CVS
  "delete" - SVN
  "rmelem" - ClearCase

Mark a element as being worked on, either exclusively or non-exclusively

“Exclusive” means you are preventing others from working on it at the same time. Non-exclusive may be a no-op in some systems, or it may have the effect of making the corresponding file writeable in some other systems.

  "co" – AccuRev (only needed for exclusive locking)
  "edit"  - CVS (only needed for exclusive locking)
  "lock" - SVN (only needed for exclusive locking)
  "checkout" – ClearCase (makes the file writeable, there are different switches for exclusive vs non-exclusive)

Create a new version of an element

The operation by which new versions come into existence. Takes the contents of a source file, creates a new version based on those contents, and puts the new version into the corresponding element’s version-history. Versions of an element are linked into a graph by predecessor/successor relationships.

  "keep" - AccuRev,
  "ci" - CVS, SVN
  "checkin" - ClearCase

Create a new branch (stream) to support parallel development

The general idea is that new versions are created on that branch. So for instance, a set of elements might have a maintenance branch/stream and a future-development branch/stream, each with its own sequence of versions.

   “mkstream” – AccuRev
   "tag –b" – CVS
   "copy" - SVN
   "mkbrtype"  - base ClearCase
   "mkstream" – ClearCase with UCM

Capture a baseline (snapshot)

The general idea is to capture a fixed set of versions that can be re-materialized at a later time.

    "mksnap" – AccuRev
    "tag" – CVS
    "copy" - SVN
    "mklabel" - base ClearCase
    "mkbaseline" UCM ClearCase

Materialize a set of files in a workspace

The files correspond to underlying elements in the SCM system.

   "update" – AccuRev, CVS, SVN, ClearCase (for snapshot/web views, implicit for dynamic views)

Get history of an element or set of elements

Time-ordering listing of the history of changes.

   "hist"  - Accurev
   "history" - CVS
   "log" - SVN
   "hist" - ClearCase

Compare versions of element(s)

  "diff" - AccuRev, CVS, SVN, ClearCase

Perform merges of versions, from one branch/stream to another

  "merge" – AccuRev, CVS, SVN, ClearCase

Promote versions up the stream hierarchy

Modern SCM systems define a process by which changes propagate up a hierarchy of streams. This use-case is to support such a hierarchical model.

  "promote" – AccuRev
  "deliver" – ClearCase with UCM
  

Define a change-package (activity)

This is typically to support associating a set of changes with a defect. A change-package is typically defined as a set of versions without gaps (though other definitions are possible).

Schema

This section not yet written.

WSDL

This section not yet written.

References

JSR 147: Workspace Versioning and Configuration Management: [1]

WebDav DeltaV [2]