[alf-dev] Fw: preliminary thoughts on SCM concepts and use cases

[Mark Phippard <markp@xxxxxxxxxxxxxxx>]

At today's conference call, several attendees mentioned wanting to see a 
copy of Richard Title's initial document on the SCM Vocabulary.  The plan 
was/is to post it to the ALF Wiki so that we can collaboratively edit it 
in an easier manner.  It has not been added to the Wiki yet as Tim Buss 
had the day off.

Since I was the only one on the conference call that had a copy, I 
volunteered to post to the mailing list as requested.  Here it is:


I’m glad we’re getting together an SCM-specific discussion – thanks Tim 
for organizing this.
Obviously some standard vocabulary will be essential for meeting ALF’s 
interoperability goals.
I see SCM as a challenging area because there are a number of vendors with 
different models.
 
Below are some thoughts toward the first 2 sections of your proposed 
document (concepts, and use cases). 
I’ll leave Schema and WSDL to those with more expertise in those areas.
 
The concepts that follow are loosely based on JSR 147, which is a standard 
Java API for SCM
 (http://www.jcp.org/en/jsr/detail?id=147 ) worked out by a consortium of 
SCM vendors not too long ago.
I thought it might be helpful to build on their work rather than starting 
from scratch.
 
For use cases, I drew from an earlier “SCM use cases” document that I sent 
out to the alf-dev mailing list a while ago.
 
Richard Title
AccuRev
 
Concepts (Objects)
 
1. 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.
 
2. Element 
 
    An SCM object that is created when a file is put under source control.
 
3. 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.
 
4. 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.
 
5. 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”.
 
6. 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.
 
7. 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.
 
8. 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.
 
9. Baseline (Snapshot)
 
    A fixed set of versions, one per element, which can be later 
reconstructed.
 
10. Repository (Vob, Depot)
 
    The persistent store housing all the SCM systems metadata.
 
 
SCM Use Cases (Operations)
 
 
1. 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 (creates and populates the sandbox)
    “mkview” – ClearCase
 
2. Remove a workspace(sandbox) (view) 
 
    Undoes #1
 
    “rmws” – AccuRev
     nothing – CVS (just delete the files)
    “rmview” – ClearCase
 
3. 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
     "mkelem" - ClearCase
 
4. Remove elements from source control 
 
    Undoes #3. Could be implemented by just hiding the elements, if the 
SCM system doesn’t want to destroy information.
 
   "defunct" - AccuRev, 
    "remove" - CVS
    "rmelem" - ClearCase
 
5. 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)
    "checkout" – ClearCase (makes the file writeable, there are different 
switches for exclusive vs non-exclusive)
 
 6. 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,
   "checkin" - ClearCase
 
7. 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
    “mkbrtype”  - base ClearCase
    “mkstream” – ClearCase with UCM
 
8. 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
     "mklabel" - base ClearCase
     "mkbaseline" UCM ClearCase
 
9. Materialize a set of files in a workspace
 
    The files correspond to underlying elements in the SCM system.
 
    "update" – AccuRev, CVS, ClearCase (for snapshot/web views, implicit 
for dynamic views)
 
10. Get history of an element or set of elements 
 
     Time-ordering listing of the history of changes.
 
    "hist"  - Accurev
    "history" - CVS
    "hist" - ClearCase
 
11. Compare versions of element(s)
 
   "diff" - AccuRev, CVS, ClearCase
 
12. Perform merges of versions, from one branch/stream to another 
 
   "merge" – AccuRev, CVS, ClearCase
 
13. 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
 
14. 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).
 
 

_____________________________________________________________________________
Scanned for SoftLanding Systems, Inc. and SoftLanding Europe Plc by IBM Email Security Management Services powered by MessageLabs. 
_____________________________________________________________________________