Difference between revisions of "ALF/SCM Vocabulary"

Revision as of 17:08, 16 May 2006

Concepts (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.

SCM Use Cases (Operations)

ALF/BuildServerUseCase

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

References

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