Note: This chapter focuses on changes to the user interface. For information on the master.tmpl file see Chapter 7, Understanding the Master Template File. For information about customizing reports, see Chapter 9, Creating Custom ClearDDTS Reports. For information about modifying the database, see Chapter 13, Managing and Customizing the ClearDDTS Database.
Before you begin customizing ClearDDTS, however, you should consider the existing system and how simple or difficult it will be to accommodate your changes. You should also work with development engineers, project managers, and quality assurance groups to determine what bug report states should exist, and what data should be collected during each state transition. Be sure to involve your entire user community and show them what ClearDDTS provides and then ask them for input.
Note: For information on how web pages are generated and specific web customizations you can make see "How webddts pages are generated" in Chapter 7, Understanding the Master Template File.To get started, look at the ~ddts/class/software directory. When you use the ls command on this directory, you should see something like this:
README helps/ states add.encl link_semantics/ submit.encl admin.help/ master.tmpl summary.print/ admin.tmpl/ notify.tmpl user.encl batchbug/ oneofs/ user.hist bugmail_ignore_fields proj.prompt user.index/ clone.prompt report_conf verify.encl description resolve.encl web_conf editencl.tmpl statenames www-helps/This directory contains all of the files you may want to customize for the software class. Similar directories are available for each class containing the files you can customize for that class. (The only other files we recommend you customize are the awk report scripts located in the ~ddts/bin directory.)
The ~ddts/class/software directory contains the following files and subdirectories:
As you may have noticed, most of the files are ClearDDTS template files. The format and meaning of these files are described in later sections.
Adding new fields
Adding a new field to a particular state transition is as easy as adding a new field derivation to the master.tmpl file. When you add a new field derivation, only new bugs will have the new data incorporated into the flat defect file located in ~ddts/allbugs/*.Note: If you are using the web interface and have defined groups of fields, be sure to add any new fields to the appropriate group. See Specific webddts customizations for information on grouping fields.
While adding a new field derivation inserts the new data into the flat file in the allbugs directory, making it available for display, it does not insert it into the ClearDDTS SQL database. If you want to use the new field in defect metrics, sorting, database searching, querying, or index lines, you need to modify the database to include it.
Note: You can also delete fields from the master.tmpl file or the database. However, care should be taken to avoid deleting special fields that ClearDDTS uses internally. See Appendix A for a complete listing of required fields.
Adding defect states
ClearDDTS comes with several default states and legal state transitions (see Chapter 2 in the ClearDDTS User's Guide for a review of these states and state transitions). This set of states should handle most users' needs. Before adding a new state, you may want to consider simply adding an attribute to an existing state. However, if you feel that a new state is necessary, you can add the new state to ClearDDTS by making some simple modifications to a few text files.
S s Submit Submitted N u New New A a Assign Assigned O a Open Opened R r Resolve Resolved V r Verify Verified D x Duplicate Duplicate P o Postpone Postponed F s Forward ForwardedThis file defines the states that exist for this class, and each line consists of four fields as follows:
Some ClearDDTS graphs and metrics present defects as they move from state to state. For example, one graph shows a plot of New defects, on top of that are the Assigned defects, on top of that are the Open defects, and so forth. The order used in the graph is determined by the order the states are defined in the statenames file. The xddts interface uses this order to define the natural progression (lifecycle) of a defect. Therefore the order of states in the statenames file is significant.
If you are adding a new state, you need to determine if it is a mainline state and where the state belongs in the overall lifecycle. Then add the new state line at the appropriate place in the file.
Here are some of the lines from the class/software/states file as shipped:
N A A N O A N R A N V A A A A A O O A R O A V O O A A O O O O R R O V R R R RThe first line above means that if a bug is in state N (New), it is possible to get to state A (Assigned) simply by entering state A. The second line means that to get from state N (New) to state O (Opened), the bug must first enter state A (Assigned). The fourth line means that you must first Assign bugs that are New as the first step toward the Verified state. Note that you must go through state R (Resolve) to enter state V.
ClearDDTS uses the states file to determine what to do whenever you attempt a state transition. For instance, if a defect is in the N (New) state, and you change to the R (Resolve) state, the defect first moves into state A because of the third line shown in the example above (N R A). ClearDDTS asks for all of the information associated with state A, and then considers how to get to the desired state (R) from the state it is in now (A).
The seventh line in the example above says that to get from state A to state R, the defect must first go through the O state. ClearDDTS then asks for the information associated with the O state and again considers how to get to the desired state (R) from the current state (O). In this case, the line O R R tells ClearDDTS that the defect can be moved to the R state and no more processing is necessary.
If there is no triple that lists the current state in the first position, you can't get out of that state. Similarly, if there is no triple that lists a particular state in the second position, bugs can't get to that state from the current state.
The triples can be in any order. However, if there are contradictory state transition rules in the file, such as:
N P O N P PThen only the rule that appears last is used.
As an example, let's add a state called K (perhaps for Killed) to be inserted between Resolved and Verified. Let's assume that entering this state means that a program source has been modified, and the new source code has been checked into whatever place the "official sources" are kept. We'd add the following lines to the states file:
N K A A K O O K R R K K V K K P K O D K O K O O K R R K V V K P O K K K . . . N F F A F F O F F R F F V F FThese lines define the following state transitions:
Note: The format and interpretation of template files is described in detail in the template(5) man page. Although the template files are discussed in this chapter, you should read and understand the man page after you read this section. Pay particular attention to the syntax of the "built-in" commands.
Modifying the master.tmpl for New States
If you have read and understood Chapter 7, Understanding the Master Template File, you are ready to customize this file. If you decide to add a new state to the master.tmpl file, it is important to ensure that the if match statements are correct for your new state. The easiest way to do this is to find another state that treats each field similarly, and duplicate all of the references to that state in if conditions with the new state. For example, if you're adding state K, and it's similar to state P, you should change lines throughout the master.tmpl file that look like this:
if match $STATE$OPERATION Pm Pv Op Ofto read:
if match $STATE$OPERATION Pm Pv Km Kv Op OfYou must also add code at an appropriate place to change the value of the Status field to the new state. The syntax is:
set Status KIf you do not add the code to change Status into the new state, you have created a pseudo-state. Pseudo-states prompt for information to be added or changed in the current defect record without actually changing the state of the defect.
Another thing to consider when adding states to the master.tmpl file is how to handle the OPERATION codes of p and f. These two codes cause a goto to be executed in the template file. The code fragment is:
.
.
.
# The if statement below does a "go-to X-fields" where X is
# the future state of this defect. It does this ONLY for painting
# the form ($OPERATION == f) of new questions to be filled out
# and for prompting ($OPEATION == p) for the new information
# required to enter this state.
# Other $OPERATION codes (m, v, n, and l) execute each and every
# field derivation below.
if match $OPERATION p f# prompt or form
and not equal "X$STATE" X
goto $STATE"-fields"
fi
.
.
.
If your new state is K, you need to create a field called K-fields and insert the appropriate template code at this point in the template file.
aprj2.tmpl aprj3.tmpl mprj2.tmpl mprj3.tmplThe aprj2.tmpl and mprj2.tmpl files contain fields called O-notify, R-notify, and so forth. These fields list the users to whom mail is sent when a defect enters that state. For example:
O-notify:
"\nEnter mail address of those to notify when a bug is\n"
"opened by the assigned engineer:\n"
"%s\n"
help aprj06.hlp
R-notify:
"\nEnter mail address of those to notify when a bug has\n"
"been resolved:\n"
"%s\n"
help aprj07.hlp
If your new state is K, add a field called K-notify with the same derivation lines as you see for the other *- notify fields. You may also want to add a context-sensitive help file (similar to aprj07.hlp) in the class/<classname>/admin.help directory.In the aprj3.tmpl and mprj3.tmpl files, you see derivations for fields called O-allow, O-allow-group, R-allow, R-allow-group. For example:
O-allow:
"\nList LOGIN names of users allowed to OPEN (O state) a\n"
"bug. Just hit return if anyone is allowed to OPEN bugs.\n"
"%s"
help aprj12.hlp
if not null
goodusers
fi
O-allow-group:
"\nList GROUP names of groups allowed to OPEN (O state) a\n"
"bug. Just hit return if any group is allowed to OPEN bugs.\n"
"%s"
help aprj13.hlp
if not null
goodgroups
fi
These fields list the login names of the users (O-allow) and the group names of the groups (O-allow-group) that are allowed to make the specified state transition. For example, if your new state is K, add two new fields called K-allow and K-allow-group with the same derivation lines as you see for the other *-allow and *-allow-group fields. You can also add a context sensitive help file (similar to aprj13.hlp) in the class/<classname>/admin.help directory.As you can see, what you are doing here is adding field derivations (similar to existing ones) regarding the mail notifications and permissions for your new state. The derivations for state P fields are good examples to copy and modify.
After you make these modifications, any new projects created with the adminbug aprj command will ask the appropriate questions concerning who can make state transitions to the new state and who should be sent mail when a defect report enters that new state. However, for projects previously created, anyone will be able to modify them and no mail notifications will be sent, since the new fields were not recorded for those projects. After you have modified the administration template files, you can use adminbug mprj to modify this project information and set it up, if desired.
Note: You should test each of your modified template files with the tmpltest utility to ensure that a new field does what you want before actually using it. For adminbug templates, use the -m option, because those templates do not operate in screen mode. For more information, see Specific xddts customizations.
The index contains the selected fields in the order you see them in the Query Builder.
A template file for the resolved state is shown below:
Status: "%-1.1s "
Severity: "Sv%1d "
Identifier: "%-10.10s "
Software: "%-8.8s "
Headline: "%-35.35s "
Resolver-id: " %-8.8s"
Enclosure-count: if equals $Enclosure-count 0
then
else
" +%-2d"
fi
Note that this template file just creates one line of 72 characters. (There are no newlines (\n) in the format strings.) This line displays various fields of the defect (Status, Severity, Headline, etc.) and is included in the ClearDDTS index to provide a summary of the defects under examination. As shipped, the line looks like this:
17 N Sv3 QTKqa00633 foo foo is broken +2If you create a new K state, you must add a new file called K to this user.index directory. The contents of the new file should be similar (or identical) to the above.
Note that any field mentioned in this template file must also be defined in the ClearDDTS database. If you modify the ClearDDTS database, you must rebuild it with the adminbug dbms command. See Chapter 13, Managing and Customizing the ClearDDTS Database.
Editing the three-line summary template file
ClearDDTS prints defects in a variety of formats. One format is a three-line summary. The ~ddts/class/<classname>/summary.print directory has a set of template files, one per state, that define the three line summary format. The template files look like:
Status: "10t=%s, " Severity: "Sv=%s, " Identifier: "Bug id = %s, " Version: "Vers = %s, " Software: "Defect in %s\n" Headline: "Desc: %s\n" Engineer: "Assig Engr = %s ," Submitted-on: "Found: %s, "These files can be modified to suit your needs. If you add a new state to the system, make sure that you add a file to this directory with the new state letter as the name and containing the code needed to print defects in that state.
As an example, all of these scripts include code for adding a new E state, and that code has been commented out. In most cases, you only need to uncomment the code and change E to the new state letter that you have defined. See the scripts and Chapter 9, Creating Custom ClearDDTS Reports, for more information.
Further template customization
Besides adding new fields and states, ClearDDTS templates allow you to do many other types of customization. This section provides examples of some of the more common modifications. Creating field dependencies
You can make the list of valid responses for one field dependent on the value of another field. For example, maybe you would like to link together the Project and the Software fields so that if a user selects the compiler Project, only C, fortran, and pascal are acceptable answers for the Software field. For example:
Begin: unset Begin
set Filter-path /usr/bin:/bin:/usr/ucb
set Oneof-path class/$Class/oneofs
set Help-path class/$Class/helps
.
.
.
Software: if match $STATE$OPERATION Sp Sf
"\(1,20)Software: %-20.20s"
fi
if match $OPERATION p m
if equals $Project compiler
oneof C fortran pascal
elif equals $Project admin
oneof -f admin
help admin.H
else
oneof -f others
help others.H
fi
required
fi
If the value of the Project field is compiler, the template will only accept Software field values of C, fortran, or pascal. In addition, since no help file is specified, the default help built into the oneof filter command (that is, listing the acceptable answers) is used. If the Project entered was admin, the list of acceptable answers is found in the file ~ddts/class/<classname>/oneofs/admin. The path to find files for the oneof filter command is described by the special field value Oneof-path, which was set in the Begin field derivation. So, the path ~ddts/class/<classname>/oneofs/admin is derived from the lines:
set Oneof-path class/$Class/oneofs oneof -f adminIn the case of the admin projects, the context-sensitive help file for the Software field is located in ~ddts/class/<classname>/helps/admin.H. The location of this file was determined similarly by the lines:
set Help-path class/$Class/helps help admin.HIf the value of Project is not compiler or admin, the acceptable values for the Software field are defined in ~ddts/class/<classname>/oneofs/others and the context-sensitive help is located in ~ddts/class/<classname>/helps/others.H.
This mechanism is simple to use and quite flexible. There are also comments in the template file to help you understand how it works and how it is used by various ClearDDTS programs.
For more complicated validation or expansion of input values, you can use the UNIX utilities such as grep, cut, and sed. See template(5) for more information on using filter commands.
Related-file: if equal $STATE$OPERATION Sp
if uniquetitle -f "Related-file" "Problem"
editfile -r -i $~/class/$Class/submit.encl "Problem"
inc Enclosure-count
log Enclosure "$$" added by $Submitter-id
else
editfile -r "Problem"
log Enclosure "$$" modified by $Submitter-id
fi
fi
This derivation already exists in the default software class master.tmpl. The title for the enclosure is Problem. The -i option causes ClearDDTS to use the contents of ~ddts/class/<classname>/submit.encl as the initial text in a Problem enclosure file every time the user submits a new record. The -r option requires that the enclosure contain text (making it a required field), and when used with -i, that text must be different from the initial text. Without the -r option, the user is still prompted for the enclosure, but adding text is optional (the enclosure is not required). The rest of the derivation increments the Enclosure-count field which contains the number of enclosures in the defect, and includes the name of the submitter in the History enclosure. In additon, you can use the -R option to make an enclosure required. This option is similar to -r (the enclosure cannot be empty), but has the additional requirement that the contents of the enclosure before editing cannot match the contents after editing. For example, this could be used to force additions to the Resolution enclosure if a defect is re-opened and then resolved a second time.
You can use a similar mechanism to prompt users to edit existing enclosures or add enclosures at different state changes. See the comments in the master.tmpl file for more examples.
Creating custom filter commands
You can create and use your own filter commands. These commands could be shell scripts or C programs that read a value from standard input, write the value to standard output, write any explanations of why the value is bad to standard error, and exit with a status of zero (good) or non-zero (bad).
Specific webddts customizations
If you plan on using the webddts interface there are several changes to the user-customizable portions of ClearDDTS, specifically to the master.tmpl and web_conf files, that will enhance the web page display. Label and type modification via the "www" filter
Some fields do not usually have an appropriate field label in view mode (for example, the Headline field) making the View Defect page hard to understand. Web layout using field grouping
In the bugs and xddts interfaces the layout of the form is controlled by cursor addressing in the prompt strings. In HTML the layout is in the order of the master.tmpl file. This can be modified by grouping fields into related sections.
set group_field [<field>][:<modifiers>][, [<field>][:<modifiers>][, [<field>][:<modifiers>] [...] ] ]Modifiers can be broken down into two categories:
set group_fields :numcols=4, Field1, Field2Incorrect: Field1 would not be displayed:
set group_fields Field1:tablewidth="60%" numcols=2, Field2Correct:
set group_fields :tablewidth="60%" numcols=2, Field1, Field2Incorrect: All table modifiers must be in the first position:
set group_fields :tablewidth="60%", :numcols=2, Field1, Field2Incorrect: Spaces separate modifiers, so there is no valid modifier on this line:
set group_fields Field1: colspan = 5, field2
Def-group:
if www
"DEFECT INFORMATION"
set group_fields :numcols=2 tablewidth="75%",
Project, Identifier, Software, Version, Headline : colspan=2 startcol=1,
Showstopper, Enhancement, Status, STATE, Last-mod, Enclosure-count,
Problem_encl : colspan=2 startcol=1
fi
unset Def-group
The table appears on the view defect page as:
Maintaining the cache directory
ClearDDTS uses a caching system to store initial versions of the webddts pages. The cached pages are stored in the ~ddts/www/cache directory. The ClearDDTS cache is completely separate from the browser cache. It is only used for ClearDDTS pages so that they do not need to be generated each time you access them.
Users can also clean their own cache through the webddts interface by clicking the Clean Cache button on the User Profile page.
Specific xddts customizations
This section contains features unique to the xddts interface. Adding new pages
To support multiple pages in a defect report in xddts, ClearDDTS uses four special commands and one variable.Note: The webddts pages use scroll bars for viewing information that requires more than one page to display. Multiple pages are not necessary.
Using the PAGE variable and return statement
The PAGE variable is used to distinguish between the various pages associated with a defect report. This variable is used in the master.tmpl file in much the same way as STATE and OPERATION. The template file runs with the value of PAGE set to some value, and is used in conditional statements to display different pages. Modifying the master template to display other pages
When executing the other pages, you should manually clear the screen, paint the form, prompt for or modify the additional fields, then go back to the first page. To do this, you use:
# Add these three lines
if equals "$PAGE" VERIFY
goto V-fields
fi
# BEFORE these four lines
if match $OPERATION p f # prompt or form
and not equal "X$STATE" X
goto $STATE"-fields"
fi
In this example, the second page is named VERIFY. You can name a page anything you wish; however, you should make it descriptive. Note the double quotes around $PAGE. This is required because the first page is named with the null string. The equals statement will not work correctly without these quotes.
V-fields: unset V-fields
if not equals $STATE V
goto F-fields
fi
if not equals "$PAGE" VERIFY
and input
pushscreen
"\f"
call -o OPERATION f PAGE VERIFY
call -i PAGE VERIFY
popscreen -r
fi
if not equals "$PAGE" VERIFY
goto Last-mod
elif equals $OPERATION v
"\f"
fi
The pushscreen command saves the current screen in memory. The \f then clears the entire screen. The first call command re-executes the master.tmpl file with PAGE set to VERIFY and OPERATION set to f. This paints the verify form on the screen. The second call command again causes the entire master.tmpl file to be re-executed with PAGE set to VERIFY and OPERATION set to p.At this point the user is prompted for all the verify information. When the last field value is entered, execution returns to the popscreen command. The popscreen command restores the screen saved by pushscreen.
# This is existing code
Last-mod: if match $OPERATION p m
today
fi
# Here is the new code
Pages: unset Pages
if null "$PAGE"
return VERIFY
fi
If we are executing the first page, then we return the next page, VERIFY. If we are executing the last page, in this case also VERIFY, then we fall through to the enclosure code so that dumpbug works correctly.
You could also make the second page dependent on Verify-check. For example:
if equals $Verify-check Y, pushscreen call -o OPERATION f PAGE VERIFY call -i PAGE VERIFY popscreen -r fiThis would give you forms-within-forms. An almost unlimited number of combinations can be implemented.
For example, recall the foo.template and foo.script files mentioned earlier that demonstrated the interact filter command. The tmpltest utility can be used to test run these scripts. To debug these scripts, you could issue the following commands:
chmod +x foo.script # make foo.script executable tmpltest -Xfpv foo.templateThe options cause tmpltest to execute the template file foo.template exactly the same way bugs and xddts execute it. That is, once with STATE equal to X and OPERATION equal to f (form), again with STATE equal to X and OPERATION equal to p (prompt), and finally with STATE as X and OPERATION equal to v (view).
As another example suppose you want to test a change to a locally modified version of the master.tmpl file. The following invocation would step through all of the executions of the template file just like bugs would for a newly submitted defect that you immediately decided to resolve. It would also go through all of the steps in modifying a defect for a particular state.
tmpltest -ofpvm -SAORV template.fileThis would test all executions for xddts and bugs. See the tmpltest man page for a complete explanation of how tmpltest works.