ClearView: Associating Attributes and Notes with a View
by Brad Appleton
<Brad_Appleton-gbda001@email.mot.com>
http://www.bradapp.net
Motorola Automotive and Industrial Electronics Group
4000 Commercial Avenue, Northbrook, IL USA 60062
ClearCase International User's Group Conference
September, 1996
| Abstract |
|---|
ClearCase provides the ability to associate attributes and hyperlinks with various
ClearCase entities, but you can't attach them to just anything. In particular, you
can't attach them to types like a branch-type, or a label-type (although version
3.0 is expected to allow this) and you can't attach them to a VOB or a view. We
have implemented a package named
ClearView
which overcomes some of these
difficulties. ClearView allows users to:
-
Associate a set of "notes" with a view. Users edit the notes in much the
same way that they edit their config-specs. The view notes can serve as
a developer's journal or diary where the user can quickly and easily
record their thoughts and ideas about the work performed in the view.
-
Attach attributes to a view and query the values of one or more view
attributes. The attributes belong to the view, not to any elements inside
it. The use of view attributes may be easily employed by scripts and
triggers.
|
ClearCase attributes are a very powerful and useful mechanism for
facilitating configuration management and change control. At present
however, ClearCase only permits you to attach attributes and hyperlinks
to certain kinds of VOB elements:
- elements
- branches
- versions
- VOB symbolic links.
- derived objects
You can't attach them to types like branch-types or label-types (version
3.0 will allow this), you can't attach them to a VOB, and you can't
associate them with a view.
I have found myself in many situations where it would have been very
useful to attach attributes to some of these other kinds of items. I
looked into implementing some way to do this using Perl scripts. View
attributes seemed to be the easiest to try and implement, so I came up
with the following idea:
Since a view's users have write access into the view storage area, why
not set aside a certain portion of the view's storage area for users to
record some extra information to associate with the view?
A proprietary configuration management (CM) system that I have used in
the past employed a task-based model of development: it views a set of
changes to a set of files as a single, logical change rather than as one
or more changes to one or more files.
This task-based CM system does not prompt the user for a comment for
each checkout/checkin. Since all work done in a "task" is for
a single, logical change, there is a single comment-file for developers
to record all notes regarding their changes. This "comment
file" was like a journal or a diary. When the task was finished,
the CM system would then archive these notes for subsequent viewing.
This idea of a set of "notes" for a development task seemed
useful. While a view is not the same thing as a task, it occurred to me
that it might be useful to associate a set of notes with a view. Better
still would be the ability to use more than one set of notes in a view.
With this idea in mind I threw together some prototype scripts to test
out my idea. The basic strategy was:
-
Reserve a specific subdirectory of the view-storage area for attribute
information.
-
For each view attribute desired, create a file in the reserved area
whose name was the attribute name and whose contents was the attribute
value.
-
Have a default set of notes in the reserved area. Additional notes may be named ("tagged") and stored under a subdirectory with the corresponding notes-tag.
I decided that the functionality provided by ClearView should satisfy
the following criteria:
-
Provide a single command (clearview) with subcommands to create,
destroy, and manipulate view attributes and notes.
-
The syntax for clearview and all of its subcommands should
resemble the syntax of cleartool as much as possible.
-
The subcommands for manipulating view attributes should be modeled after
the attribute manipulation facilities of the cleartool command
(mkattr, rmattr, ...).
-
The subcommands for manipulating view notes should be modeled after the
config-spec manipulation facilities of cleartool
(setcs, edcs, catcs).
Once I knew what I wanted, there were several issues that needed to be
resolved:
-
What problems might I encounter with access-permissions?
-
What about concurrent modification?
-
Would I need to use view-attribute-types?
- Access Permissions
-
As long as the user has permission to create view-private files in the
view, the user should also have permission to create and destroy files
in the view's storage area.
- Concurrent Modification
-
If two users want to modify the same view-private file, ClearCase does
not prevent one from overwriting the work of another (after all, that is
what separate views are for). Therefore it should not be a problem if
ClearView does not provide any safeguards against two users trying to
modify the same attributes or notes in a view.
- View Attribute Types
-
ClearView can't require a view-attribute to be a valid ClearCase
attribute-type because attribute types only exist on a per-VOB basis.
The work in a view may encompass multiple VOBs. This leaves two
alternatives:
-
Provide a means for creating and manipulating view attribute types (and
possibly view notes types as well).
-
Don't require a view attribute-type to exist when creating a view attribute.
If ClearView provides view attribute types then it must create and
maintain some global type database in which to store them. If view
attribute types are not provided then there is no straightforward way to
ensure that certain view attribute values conform to a particular
format.
I decided against providing view attribute types in ClearView. If, at a
later time, they seem to be necessary, it would be relatively easy to
add them without impacting the user. At the time, it just seemed like
"overkill".
Now I was ready to design the user interface. I decided I would need the following subcommands:
- clearview mkvwattr
-- create a view attribute
- clearview rmvwattr
-- remove a view attribute
- clearview lsvwattr
-- list one or more view attributes
- clearview mknotes
-- create a set of view notes
- clearview setnotes
-- set a view's notes to the contents of a file
- clearview ednotes
-- edit a view's notes
- clearview lsnotes
-- list the names of one or more view notes
- clearview catnotes
-- show the contents of one or more view notes
- clearview rnnotes
-- rename a set of view notes
- clearview rmnotes
-- remove one or more view notes
Each clearview subcommand should take arguments and options
that resemble their cleartool counterpart and/or an
existing cleartool option name. As much as possible, I
wanted ClearView to look like a natural extension to ClearCase (not like
a layer on top of it).
I decided to implement ClearView using Perl. I wanted to have a core
ClearView-Perl library of primitive operations and a single perl script
for each command and subcommand.
-
Have developers keep a programmer's journal in their view by using
clearview ednotes to recording their comments in a single location.
-
If a format or outline is needed, a script can be created that uses
clearview setnotes to set up a template for the desired format.
-
If multiple developer's will be working in the same view, have them each
use their own set of notes (perhaps named by each developer's login
name). Otherwise, just use the default set of notes.
-
When development in the view is complete, all the "journals"
can be compiled together and archived in an appropriate file, directory,
or database.
It is probably not a good idea to try and document too much with view
notes. They should not be used in place of documents for specifying
requirements, analysis, design, or interface. They may be appropriate
supplementary documentation however (especially when used like a journal
to help you get inside the developer's head at the time the changes were
made).
-
Set up a trigger on all the "interesting" events that logs the
event to a set of notes in the view in such a way that the corresponding
command(s) may be reconstructed (perhaps the notes would be named
ViewHistory).
-
If desired, you can use separate event-history notes for each VOB that
is being used within the view.
-
Such an event-history may be useful in trying to retrace a developer's
steps when certain problems are encountered in the view and may be used
to determine how to recover from certain actions.
-
The event-history may also be useful in its own right as a sequential
log of all the "work" that was done to accomplish a particular
task. NOTE that if you have multiple developer's working in the same
view you may need to take some precautions to ensure that you don't try
to log two (or more) events to the same event-history at the same time.
For ClearCase user's who also use PureDDTS, Atria provides an
integration of ClearCase with Pure Software's PureDDTS. This
integration, among other things, logs checkout and
checkin events into the corresponding change request
record.
In order to know which request to log events against, the
ClearCase-PureDDTS integration looks at the contents of a variable in
the user's environment named "TASK_BUGNUM" (actually
it does a bit more than this but this isn't really important for the
purposes of our discussion). If the TASK_BUGNUM environment
variable is empty (or undefined) then the ClearCase-PureDDTS integration
will prompt the developer to enter the ID of the change request.
Suppose you have a development environment where each view is used for
only one task at a time. In other words, all the work performed in a
view will always be for the same change request (until that request is
resolved in some way). Currently, your only alternative to having to
enter a change request ID with every checkout and
checkin is to remember to set the TASK_BUGNUM
environment variable.
Instead of having to enter a request-ID for every checkin/checkout, or
every time you start an interactive shell to work in the view, you can
do the following:
-
Add three lines to the get_bugnum shell function in file
ccutils.sh in the ClearCase-PureDDTS integration so that it
examines a view attribute if the TASK_BUGNUM environment
variable is not set.
if [ -z "$TASK_BUGNUM" ] ; then
TASK_BUGNUM=`clearview lsvwattr -quiet -fmt %v TASK_BUGNUM`
fi
-
Whenever a developer begins work on a defect, use clearview
mkvwattr to create the view attribute corresponding to the
request.
clearview mkvwattr -replace TASK_BUGNUM XYZab01234
-
Have the developer reset (or remove) the view attribute after work on
the defect has been completed.
Now the developer only has to enter the request-ID once at the beginning
of each task!
- Perl5 Rewrite
-
At present, ClearView is written in version 4 of the Perl programming
language. I would like to rearrange portions of it to take advantage of
some of the object-oriented features available in version 5 of the Perl
programming language.
- Triggers
-
It might be useful to allow the user to define triggers to execute a
specified command or script when view attributes or notes are modified.
- Types
-
It may be useful to implement "types" for attributes (and
possibly even for notes, although I'm not sure what that means yet
beyond reserving a name for use).
- Locks
-
It may be useful to allow a view attribute (or even a view-attribute
type) to be "locked".
- Atria's "contrib" Site
-
The complete Perl source for
ClearView has been made available as package T0025 at
Atria's User Contributed Software ("contrib") site located at
the following URL on the World Wide Web:
- CCIUG Mailing List
-
Announcements regarding new releases (updates) of ClearView will be made
on the ClearCase International User's Group electronic mailing list
<cciug@atria.com>.
- Synopsis:
-
clearview
[-Help]
[-version]
subcommand
subcommand-arg
...
- Arguments:
-
- -Help
-
Print this help message and exit.
- -version
-
Display the current version of clearview.
- subcommand
-
A subcommand of clearview to invoke.
- subcommand-arg
-
An argument/option to a subcommand of clearview.
- Description:
-
clearview provides several subcommands to allow the user to
create and manipulate various attributes and/or notes that may be
associated with a view. The current list of subcommands is:
Commands for manipulating a view's notes:
- mknotes
-- create notes (only if they don't already exist)
- rmnotes
-- remove notes
- rnnotes
-- rename notes
- setnotes
-- set notes (even if they don't exist yet)
- ednotes
-- edit notes (even if they don't exist yet)
- catnotes
-- display notes
- lsnotes
-- list the name-tags of one or more notes
Commands for manipulating a view's attributes:
- mkvwattr
-- create a view attribute
- rmvwattr
-- remove one or more view attributes
- lsvwattr
-- list one or more view attributes
Commands for browsing the contents of the ClearView Perl library:
- library
-- list documentation for one or more ClearView perl functions
For more information on using a particular subcommand, use:
clearview subcommand -Help
- Synopsis:
-
mkvwattr
[-Help]
[-tag view-tag]
[-replace]
attr-name [attr-value]
- Arguments:
-
- -tag view-tag
-
The view to use. Defaults to the current view if not specified.
- -replace
-
Replace the current attribute value if it already exists (an error is
generated otherwise).
- attr-name
-
The name of the attribute to (re)set. It must be a valid ClearCase
attribute name.
- attr-value
-
The value to assign to the attribute. If no value is given then the
contents of standard input is used as the value (unless standard input
is connected to a terminal)
- Description:
-
mkvwattr will create or replace the value for an attribute
associated with the given view. If no view is given then the current
view is used.
- Synopsis:
-
lsvwattr
[-Help]
[-fmt spec]
[-quiet] [-tag view-tag]
[attr-name ...]
- Arguments:
-
- -quiet
-
Don't complain about attributes that don't exist.
- -tag view-tag
-
The view to use. Defaults to the current view if not specified.
- -fmt spec
-
Specify the format of the output. The following special format items may
be used:
- %t
: replaced with the view tag
- %s
: replaced with the view storage path
- %h
: replaced with the view hostname
- %n
: replaced with the attribute name
- %v
: replaced with the attribute value
- %u
: replaced with the login name of the user that last set the attribute
- %d
: replaced with the date & time that the attribute value was set
- %%
: replaced with the percent character itself
Standard C escape ('\') sequences may also be used.
The default output format is "%n = %v\n".
- attr-name
-
The name of an existing attribute to list.
- Description:
-
lsvwattr will list one or more attributes associated with
the given view. If no view is given then the current view is used. If no
attribute names are given, then all attributes are listed. The exit
status is 0 if at least one attr-name was listed and printed. If
all attr-names given were invalid, the exit status will be 1.
- Synopsis:
-
rmvwattr
[-Help] [-all]
[-confirm]
[-force]
[-quiet]
[-tag view-tag]
[attr-name ...]
- Arguments:
-
- -all
-
Remove all attributes associated with the view.
- -confirm
-
Prompt for confirmation before removing attributes.
- -force
-
Don't prompt for confirmation before removing attributes (this is the
default unless '-all' is used).
- -quiet
-
Don't complain about attributes that don't exist.
- -tag view-tag
-
The view to use. Defaults to the current view if not specified.
- attr-name
-
The name of an existing attribute to remove. At least one
attr-name is required unless '-all' is specified.
- Description:
-
rmvwattr will remove one or more attributes associated with the
given view. If no view is given then the current view is used.
- Synopsis:
-
mknotes
[-Help]
[-notes notes-tag]
[-tag view-tag]
[pname]
- Arguments:
-
- -notes notes-tag
-
Specify the name-tag of the set of notes to create (if not given,
the default set of notes is created).
- -tag view-tag
-
The view to use. Defaults to the current view if not specified.
- pname
-
The pathname of the file to use as contents for the notes.
If no pathname is given then the contents of standard input is used
(unless standard input is connected to a terminal, in which case it
behaves like ednotes).
- Description:
-
mknotes will create the notes associated with the given view.
If no view is given then the current view is used. The rules for naming
notes with a tag are the same as those for naming attributes with the
exception that the tag '.' may be used to indicate the default
set of notes.
- Synopsis:
-
setnotes
[-Help]
[-notes notes-tag]
[-tag view-tag]
[-append | -prepend | -replace]
[pname]
- Arguments:
-
- -notes notes-tag
-
Specify the name-tag of the set of notes to (re)set (if not
given, the default set of notes is (re)set).
- -tag view-tag
-
The view to use. Defaults to the current view if not specified.
- -append
-
Specifies that the current notes file should be appended to (instead of
replaced).
- -prepend
-
Specifies that the current notes file should be prepended to (instead of
replaced).
- -replace
-
Specifies that the current notes file should be replaced (this is the
default).
- pname
-
The pathname of the file to use as contents for the notes. If no
pathname is given then the contents of standard input is used (unless
standard input is connected to a terminal, in which case behaves like
ednotes).
- Description:
-
setnotes will set the notes associated with the given view. If
no view is given then the current view is used. The rules for naming
notes with a tag are the same as those for naming attributes with the
exception that the tag '.' may be used to indicate the default
set of notes.
- Synopsis:
-
ednotes
[-Help]
[-notes notes-tag]
[-tag view-tag]
[-append | -prepend | -replace]
[pname]
- Arguments:
-
- -notes notes-tag
-
Specify the name-tag of the set of notes to edit (if not given,
the default set of notes is edited).
- -tag view-tag
-
The view to use. Defaults to the current view if not specified.
- -append
-
Specifies that the current notes file should be appended to (instead of
replaced).
- -prepend
-
Specifies that the current notes file should be prepended to (instead of
replaced).
- -replace
-
Specifies that the current notes file should be replaced (this is the
default).
- pname
-
The pathname of the file to use as the initial contents for the notes to
edit. If no pathname is given and standard-input is not connected to a
terminal, then the contents of standard input is used (otherwise the
existing notes are edited).
- Description:
-
ednotes will set the notes associated with the given view. If
no view is given then the current view is used. ednotes will
use the editor named by the CLEARVIEW_NOTESEDITOR environment
variable. If this environment variable is undefined or empty, then
ednotes will use the same editor that cleartool edcs
would use. The rules for naming notes with a tag are the same as those
for naming attributes with the exception that the tag '.' may
be used to indicate the default set of notes.
- Synopsis:
-
catnotes
[-Help]
[-notes notes-tag]
[-quiet]
[-tag view-tag]
[notes-tag ...]
- Arguments:
-
- -notes notes-tag
-
Specify the name-tag of a set of notes to display. (May be
specified multiple times)
- -quiet
-
Don't complain about notes that don't exist.
- -tag view-tag
-
The view to use. Defaults to the current view if not specified.
- notes-tag
-
Specify the name-tag of a set of notes to
display.
- Description:
-
catnotes will display the specified notes associated with the
given view. If no view is given then the current view is used. If no
notes are specified, the default notes are displayed. The rules for
naming notes with a tag are the same as those for naming attributes with
the exception that the tag '.' may be used to indicate the
default set of notes.
- Synopsis:
-
lsnotes
[-Help]
[-notes notes-tag]
[-quiet]
[-tag view-tag]
[notes-tag ...]
- Arguments:
-
- -notes notes-tag
-
Specify the name-tag of a set of notes to list. (May be specified
multiple times)
- -quiet
-
Don't complain about notes that don't exist.
- -tag view-tag
-
The view to use. Defaults to the current view if not specified.
notes-tag Specify the name-tag of a set of notes to list.
- Description:
-
lsnotes will list the names of one or more tagged notes
associated with the given view. If no view is given then the current
view is used. If no notes-tags are given, then all notes are
listed. The rules for naming notes with a tag are the same as those for
naming attributes with the exception that the tag '.' may be
used to indicate the default set of notes. The exit status will be 0 if
at least one valid notes-tag was found and listed. If all
notes-tags given were invalid, the exit status will be 1.
- Synopsis:
-
rnnotes
[-Help]
[-replace]
[-tag view-tag]
from-notes-tag
to-notes-tag
- Arguments:
-
- -replace
-
Overwrite to-notes-tag if it already exists.
- -tag view-tag
-
The view to use. Defaults to the current view if not specified.
- from-notes-tag
-
Specify the current name-tag of a set of notes to rename.
- to-notes-tag
-
Specify the new name-tag to use for the given
set of notes.
- Description:
-
rnnotes will rename the specified notes associated with the
given view. If no view is given then the current view is used. The rules
for naming notes with a tag are the same as those for naming attributes
with the exception that the tag '.' may be used to indicate the
default set of notes.
- Synopsis:
-
rmnotes
[-Help]
[-all]
[-confirm]
[-force]
[-notes notes-tag]
[-quiet]
[-tag view-tag]
[notes-tag ...]
- Arguments:
-
- -all
-
Remove all notes associated with the view.
- -confirm
-
Prompt for confirmation before removing notes.
- -force
-
Don't prompt for confirmation before removing notes
(this is the default unless '-all' is used).
- -quiet
-
Don't complain about attributes that don't exist.
- -notes notes-tag
-
Specify the name-tag of a set of notes to remove. (May be
specified multiple times)
- -quiet
-
Don't complain about notes that don't exist.
- -tag view-tag
-
The view to use. Defaults to the current view if not specified.
- notes-tag
-
Specify the name-tag of a set of notes to remove.
- Description:
-
rmnotes will remove the notes associated with the given view.
If no view is given then the current view is used. If no
notes-tags are given, then the default set of notes is removed.
The rules for naming notes with a tag are the same as those for naming
attributes with the exception that the tag '.' may be used to
indicate the default set of notes. The exit status is 0 if at least one
set of notes was successfully removed. Exit status is 1 if no notes were
successfully removed.
- Synopsis:
-
library
[-Help]
[-long | -apropos | -short]
[regexp ...]
- Arguments:
-
- -long
-
Print full documentation for matching functions.
- -apropos
-
Print summary description for the matching functions.
- -short
-
Print only the function name of any matching functions.
- regexp
-
A regular expression to match against function names.
- Description:
-
library will display the documentation for the functions in the
ClearView library whose names match the given regular expressions. If no
regular expressions are given then summary descriptions are output for
all functions in the library, otherwise full documentation is used.
Brad Appleton lives in the
Chicago area and is a Senior Software Engineer with
Motorola AIEG in
Northbrook, IL. For the past two years he has spent much of his time
crafting shell and
Perl scripts for use with
ClearCase and
PureDDTS.
Before joining Motorola, he worked for
six years as a developer of software development and configuration
management tools. Brad received his BS in Mathematics and Computer
Science from the University of Michigan
in 1988, and is currently working towards an MS in Software Engineering.
His other professional interests include object-oriented design and
software process improvement. He may be reached via e-mail at
<Brad_Appleton-gbda001@email.mot.com>.
Brad Appleton
<Brad_Appleton-gbda001@email.mot.com>
Motorola Automotive and Industrial Electronics Group
4000 Commercial Avenue, Northbrook, IL USA 60062