ALF/SCM Vocabulary

ALF Wiki Home

Preview

The purpose of this document is to define a standard ALF SCM vocabulary.

This document is organized as follows: First a couple of definitional sections, for anyone who didn't understand what the first sentence of this section meant. One will define what ALF is (ALF background), and the other will define what SCM is (SCM background). These sections 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.

ALF background

The fundamental idea of ALF is for software-development tools to provide callable interfaces and use a common callback mechanism allowing them to be coordinated by an external agent. This will diminish or eliminate the need for tools to implement point-to-point integrations. To particpate in ALF, a tool should provide a set of services exposed as SOAP based web services and may raise events to an ALF event manager to signal significant changes that may be of interest outside the tool itself in the context of an application lifecycle. In ALF the direct client or such a tools is a BPEL service flow which runs when an ALF event is raised and is used to call one or more tools via their service interface to take some action and.or update their state.

Here's an example service flow expressed in English: (User promotes changes to a SCM repository) => (SCM system updates build-workspace) => (Build tool performs build) => (Test tool runs regression tests against built executables) => (Issue-tracking tool is updated with any new problems found)

The primary intent of ALF Vocabularies is to make the creation of the BPEL services flows easier by creating common definitions. This allows the service flows to be expressed in a way that is independent of what particular tool is providing each service. At their most basic level ALF Vocabularies may define simple datatypes in the form of names and value ranges that express particular concepts. At their boldest, ALF Vocabularies may define a system of interfaces expressing operations on objects of those datatypes, that are intended to be implemented by all tools providing the described function.

Please see the ALF Architecture pages at [1] for detailed information about ALF.

SCM background

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, because that's all that currently-available SCM systems (such as the ones mentioned above) support.

Typically an SCM system includes a repository, which is a database containing all the versioned files the SCM system is managing, together with the metadata keeping track of the relationships between these versioned files and other SCM-specific concepts. For instance, if I create versions 1, 2, and 3 of a source file foo.c on some branch B, then the repository would typically contain the actual files contents of all three versions of foo.c, and would also contain metadata capturing the fact that version 1 was the predecessor of version 2, version 2 was the predecessor of version 3, and also defining branch B. (Note: A SCM implementors use of the word metadata may be a bit different than the normal usage: usually we think of data as being the actual contents of the files being managed, while the metadata is everything else in the SCM repository). The SCM repository is not accessed directly by an end user; instead there is an SCM server handling requests against the repository.

Another important SCM concept is that of a workspace. This is an area on the filesystem of the SCM client where files are materialized and operated on. For instance, if one of the clients issues an update workspace request to the SCM system, it expects a version of each of the managed files to be materialized locally in the filesystem. In the above example, the client might get version 3 of foo.c. If the client then edits files and does a checkin (or commit, or keep, depending on SCM system) operation, that may cause a new version 4 of foo.c to get uploaded to the server and saved in the repository.

We see from the above discussion that an SCM system has client and server components which must talk to one another. The client(s) run "where the files live", while the server runs "where the repository lives".

Thus one aspect of the SCM vocabulary is defining the core SCM concepts so that queries to the SCM server about what's in the SCM repository can have a common base. We will then be able to formulate requests that talk about SCM objects such as versions, elements, branches, and so on, and have those requests have meaning across SCM systems.

The fact that SCM systems operate on files in workspaces presents some challenges. A typical SCM client will utilize a client side API provided by the SCM but running on the client to "pull" files to the client's local file system (or "push" modified files back to the SCM repository). The client's security context is used to access the local file system. An ALF service flow cannot act as a normal SCM client. Since it it can only call web services, it has no way to run a client side API. Thus if it were to "pull" or "push" files directly, the implication would be that the file content would be streamed through the BPEL engine. This is undesirable from both a performance and scalability standpoint. Further, logically, a service flow will have no interested in operating directly on the files materialized from the SCM repository. Instead, other tools will operate on those files under the instruction of the ALF service flow. Since these tools may reside on different servers and have very different implementations there is no guarantee that these tools can or will run in the same security context or share the same file space. Thus, contrary to the main thrust of ALF, there is a need for tools to interact directly with a workspace provider of some sort either as a shared resource where the period of access is managed by one of more ALF service flows and passed between tools or as a private resource where the period of access may be initiated by an ALF service flow but is managed exclusively by the tool.

