| [alf-dev] ALF SCM use cases |
|
I sent this out to alf-req (apologies if you get it twice). AccuRev plans to get involved in ALF development,
ALF-enabling our SCM product and so on. To that end, we’d like to expand the set of SCM use
cases in the existing ALF requirements document to make them more complete. Richard Title, developer & Scott
McGrath, product manager AccuRev SCM Use Cases for ALF For the
list of SCM use cases below, we have attempted to capture the core
functionality of an SCM tool. These are intended as building blocks: The hope
is that tools that want to integrate with an SCM system (e.g. IDE’s,
issue-tracking tools, build tools) can create the SCM integrations they need
out of these core capabilities. Of course, if we discover needed but missing
use cases, we can extend this list. A
challenge of ALF will be defining the common vocabulary that the tools use to
talk to each other. The vocabulary and model may vary from tool to tool. In
particular, for SCM, we’ll want to talk about objects like
“elements”, “versions”, “branches”,
“streams”, “baselines”, “workspaces”, etc,
and the precise meaning of these things will vary from SCM tool to SCM tool. In the
list of use cases below we deal with this by introducing new terms as we go
(putting each new term in italics).
If there’s more than 1 term for the concept we’ll put the 2nd
/ 3rd one(s) in parenthesis, as in
workspace (sandbox) (view). We’ll let each term be defined
functionally by its use case. This isn’t very rigorous, but for now it
should be good enough. In most cases we give examples from existing SCM-tool
command-line-interfaces to clarify what we mean. 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 a set of
changes, typically defined to support associating the set of changes with a
defect. A change-package is typically defined as a set of versions without gaps
(though other definitions are possible).
“cpkadd” - AccuRev
“mkactivity”, “checkin” (specifying an activity) -
ClearCase 15. Associate defect
(issue) with a change-package
(activity) A 2-way association can be maintained between issues
in an issue-tracking-system and sets of changes in an SCM system. Examples from existing systems: AccuRev/AccuWork – this integration is
supported by the UI ClearCase/ClearQuest – this integration is
supported by the UI 16. Create a trigger which fires on selected actions in
the SCM system Many
SCM systems support the notion of triggers, which typically are set up to fire
when given element(s), stream(s), etc are changed. Traditionally these are associated with executable
scripts on either the client machine or the server machine, though in the
context of ALF they might instead be associated with firing an ALF service
request. “mktrig” – AccuRev “mktrigger” - ClearCase |