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.


Table of Contents


1.0 Introduction

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


2.0 Motivation for View Attributes

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?


3.0 Motivation for View Notes

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.


4.0 Design Strategy

With this idea in mind I threw together some prototype scripts to test out my idea. The basic strategy was:
  1. Reserve a specific subdirectory of the view-storage area for attribute information.

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

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


5.0 View Storage Directory Structure


6.0 Goals

I decided that the functionality provided by ClearView should satisfy the following criteria:
  1. Provide a single command (clearview) with subcommands to create, destroy, and manipulate view attributes and notes.

  2. The syntax for clearview and all of its subcommands should resemble the syntax of cleartool as much as possible.

  3. The subcommands for manipulating view attributes should be modeled after the attribute manipulation facilities of the cleartool command (mkattr, rmattr, ...).

  4. The subcommands for manipulating view notes should be modeled after the config-spec manipulation facilities of cleartool (setcs, edcs, catcs).


Issues to Resolve

Once I knew what I wanted, there were several issues that needed to be resolved:

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:

  1. Provide a means for creating and manipulating view attribute types (and possibly view notes types as well).

  2. 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".


7.0 Designing the ClearView Subcommands

Now I was ready to design the user interface. I decided I would need the following subcommands: 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).


8.0 ClearView Architecture

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.


9.0 Application: a Programmer's Journal

  1. Have developers keep a programmer's journal in their view by using clearview ednotes to recording their comments in a single location.

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

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

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


10.0 Application: a View Event-History

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

  2. If desired, you can use separate event-history notes for each VOB that is being used within the view.

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

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


11.0 Application: Integration with PureDDTS

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:

  1. 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
      
  2. 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
      
  3. 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!


12.0 Future Plans for ClearView

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


13.0 How to Obtain ClearView

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


Appendix: The ClearView Commands


clearview

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:

For more information on using a particular subcommand, use:


clearview mkvwattr

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.

clearview lsvwattr

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.

clearview rmvwattr

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.

clearview mknotes

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.

clearview setnotes

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.

clearview ednotes

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.

clearview catnotes

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.

clearview lsnotes

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.

clearview rnnotes

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.

clearview rmnotes

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.

clearview library

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.


User Presentation Biography

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