The implication of this is that ALF SCM vocabulary should provide a common defintion of a Workspace provider that tools can target. Requests involving workspaces (e.g. update workspace) should go to the Workspace provider rather than to the SCM server. SCM vendors will likely implement their Workspace provider by wrapping their existing client-side software. ALF may also provide an example implementation of a such a Workspace provider. This could be utilized by SCM tools if they were not immediately able to provide their own implementation.

(Picture to be inserted) File:Architecture2.jpg

Objects

Workspace

(CVS: Sandbox, ClearCase: View, AccuRev: Workspace, Version Manager: Local Workspace, Dimensions: Work Area)

A workspace corresponds to an area on the filesystem of a client machine where the SCM user will work on the files that are under version control. Users can create workspaces, and load them with files that are copies of the shared artifacts (elements) that are under source control. The workspace's configuration determines what versions of each element is obtained. Users can edit the files in the workspace, and create new versions, and promote those versions back to the underlying repository so that other users of the SCM system can access them.

Workspaces have the following attributes:

• a client machine hosting the workspace
• a workspace root directory
• a unique name within the SCM system
• a configuration (rules saying what version of each element is to be loaded into the workspace. This might be as simple as a “parent stream”, or might be a more complex “config spec” style of rules)
• an owner (typically whoever created the workspace)
• possibly, permissions (who gets to read or write the workspace)
• possibly, a set of load rules characterizing what files are to be loaded into the workspace
• possibly other attributes

Files, Directory

These are operating system concepts, but since an SCM system operates on them, they need to be part of the SCM vocabulary also.

A file has the following attributes:

• a base filename
• a parent directory
• contents (a stream of bytes)
• a modification time-stamp
• an owner
• possibly, some permissions
• possibly other attributes

A directory can be thought of as a special kind of file with no contents. A root directory (in the filesystem) is a special kind of directory with no parent. We speak of the children of a directory as the set of all files and directories having the given directory as a parent. We define the pathname of a file as the series of basenames from the root to given file, separated by ‘/’ or ‘\’, e.g.: “/home/fred/workspace/dir/some_file”.

Only files that live under the root directory of a workspace are subject to version control. Within a workspace, any given file may or may not be under version control. If a file is under version control, it is associated with an element (see next section).

For a file in a workspace, we speak of its workspace-relative-path as the relative path from the root of the workspace to the file. E.g. in a workspace rooted at “/home/fred/workspace”, the file “/home/fred/workspace/dir/some_file” has workspace-relative path of “dir/some_file”.

Element

(CVS: File [CVS fails to distinguish between "file" and "element"], ClearCase: Element, AccuRev: Element, Version Manager: Versioned File and Archive, Dimensions: Item)

An element is an SCM object that is created when a file or directory in a workspace is put under source control.

Elements have the following attributes:

• an element ID (some SCM-system-specific internal identifier of the element, typically a number)
• an element-type (e.g., directory, text file, binary file, possibly other values)
• a set of versions (see next item)
• an owner
• a creation-time
• possibly, a creation comment
• possibly, permission bits

Version

(CVS: Version, ClearCase: Version, AccuRev: Version, Version Manager: Revision, Dimensions: Item Revision)

A version is an SCM object representing the contents of some version-controlled file at a particular moment. The initial version of a given element is created at the time the element is created, and captures the contents of the file when it was put under version control. Subsequent versions are created by “checkin” (or “keep”) operations on version-controlled files. This operation creates a new version and puts it into the version-set of the element corresponding to the checked-in file.

Versions have the following attributes:

• contents (a series of bytes)
• an element they are associated with
• some sort of version-id (name or number)
• a set of predecessors/successor versions
• an owner
• a creation-time
• possibly, a creation comment
• possibly other attributes

Note the contents of any given version are immutable. New versions of the element can be created, but past versions content do not change.

