- 1 Preview
- 2 ALF background
- 3 SCM background
- 4 Objects
- 5 Use Cases
- 5.1 Create a workspace(sandbox) (view)
- 5.2 Modify a workspace(sandbox) (view)
- 5.3 Remove a workspace(sandbox) (view)
- 5.4 Put a set of files under source control.
- 5.5 Remove elements from source control
- 5.6 Mark a element as being worked on, either exclusively or non-exclusively
- 5.7 Create new versions of an element
- 5.8 Create a new stream (branch) to support parallel development
- 5.9 Capture a baseline (snapshot)
- 5.10 Materialize a set of files in a workspace
- 5.11 Get history of an element or set of elements
- 5.12 Compare versions of element(s)
- 5.13 Perform merges of versions, from one branch/stream to another
- 5.14 Promote versions up to a higher-level stream or branch
- 5.15 Define a change-package (activity)
- 6 Proof-of-concept Use Case Proposals
- 7 Schema
- 8 WSDL
- 9 References
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.
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  for detailed information about ALF.
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
(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
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”.
(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
(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.
(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
(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: 
Attributes of branches/streams:
- A name
- Parent branch or stream
- Creation time
- Other attributes tbd
(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.
(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
(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
(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
- Possibly other attributes
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
- Possibly other attributes such as an email address
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
JSR 147: Workspace Versioning and Configuration Management: 
WebDav DeltaV