This chapter describes the integration of Atria® Software's ClearCase configuration management system with Silicon Graphics Inc.'s Tracker bug-tracking tools. The ClearCase/Tracker Integration provides each application with tools for exchanging information about bugs and bug-fixing activity. It updates the Tracker database automatically, and provides reporting capabilities for both the ClearCase and Tracker user.
This integration is designed to work specifically with the RTS sample application, and is dependent on the state and field names used in RTS. It can be modified to work with custom-designed applications by changing information in the trigger scripts, which are described later in this chapter.
 | Note: The integration system files are contained in the Tracker.sw.clearcase subsystem. You can install this subsystem only if you have ClearCase already installed. For more information, see the Tracker 2.0 Release Notes. |
This chapter covers these topics:
The purpose of the integration
The integration architecture
The trigger scripts
Checkout and checkin triggers
Some typical tasks performed with the integration
The checkout/checkin model is ClearCase's standard mechanism for managing the growth of an element's version tree: checkout creates an editable copy of a file in a user's view; checkin adds a new version to the element's version tree.
The ClearCase/Tracker Integration extends this model to include information about bug fixing. When checking out a file, a developer enters a bug number. The checkout succeeds only if the bug number can be validated against an existing Tracker bug report. Information about the checkout is recorded in a ClearCase versioned object base, or VOB, in the form of an event record and attributes (see Figure 7-1). In the Tracker database, the update appears in the “Resolved in:” field.
When checking in a file, a developer enters a bug number again. This begins the same validation sequence that was performed before: the checkin succeeds only if a corresponding Tracker bug report exists. Both the VOB database and Tracker database are updated to reflect the file's change in condition.
Not every checkin constitutes a “fix,” however. The developer can create “checkpoint” (intermediate) versions of a source file during the course of bug-fixing work. Only the final version “fixes” the bug, not the intermediate versions.
A developer can also cancel a checkout with the uncheckout command, removing information about the checkout from both the VOB database and Tracker database.
The integration does not impose a hard connection between a ClearCase checkin (a state transition) and a “fixed bug” (a status). It includes tools to create a closer connection, but the decision to call a bug “fixed” remains a site policy decision.
When you install the ClearCase/Tracker Integration, it prepares ClearCase VOBs for use with Tracker (see Figure 7-2). The integration creates attribute types and trigger types in ClearCase VOBs. The attribute types are used to track changes to source files as they proceed thronugh the bug-fixing life-cycle, from “work in progress” (WIP attribute) to “fixed” (FIXES attribute).
The trigger types implement the mechanism through which File and Tracker communicate and update their databases. For details on this mechanism, see “The Integration Architecture” in the next section.
The integration provides ClearCase users with tools for tracking status:
The find_wip script lists every version of an element with the WIP attribute. For example:
% find_wip base.c base.c@@/main/CHECKEDOUT WIP 3 base.c@@/main/ports/2 WIP 6
The find_fixes script lists every bug that a particular version of an element fixes, using values of the FIXES attribute. For example:
% find_fixes base.c Version base.c@@/main/5 fixes the following bugs: 23 6 3
| Note: Each version can have only one instance of the FIXES attribute, but this does not mean that it can fix only one bug. For more details, see “Using the find_fixes Utility” later in this chapter. |
The ClearCase/Tracker Integration includes a tool for enforcing site policies. It takes the form of an editable “policy file” (default: policy_vars.sh), which defines UNIX environment variables used by the integration software. The environment variables, which can be set in one or more policy files, include:
-
determines if a user must specify a bug number when checking out or checking in a file
-
determines if a user must be authorized to work on a bug, or if anyone can work on the bug (no validation)
-
determines how the system responds when operations occur out of order; for example, if the checkin bug number is different from the checkout bug number
A complete list of the environment variables and their purpose is given in Appendix A, “The policy_vars.sh File.”
You can set other environment variables in the policy file, such as the Tracker Administrator's name, the character used to “checkpoint” element versions (“no bug-fix” character), and other general items.
You can also let different groups of ClearCase users have different policy files. For example, you might set up a policy file for a new development group that does not require users to enter a bug number. Or, you could set up a policy file that updates a completely different Tracker database.
The integration allows ClearCase users to set up a work environment called a bug task. The bug_task utility establishes task parameters, which include a bug number and a ClearCase view-tag.
The bug_task utility creates a process that is attached to a specified view. While working in that process, you need not enter a bug number during checkout or checkin; the task's bug number is used automatically.
UNIX shell scripts, DML macros, and ClearCase triggers form the basis of the integration mechanism. Together, they allow ClearCase and Tracker to exchange information and affect each other's behavior. The integration creates global-element triggers in each VOB database, including:
a pre-op and post-op checkout trigger:
(tracker_pre_co_trig, tracker_post_co_trig
a pre-op and post-op checkin trigger:
tracker_pre_ci_trig, tracker_post_ci_trig
a pre-op uncheckout trigger:
tracker_pre_unco_trig
Each trigger runs a shell script. The pre-op trigger exit status determines if the operation proceeds or is cancelled.
The trigger scripts described in the following sections depend on several Tracker-specific scripts that access the Tracker database. If you want to use the integration for a customized database, you must modify the scripts accordingly.
All integration files, including the scripts, are located in /usr/atria/tracker. Table 7-1 lists each script and its purpose.
Script Name | Purpose |
|---|---|
Verifies that: - the bug number entered by a user actually exists in the Tracker database - it is an “open” bug, that is, AWAITING_RESPONSE | |
Informs Tracker about a checkin to fix a bug. It updates the “resolved_in” field of the bug and adds the name of the checked-in file to the “resolved_in” list. | |
Inform Tracker about a checkout or uncheckout. They make no change to the Tracker database. They are provided so that the system administrator can extend the integration if desired. |
The shell script run by the pre-op checkout trigger prompts you for a bug number, and then invokes a DML macro to validate the request with Tracker. The validation comprises these checks:
the bug number exists
no illegal state prevents the checkout
If these conditions are met, the script exits with a success status, and the checkout proceeds. The shell script run by the post-op checkout trigger attaches the WIP=bug_number attribute to the checked-out version. Figure 7-3 illustrates the checkout mechanism.
If the checkout request cannot be validated (for example, because the user was unauthorized to work on the bug), the pre-op trigger exits with a failure status, and the checkout is cancelled.
The shell script run by the pre-op checkin trigger checks the specified version for the WIP attribute and, if it exists, prompts you for the bug number that the version fixes. Entering the “no bug-fix” character (by default, 0) “checkpoints” the version: the checkin proceeds with no change to the attribute or to the Tracker database. Attribute manipulations by the post-op checkin trigger are suppressed.
Entering a bug number invokes the same validation procedure that occurs at checkout. If the request is valid, the script exits with a success status, and the checkin proceeds.
The shell script run by the post-op checkin trigger removes all WIP=bug_number attributes from the element.
| Note: It is possible for many versions to have the same WIP attribute value. |
Then, it attaches the FIXES=bug_number attribute to the checked-in version. The script also invokes a DML macro to update the Tracker database with a bug report. If several versions had the WIP=bug_number attribute, the DML macro deletes the corresponding checkout records from Tracker, leaving only the most recent checkout record intact.
Figure 7-4 illustrates the checkin mechanism.
If a checkin request cannot be validated, the pre-op trigger exits with a failure status, and the checkin is cancelled. The post-op trigger sends mail to the Tracker Administrator explaining the problem and showing the failed DML commands. The Administrator can rerun these commands at a later time.
For more details, see “Recovering from Database Update Failures” later in this chapter.
The shell script run by the pre-op uncheckout trigger checks the specified version for the WIP attribute. If the version does not have a WIP attribute, the uncheckout proceeds normally.
The uncheckout command itself removes the WIP attribute (if any) from the checked-out version; there is no need for the trigger to perform this operation.
This section presents some typical usage scenarios for the ClearCase/Tracker Integration.
A customer-reported problem has been assigned bug number 6 in Tracker. The bug involves several source files, including parser.h, main.c, and base.c. Using ClearCase, a developer begins working on parser.h.
The developer checks out parser.h, and provides the bug number:
% cleartool checkout -nc parser.h What bug number will you be fixing? (0 for none) 6 Tracker: Successful verification. Created attribute "WIP" on "parser.h@@/main/CHECKEDOUT". Checked out "parser.h" from version "/main/4".After editing the file, he “checkpoints” the element by entering the “no bug-fix” character:
% cleartool checkin -c "checkpoint" parser.h What bug number have you fixed? (0 for none) [6] 0 Checked in "parser.h" version "/main/5".The developer checks out parser.h again, and resumes working on bug 6. Instead of entering an explicit bug number, he accepts the default value by pressing <Enter>:
% cleartool checkout -c "resume conditionalizing work" parser.h What bug number will you be fixing? (0 for none) [6] RETURN Tracker: Successful verification. Created attribute "WIP" on "parser.h@@/main/CHECKEDOUT". Checked out "parser.h" from version "/main/5".
Before getting to work, he checks status with the find_wip utility to see if parser.h has been edited to fix other bugs:
% find_wip parser.h parser.h@@/main/5 WIP 6 parser.h@@/main/CHECKEDOUT WIP 6
The developer checks in parser.h, indicating that it fixes bug 6:
% cleartool checkin -c "conditionalized parameters" parser.h What bug number have you fixed? (0 for none) [6] <Rtn> Tracker: Successful verification. Removed attribute "WIP" from "/tut_vobs/soap/parser.h@@/main/6". Removed attribute "WIP" from "/tut_vobs/soap/parser.h@@/main/5". Created attribute "FIXES" on "/tut_vobs/soap/parser.h@@/main/6". Checked in "parser.h" version "/main/6".The developer verifies that the bug fix was recorded in the VOB:
% find_fixes parser.h Version parser.h@@/main/6 fixes the following bugs: 6
| Note: A developer is assigned to work on bug 5. The fix involves several files, so he or she decides to set up a bug task to make the job easier. The project leader has instructed everyone to make fixes in the bug-fix view. |
The developer runs the bug_task utility to establish task parameters and start the task:
% bug_task What bug number will you be fixing? 5 What view will you be using? [arb] bugfix Starting task to fix bug "5" in view "bugfix". Please exit shell when done.
Note: bug_task stores the bug number in the TASK_BUGNUM environment variable. You can set this environment variable manually, and not be prompted for a bug number when you checkout or checkin a file. Before getting started, the developer checks the view:
% cleartool pwv Working directory view: bugfix Set view: bugfix
The developer checks out the first of several files involved with the fix:
% cleartool checkout -nc main.c Tracker: Successful verification. Created attribute "WIP" on "main.c@@/main/CHECKEDOUT" Checked out "main.c" from version "/main/5".
The developer checks in the file when ready:
% cleartool checkin -c "fixed init error" main.c Tracker: Successful verification. Removed attribute "WIP" from "/vobs/soap/main.c@@/main/6". Created attribute "FIXES" on "/vobs/soap/main.c@@/main/6". Checked in "main.c" version "/main/6".
When all files have been checked in, the developer terminates the bug_task by exiting the process:
% exit % cleartool pwv Working directory view: arb Set view: arb
A developer checks out a file with the wrong bug number, and cancels the checkout.
The developer performs the checkout, specifying bug 4:
% cleartool checkout -nc base.c What bug number will you be fixing? (0 for none) 4 Tracker: Successful verification. Created attribute "WIP" on "base.c@@/main/CHECKEDOUT" Checked out "base.c" from version "/main/1".The developer checks the file's status with find_wip, and realizes the mistake:
% find_wip base.c base.c@@/main/CHECKEDOUT WIP 4
(The mistake might just as easily have been noticed at checkout time.)
The developer cancels the checkout, and checks the file's status again:
% cleartool uncheckout -rm base.c Checkout cancelled for "base.c". % find_wip base.c There are no WIP attributes on this element.
A site allows developers to checkout a file with one bug number and check it in with another (an “incomplete cycle”). A developer checks a file out and begins working on bug 3. Later, he or she checks the file in as the fix for bug 4.
The developer checks out the file, specifying bug number 3:
% cleartool checkout -nc base.c What bug number will you be fixing? (0 for none) 3 Tracker: Successful verification. Created attribute "WIP" on "base.c@@/main/CHECKEDOUT" Checked out "base.c" from version "/main/2".The developer really fixes bug 4, so he or she checks the file in with that bug number. When warned about the incomplete cycle, he or she indicates the intention of continuing anyway:
% cleartool checkin -c "increased buffer size" base.c What bug number have you fixed? (0 for none) [3] 4 Tracker: Warning: A check out has not been done. Do you wish to continue despite the warnings? [no] yes Changing WIP value from 3 to 4 Removed attribute "WIP" from "/tut_vobs/soap/base.c@@/main/CHECKEDOUT". Created attribute "WIP" on "/tut_vobs/soap/base.c@@/main/CHECKEDOUT". Removing Checkout record for 3 from Bugtracking Database Removed attribute "WIP" from "/tut_vobs/soap/base.c@@/main/3". Created attribute "FIXES" on "/tut_vobs/soap/base.c@@/main/3". Checked in "base.c" version "/main/3".
The Tracker Administrator has defined an illegal state that prevents a file from being checked in if the bug is closed. A developer tries to checkin a bugfix, but the Tracker bug status is “CLOSED”:
% cleartool checkin -c "changed ifdef, line 15" base.h What bug number have you fixed? (0 for none) [7] 7 Tracker: Error: Bug Status CLOSED for bugid 7 is illegal for checkin cleartool: Warning: Trigger "tracker_pre_ci_trig" has refused to let checkin proceed. cleartool: Error: Unable to check in "base.h". |
To checkin the file, the developer must specify another bug number, “checkpoint” the version (for example, by entering 0), or cancel the checkout with the uncheckout command.
A site has two Tracker databases: one for tracking alpha project bugs, another for tracking beta project bugs. The alpha project team uses the default policy file, policy_vars.sh. The beta project team uses an alternate policy file, /usr/atria/tracker/alt_policy_vars.sh.
The integration software uses policy_vars.sh automatically, unless the ALT_POLICY environment variable is set. Therefore, alpha team members begin work with no special preparation. beta team members set the ALT_POLICY environment variable in their shell startup script:
setenv ALT_POLICY /usr/atria/tracker/alt_policy_vars.sh
(C shell)
ALT_POLICY=/usr/atria/tracker/alt_policy_vars.sh
(Bourne shell)
export ALT_POLICY
|
A site allows developers to omit the bug number when they checkout or checkin a file. The “no bugfix” character is 0 (the default value). A new project has started, and the development team wants to bypass the integration mechanism altogether. Each team member sets the TASK_BUGNUM environment variable to 0:
% setenv TASK_BUGNUM 0 (C shell) % TASK_BUGNUM=0 (Bourne shell) % export TASK_BUGNUM |
As an alternative, each team member starts a bug task with bug number 0.
The find_fixes utility compiles a list of bug fixes from values of the FIXES attribute. It uses the following algorithm to determine the list of bugs that a particular version of an element fixes:
First, it lists the FIXES attribute value for the specified version (if any).
Then, it lists the FIXES attribute value for any of that version's ancestors.
Finally, it lists the FIXES attribute value for any merge contributor that produced the specified version, or any of its ancestors.
find_fixes recursively processes merge contributor versions to determine their list of bug fixes: it examines their ancestor versions, any merge contributors that produced them, and so on.
To illustrate the find_fixes algorithm, consider the version tree in Figure 7-5. Several versions have the FIXES attribute — some on the main branch, others on subbranches.
find_fixes returns the following list of bug fixes for the latest version on the main branch:
% find_fixes foo.c Version foo.c@@/main/5 fixes the following bugs: 45 23 4 |
The listing includes bug 45 because that fix was merged into an ancestor version of foo.c@@/main/LATEST, which itself, fixes bug 23 (also listed). It includes bug 4 because that fix was also made in one of foo.c's ancestor versions.
find_fixes returns the list of bug fixes below for the latest version on the branch2 branch:
% find_fixes foo.c@@/main/branch2/LATEST Version foo.c@@/main/branch2/2 fixes the following bugs 17 4 |
The listing includes bug 17 because the latest version on the branch2 branch fixes that bug. It includes bug 4 because that fix was made in an ancestor version of foo.c@@/main/branch2/2.
Neither listing includes bug 9, however (fixed on the branch3 branch), because neither of the specified versions have “inherited” that fix.
If the Tracker database cannot be updated during a ClearCase checkout, checkin, or uncheckout (for example, because the Tracker database server went down), ClearCase triggers send mail to the Tracker Administrator (value of BUGTRACK_ADMIN environment variable).
Figure 7-6 shows a typical mail message, which explains the problem and includes the DML macro that failed.
You can recover the lost transaction (for example, a ClearCase checkin) by rerunning the DML macro manually.
Set a view:
% cleartool setview <any view-tag>
As the VOB owner or root user, run the vob_prep script over each VOB to be integrated with Tracker. The script takes one or more full pathname arguments; you can specify any pathname within the VOB. For example, these commands prepare three VOBs for use with Tracker:
% su Password: <enter root password> # vob_prep /vobs/scomp /vobs/soap /vobs/gui Installing types for ClearCase/Tracker integration into /vobs/scomp. ------------------------------------------------- Created trigger type "tracker_pre_co_trig". Created trigger type "tracker_post_co_trig". Created trigger type "tracker_pre_ci_trig". Created trigger type "tracker_post_ci_trig". Created trigger type "tracker_pre_unco_trig". Created attribute type "WIP". Created attribute type "FIXES". . . similar output for /vobs/soap and /vobs/gui .(optional) Instruct other ClearCase users to run vob_prep over any of their own VOBs that they want integrated with Tracker.