If we ignore branching for the moment (we’ll deal with that two sections from here), then without branching each version has a single predecessor and a single successor, and thus the versions form a linear graph:

(picture to be inserted)

Each “checkin”/”keep” creates a new one of these version objects and links it into the graph.

Change-Set

(CVS: [none], UCM ClearCase: Activity, AccuRev: Change-Package, Version Manager: [none], Dimensions: Request)

A set of versions (i.e. changes from previous version) that logically go together. Possible uses of change-sets are: (a) Associate them with an issue in an issue-tracking system, (b) Treat them as a unit, e.g. commit them together, revert them together, merge them as a unit (e.g. for merging the same fix into multiple branches).

The versions in a change-set need not have been created at the same time, though some SCM systems might limit the notion of change-set to versions checked-in/committed in one transaction. The versions in a change-set logically need not be contiguous (e.g. versions 3 and 5 of a given element might be part of a single bug-fix, but not version 4), although many systems restrict change-sets to contiguous versions for implementation reasons.

Change-sets have the following attributes:

• an id (possibly a name or a number)
• a set of versions in the change-set
• an owner
• possibly, a comment
• possibly, an identification of an issue in some issue-tracking system
• possibly other attributes

Branch/Stream

(CVS: Branch, Base ClearCase: Branch, UCM ClearCase: Stream, AccuRev: Stream, Version Manager: Workspace and Promotion, Dimensions: Branch)

In the context of a single element’s version graph, a branch is a named linear sub-graph, for example here we have versions 0, 1, 2, and 3 in branch MAIN, and versions 0 and 1 in branch B (which spouted off of MAIN/1).

(picture to be inserted)

Normally, we speak of a “branch” in the collective sense. For example, if a set of elements all have version graphs of the same general shape as the above, we can speak of “latest on branch B” as meaning the latest version of each element along the “B” branch of the graph. The user who is “working on a branch B” is creating new versions on the branch B subgraph.

Merging means the act of merging together the changes that were made on a branch back into a single version in another branch, for example as selected by the red merge arrow in the following:

(picture to be inserted)

A stream is conceptually similar to a branch, but the streaming model adds some structure and applies some constraints as follows:

• Streams form a hierarchy (every stream has a parent)
• Merges go up the stream hierarchy, and are generally referred to as “deliver” or “promote” operations. The general idea is that you promote your work to the parent stream.
• Workspaces live at the leaves of the stream hierarchy, and the contents of the workspace are determined by its position in the stream hierarchy.

The following whitepaper explains the difference between the stream model and the branching model in more detail: [2]

Attributes of branches/streams:

• A name
• Parent branch or stream
• Owner
• Creation time
• Other attributes tbd

Configuration

(Base ClearCase: Config Spec, Dimensions: Baseline Template)

Loosely speaking, a configuration refers to the rules specifying what versions of what elements should be loaded into a workspace. The rules may be explicit, as in a ClearCase config spec. Or they may be implicit, e.g. determined by where the workspace lives in the stream hierarchy. Typically the configuration is expressed in terms of branches or streams, e.g. "load the latest version of each element on branch B". Alternatively one can use a baseline as a configuration (see next item). Note a configuration is merely a set of rules, and therefore does not refer to any fixed set of versions.

Baseline

(CVS: Tag, Base ClearCase: Label, UCM ClearCase: Baseline, AccuRev: Snapshot, Version Manager: Label, Dimensions: Baseline)

Despite the variety of names for this concept, it is fundamental to SCM. The motivation is to be able to re-create a fixed set of files, e.g. corresponding to the release of a product. A baseline is therefore a fixed set of versions, one version per element in a component. A baseline can be thought of as a "slice" through the element set capturing their states at a moment in time. The baseline can then be loaded into a workspace when you want to re-create the state it captured.

Although baseline has a similar definition as change-set (in terms of a set of versions), they have different intent. A change-set is intended merely to capture one logical change, and thus typically has a small number of versions in it (e.g. "foo.c version 5 and fum.c version 7" may be my change-set for a given fix). Whereas a baseline is intended as a slice through all the elements in a component, and thus has a large number of versions in it.

Attributes of baselines:

• A name
• A creation time-stamp
• An owner
• A list of versions
• Possibly other attributes

Component

(CVS: [none], UCM ClearCase: Component, Dimensions: Design Part)

Conceptually, a component is a set of the elements that logically go together. For example, a SCM user developing a client/server app might have a “client” component with the source files to his client, and a “server” component with the source files to the server. Possible things people might want to do with components: (a) Load only the sources that go with a particular component into a workspace. (b) Use different configuration rules for different components

Note that the set of elements in a component might vary over time.

One possible way to define components is through the directory structure. "everything under directory gui/..." might be a definition of a component. One could then embellish that with include/exclude rules (e.g. "everything under directory gui/... except gui/doc/...").

Attributes of components are:

• A name
• Its definition (e.g., a set of include/exclude rules)
• A creation time
• An owner
• Possibly other attributes

Repository

(CVS: Repository, ClearCase: VOB [stands for "versioned object base"], AccuRev: Depot, Version Manager: PDB [stands for "Project Database"], Dimensions: Base Database, Product)

The persistent store housing the SCM data and metadata. The SCM system may divide its data into multiple repositories, or store it all in one repository.

Attributes of repositories:

• A host machine
• A storage area, or specification of where it lives in a database
• An owner
• Permissions
• Possibly other attributes

User

A person or device that is authorized to retrieve sources from the SCM system or commit changes to the SCM system.

Attributes of users:

• A name
• A password
• Permissions
• Possibly other attributes such as an email address

Use Cases

Build Server Use Cases

Build Service Flow Example

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

   Possible methods, datatypes, etc.
   CreateWorkspace(
       String		workspaceName,  // the name of the new workspace 
       Repository 	repository, 	// SCM repository
       FileSelection   loadRules,      // determines what files are loaded into the workspace
       Configuration   configSpec,     // configuration determines what versions are selected
       String 		clientHostName,	// machine name where the workspace resides
       String 		workspaceRootPath // file path of the root of the workspace
   )
   Description:
       Creates a new workspace with the specified name at the specified location. 
       The load rules specify which elements are to be loaded into the workspace when an update is done. 
       The default is all elements. The Configuration defines what versions of each file are selected 
       by the workspace, i.e. what versions will be loaded upon 'update'. The simplest example of a  
      configuration would be a single stream, specifying to load the latest versions in that
      stream.     
   Events fired and who might consume:
       “New Workspace” – unsure
   Questions/thoughts:
       Is repository tool specific or ALF abstraction?  Perhaps both are in Repository.
       Unsure how this interacts with, for example, UpdateWorkspace().

Modify a workspace(sandbox) (view)

This is used to modify the attributes of an existing workspace. For example, its load-rules, configuration, or location.

   "chws" – AccuRev
   "chview" – ClearCase

   Possible methods, datatypes, etc.
   ModifyWorkspace(
       String		workspaceName,  // the name of the existing workspace 
       Repository 	repository, 	// SCM repository the workspace is associated with
       FileSelection   loadRules,      // new load rules
       Configuration   configSpec,     // new config spec
       String 		clientHostName,	// new client machine location
       String 		workspaceRootPath // new file path location
   )
   Description:
       Modifies an existing workspace, changing its load rules, config spec, client host, or root
       location according to the specified arguments. Pass only the arguments you are changing
       (null if not changing that attribute).
   Events fired and who might consume:
       “Changed Workspace” – unsure
   Questions/thoughts:

Remove a workspace(sandbox) (view)

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

   Possible methods, datatypes, etc.
   RemoveWorkspace(
       Repository  	repository,	//  
       Workspace 	workspace, 	// the workspace to remove 
       OtherOptions	otherOptions	// tool specific options
   )
   Events fired and who might consume:

   Questions/thoughts:

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
   "addfiles" - Version Manager

   Possible methods, datatypes, etc.
   AddAssets(
       Repository  	repository,	//  
       Workspace 	workspace, 	// the workspace from which the files/folders are being added
       Stream		stream,		// the stream/branch to which the assets will be added
       FileSelection    selection,	// specific files to be added; and/or wildcard filtering
       OtherOptions	otherOptions	// tool specific options
   )
   Events fired and who might consume:
       “Stream Changed” – build service provider may want to initiate continuous integration builds
                          when “enough” change sets have occurred

   Questions/thoughts:

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
  "delete" - Version Manager

   Possible methods, datatypes, etc.
   RemoveAssets(
       Repository  	repository,	//  
       Stream		stream,		// the stream/branch in which the assets live
       FileSelection   selection,	// specific files to be removed
       OtherOptions	otherOptions	// tool specific options
   )
   Events fired and who might consume:
       “Stream Changed” – build service provider may want to initiate continuous integration builds
                          when changes occur on a stream.  In general changes to streams may be monitored.

   Questions/thoughts:

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)
  "get -l" - Version Manager (only needed for exclusive locking; Rich clients auto-merge on check-in)

Possible methods, datatypes, etc.

   IntentToModify(
       Repository 	repository,     // SCM repository in which you are working
       Workspace       workspace,      // Workspace which has the elements to lock (the stream is derived from this)
       FileSelection   elements,       // Set of elements to be locked
       IntentType      intentType,     // OPTIMISTIC
                                       //    The user is communicating intent to work on this asset; others may 
                                       //    also work on it, but will have knowledge of this intent.
                                       // PESSIMISTIC - exclusive lock - recommend no one else works on this asset (to avoid merge)
                                       //    The SCM system would typically use an exclusive lock to indicate this, and prevent
                                       //    other users from AddNewVersion until the locker check's in.
       String          reason          // Optional reason description, explains the intent of the user
   )
   Events fired and who might consume:
   Questions/thoughts:

Create new versions 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
  "put" - Version Manager

Possible methods, datatypes, etc.

   CreateNewVersions(
       Repository 	repository,     // SCM repository in which you are working
       Workspace       workspace,      // Workspace from which new versions are being created
       Stream          stream,         // Stream in which you are creating new versions
       FileSelection   elements,       // Set of elements you are creating new versions of
       OtherOptions    options         // TBS
   )
   Description:
     Say you've edited files a, b, and c in your workspace, and you want to create new versions 
     of those 3 files based on their new contents. In that case, CreateNewVersion would be called,
     specifying the workspace in which the edited files a, b, and c reside, and specifying 
     the 3 files in the FileSelection argument. The stream is optional; if unspecified the 
     new versions are created on whatever branch the workspace's configuration specifies for the elements.
   Events fired and who might consume:
       “Stream Changed” – 
       “New Versions” – unsure
   Questions/thoughts:

Create a new stream (branch) 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

   Possible methods, datatypes, etc.
   CreateStream(
       String		streamName,     // the name of the new stream 
       Stream  	parent,    	// parent stream or branch  
       TimeSpec        basisTime       // basis time (default: now)
   )
   Description:
        Create a new branch or a new stream. The parent is the branch
        or stream that this branch/stream sprouts from.
   Example:
        Suppose initially there is a single stream "main", and each element has a straight-line version
        graph with a series of versions that we'll call main/1, main/2, main/3, etc. Now suppose you do
        CreateStream to create a stream "b" whose parent is "main", and suppose you associate a workspace
        with the branch "b" (through its config spec). Now, new versions created in that workspace will
        be on branch "b", so each element has a fork in its version graph:
             main/1
               |
             main/2
               |   \
               |    \
             main/3  \
               |    main/b/1
               |      |
                  ...
        The point at which the fork occurs (main/2 in the above picture) is a point in time depending
        on when CreateStream was called, or on the basisTime argument if one was given.

        Other streams can use "b" as their parent, so the substream hierarchy can become nested.
            
   Events fired and who might consume:
       “New Stream” – unsure
   Questions/thoughts:

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
    "label" - Version Manager

   Possible methods, datatypes, etc.
   CreateBaseline(
       String		baselineName,	// the name of the new baseline
       Repository 	repository, 
       Stream 	        stream,		// stream/branch or baseline+changesets? or arbitrary selection?
       Configuration 	configuration,	// appropriate filtering
       otherOptions	OtherOptions	// tool specific options
   )
   Events fired and who might consume:
       “New Baseline” – unsure

   Questions/thoughts:
       Consider how to request creation of a baseline from another baseline plus a list of change sets.

       Consider how to request creation of a baseline from an arbitrary list of assets.  (Is this 
       an important ALF case?)

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 -u" - Version Manager

   Possible methods, datatypes, etc.
   UpdateWorkset(
       Repository      repository,     // 
       Workspace       workspace,      // 
       Baseline        baseline,       // if materializing from an existing baseline
       Stream          stream,         // if materializing from a stream/branch
       Configuration   configuration,  // provides filtering
       Options         options,        // standard options such as refresh, replace, etc.
       OtherOptions    otherOptions    // tool specific options
   )
   Events fired and who might consume:
       “Workspace Update Started” - unsure
       “Workspace Update Completed" - unsure

   Questions/thoughts:
       We may want to "normalize" the Baseline / Stream concepts into a SelectionSet.
 
       Is configuration the right filtering mechanism?

       Should there be an option to create the workspace and return it?  The thinking here would
       be that it's a SCM Service Provider managed workset, created by the versioning tool, handed
       to the build tool, etc.

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
   "pcli vlog" - Version Manager

Compare versions of element(s)

This compares different versions of an element, or a set of elements.

  "diff" - AccuRev, CVS, SVN, ClearCase 
  "vdiff" - Version Manager
 
   Possible methods, datatypes, etc.
   CompareAssets(
       Repository  	repository,	//  
       Stream		stream1,	// stream specifying first version 
       Stream		stream2,	// stream specifying second version
       Version         version1,       // first version being compared
       Version         version2,       // second version being compared
       FileSelection   selection,	// specifies elements to be compared
       OtherOptions	otherOptions	// tool specific options
   )
   Events fired and who might consume:
      
   Questions/thoughts:

The caller should specify either a 'stream1' (meaning latest version in that stream), or 'version1' (meaning that specific version), but not both. Similarly, the caller should specify either a 'stream2' (meaning latest version in that stream), or 'version2' (meaning that specific version), but not both. For example, to see all differences between stream S1 and S2, specify "*" as the file selection, specify S1 as stream1, and S2 as stream2. Another example: To see the difference between version B/1 and version B/2 of a specific element "foo.c", specify "foo.c" as the file selection, specify "B/1" as the first version, and specify "B/2" as the second version.

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

  "merge" – AccuRev, CVS, SVN, ClearCase

Promote versions up to a higher-level stream or branch

New versions are created by the CreateNewVersion service, which takes files in a workspace and turns them into versions in a stream or branch. These versions can later be promoted up the stream hierarchy. For example, if a team is working in the EXPERIMENTAL_NEW_FEATURE branch, they are creating new versions in that branch (visible to each other - anyone working in that branch). When the team's new feature is ready, they will promote all the versions in the EXPERIMENTAL_NEW_FEATURE up to its parent (say, MAIN), thus exposing their feature to others.

  "promote" – AccuRev
  "deliver" – ClearCase with UCM
  "PromoteGroup" - Version Manager

   Possible methods, datatypes, etc.
   Promote(
       Repository      repository,  // SCM repository the streams are in
       Stream		fromStream,  // stream you're promoting from
       Stream 	        toStream,    // stream you're promoting to (default: parent stream)
       FileSelection   whichElements // which elements you're promoted (default: all that changed)
           )
   Events fired and who might consume:
       “Promotion” – might be consumed by a build-on-demand service flow
   Questions/thoughts:
       Perhaps whichElements should be "ElementSelection" rather than "FileSelection", to avoid
       confusing these two similar-but-distinct concepts. FileSelection would refer to a set of
       files in a workspace, while element selection would refer to a set of elements in a stream
       (not necessarily materialized on disk). Both might be specifiable by a list of paths, but
       they are conceptually distinct.

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

Proof-of-concept Use Case Proposals

POCUseCases

Schema

Schema

WSDL

WSDL

References

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

WebDav DeltaV [4]