In many organizations, there is a need for an integrated approach to Configuration Management (CM) and Defect Tracking (DT). This integrated approach is necessary for effective change control and is often called Change Management.
This chapter describes the general problems, requirements, and levels of integration necessary to control and track changes, and the specific ways that ClearDDTS can help you implement a robust Change Management system.
Before considering the solution, it is best to understand why you may want to integrate configuration management and defect tracking. For the most part, every Release Engineering Manager would like to be able to answer the following questions:
None of the questions above can be answered by a standalone CM or DT tracking system. To address this problem, ClearDDTS is designed to work with your current CM system to provide an integrated change management solution.
Answering the questions posed above requires a robust CM/DT integration. The resulting software, called the Change Management Control System (CMCS), is similar to what hardware engineers and manufacturing departments have used for years to control changes that go into manufacturing (the Engineering Change Order, or ECO, system).
In manufacturing industries, Engineering Change Orders are used to control and track hardware changes that need to move from engineering into production. The ECO process includes approvals, schematic drawing or blue print check out/in, process controls, defined release dates, and predictability in the hardware release process.
In the software industry, a similar process can be used where the DT system records change orders and the CM system provides a repository and defined configurations where the software (hardware drawings and blue prints) can be checked in and out. This software ECO system requires a CM and DT system to be integrated at three distinct levels:
Effective version control integration can help answer the following questions:
Version control allows you to make changes to a file (or versioned object) and still be able to recreate any prior version of the file. There are several freely available version control systems in the UNIX environment. The most common version control system is the Source Code Control System, SCCS. Other freely available, often used systems include the Revision Control System, RCS, and the Concurrent Version System, CVS.
ClearDDTS provides version control integration with RCS and SCCS by keeping pointers to objects that these systems manage. The version control system is configured to remember a defect identifier at check-in time and ClearDDTS remembers all the files that were checked in and out on behalf of a particular defect. This is illustrated in Figure 15-1.
Figure 15-1: Version Integration
In this figure, file foo.c was checked out on behalf of defect identifier ECO12345; files main.c, bar.c, and fram.c were checked in on behalf of defect identifier ECO12345. The version control system saves the defect id in the version database and the defect tracking system saves all the file names checked in/out in the defect record called ECO12345.
If a user wants to back out a change to foo.c, he can follow the CM link through the defect tracking system and discover that the change must also be backed out of main.c, bar.c, and fram.c. That is, a user may look at a versioned file and then go look at the associated defect record. That record will tell the user who changed the file, who approved the change, why it was changed, when it was changed and the other three files that were changed to repair the defect (to implement the ECO).
This integration between version control and ClearDDTS can also make reading check-in summaries considerably more meaningful. For example, instead of cryptic comments like "fixed bug" or "fixed the pointer problem," ClearDDTS can provide the one line bug description at file check-in time.
Note: Although version control systems can be very useful, they have little or no understanding of the collection of files that constitutes a configuration or product release. This is the primary difference between a version control system and a configuration management system.
Effective configuration integration attempts to answer the following questions:
Unlike a version control system which knows about individual files, but not about the collections of files that constitute a configuration or a release, integrating at the configuration level requires that the CM database be able to produce the list of defect IDs associated with a CM query about a "configuration" or a "release." The CM system already knows all the files within a release and can print out a report of these files. This facility simply needs to be extended to report the defects IDs associated with those files. In general, this is a trivial extension to the CM query facilities, and some CM systems such as ClearCase already have this capability.
Once your CM query facility can report defect IDs (as opposed to file names), those defects can be passed to the defect tracking system and you can easily answer questions posed above. This is shown graphically in Figure 15-2.
Figure 15-2: Configuration Integration
ClearDDTS provides this level of integration and for many CM systems can automatically produce release notes. Given any query that produces a list of defect IDs, ClearDDTS can easily sort the list into enhancement requests, actual defects, remaining unresolved defects, and a summary table of contents. This is done with the cm.relnotes.sh(1) utility.
Process integration requires merging the access control and process control policies of:
This type of integration is often the most difficult because access and process control policies are often a point of contention between CM, DT, and Release Engineering (User). The CM and DT vendor both want to control this process and thereby add value. The user also has unique requirements that need to be met. However, effective process integration will answer the remaining questions posed in the first part of this chapter.
The solution to this problem is an architected exit from the CM system at check in/out time. This exit must be allowed to return a flag that prevents the actual check in/out and issues an error message.
Generally this is not technically difficult. Many CM vendors already supply an architected "trigger" that can be executed before or after a check in/out. Providing such an exit at check in/out time allows the DT system to query the defect tracking database and find out if the defect is in the correct state.
This process is illustrated in Figure 15-3. In this example, the top portion shows a typical CM maintenance process. The user is assigned a defect for repair and wishes to check out a file, go through the normal edit-compile-debug process, and check in the repaired file. A merged CM/ClearDDTS system is shown in the lower portion of the figure.
Figure 15-3: Process Integration
A merged CM/ClearDDTS system provides several exits from the CM system:
Other examples abound. There may be a requirement that a software change be approved by a Change Control Board. Typically such approvals are recorded in a DT (ECO) system or user database. Again, an architected CM exit allows the Change Control Board, DT system, or user to automate and merge their own unique process requirements. The real issue here is that by passing control to all three parties (CM, DT, and the user), the access and process control policies are merged into a cohesive Change Control process.
ClearDDTS provides special exit utilities for the checkin, checkout, and release build processes. These scripts need to be tailored for your particular needs and are discussed briefly in this chapter. See the cm.checkout.sh(1), cm.checkin.sh(1), and cm.release.sh(1), man pages for more information.
The proposed integrated Change Management system (using ClearDDTS with CM systems) described in the previous section can provide the Release Engineering team with the same benefits of control and predictability that the hardware ECO process has provided manufacturing and hardware engineering for many years.
To implement this system, you need to understand how to set up ClearDDTS to work with your Configuration Management (CM) system and how to customize the system for your particular needs.
One advantage of the ClearDDTS change management control system is that it is implemented using template files and Bourne shell scripts that can be easily customized to meet your unique needs. Before looking at these templates and shell scripts, let's walk through an example that illustrates the overall integration (see Figure 15-4).
Figure 15-4: Overview of the Integrated Change
Management Control System
In ClearDDTS, there are four ways to call your CM system: through xddts(1), bugs(1), cm.browser(1), or cm.sh(1). For example, xddts(1) has a drop down menu called CM. From this menu, the user can specify a CM operation such as checkin or checkout. When an operation is selected, a file selection browser pops up and allows the user to select a file or files to perform the action upon. When both the operation and the files have been specified, xddts calls cm.sh to perform the CM action on those files.
The cm.sh utility determines the CM system to use by looking at a bugid that is passed into the utility. Based on the bugid, cm.sh finds the associated ClearDDTS project and the CM system to use for this project (CMsys field of proj.control file).
Once the CM system is determined, cm.sh uses a macro file to load in the commands appropriate for that CM system to perform the desired action. Current macro files appear in the form cm.xxx.sh(1); for example, cm.rcs.sh(1). You should look at these macro files now. They contain lines similar to the following:
CKIN='cd $path; cmsetuser $dirname sccs delget -y"$bugid by $user, \ $Headline" $basefile'
This line creates a macro called CKIN that describes how to checkin a file. Once the macro is loaded, the appropriate command line is executed to check in or check out the specified files. If the CM action is successful, the CM system must then update its own internal database to reflect the CM operation and call the cm2ddts(1) using a post check in/check out trigger. The cm2ddts utility then passes control to some lower level programs to update the ClearDDTS database.
The integration between ClearDDTS and your CM system allows you to merge the access control policies of the CM system, the defect tracker, and the user using an access control trigger from the CM system. This is shown in the right side of Figure 15-4. Before every checkin, a utility called cm.checkin.sh(1) is called and before every checkout a utility called cm.checkout.sh(1) is called. If these utilities return a '0' exit code, the checkin or checkout is allowed to occur. A non '0' exit code causes the checkin or checkout to abort.
This ability to impose an external user-defined (or Change Management defined) access control policy is extremely powerful. For example, at checkout time, cm.checkout.sh(1) can make sure that the defect has been approved for repair and that the engineer checking out the file is the engineer assigned to repair the defect. At checkin time, cm.checkin.sh(1) can make sure the defect has been moved to the Resolved state and that the defect is approved for inclusion in the next release.
You can completely customize the access control and authorization policies to suit your environment by editing these scripts.
To install the ClearDDTS Change Management Control system, all you need to do is define the CM system to use for every project. If you have already defined projects, use the adminbug mprj command to add the CM system. For example:
What Configuration Management System does this project use? sccs
To see a list of valid responses, type a question mark (?).
If you are using Hewlett-Packard's SoftBench, you also need to run the installsb.sh utility (see the man page for more information). This is all that is required.
There are several Bourne shell scripts that support the integration between ClearDDTS and your CM system. ClearDDTS also provides some special utilities to check in and check out files and control the release process. The next sections describe these scripts and utilities.
The cm.tty.sh(1) script is called by bugs(1) as:
cm.tty.sh bugid
The cm.tty.sh(1) script is interactive and is used by the tty user interface to enable file selection and CM processing. The cm.tty.sh script checks out/in files requested from a user menu and then calls the cm.sh utility to perform the CM action. See the cm.tty.sh and cm.sh man pages for more information.
Each CM macro file defines command line macros for checkin, checkout, and other configuration management tasks for a particular CM system. By editing this one file, you can quickly integrate an entire new CM system. (Typically, it takes 30 minutes to write the macros and 30 minutes to test and debug the system.)
For example, the SCCS macro file is located in ~ddts/bin/cm.sccs.sh. Similarly, there is a cm.rcs.sh file for RCS and a cm.clearcase.sh file for ClearCase. Each of these files completely defines how ClearDDTS will invoke the appropriate CM system.
The cm.sccs.sh file calls a utility, cmsetuser(1). This utility must be run suid root. If the utility is run suid root, it allows you to invoke the CM utilities as any user that you specify (subject to many security checks). The utility is delivered in source form in the ~ddts/etc/cmsetuser.c file for your reference.
Most CM systems do not need this functionality; however, if your versioned files are owned by a specific user id, you may find this utility extremely useful for integrating your unique CM needs into ClearDDTS. See the man page cmsetuser(1) for more information.
Most CM systems provide command line functions to check in and check out files. For example, RCS supplies co(1) to check out a file and ci(1) to check in a file. ClearDDTS provides a set of convenience functions to all supported CM systems. These utilities are:
These are all links to the cm.sh utility. The advantage of this utility is that it works for all supported CM systems. Another advantage is that they all require a bugid to be specified. Lastly, the script provides a centralized location for your own customizations.
One extremely useful feature of ClearDDTS' CM integration is that it has the ability to merge the access control policies of the CM system, the bug tracker, and the user. This is done via the checkin and checkout access control scripts. The following scripts are provided:
Check out access control is provided by cm.checkout.sh(1). This script is called before a file is checked out. In this script, you may enforce your own CM check out policy. As shipped, the script has examples that show you how to require that the defect be in a particular state or that it be assigned to a particular engineer. See the cm.checkpout.sh(1) man page and the script itself for more information.
Check in access control is provided by the cm.checkin.sh(1) script. This script is called before a file is checked in. Like cm.checkout.sh, it provides the ability to impose a check in policy on the CM system. See the cm.checkin.sh(1) man page and the script itself for more information.
Most defect tracking and CM systems do not have specific roles defined in their day-to-day usage. However, some large companies or government procurements define special roles and need role support for formal CM. DDTs can support this requirement with the ~ddts/class/<classname>/mprj3.tmpl and ~ddts/class/<classname>/aprj3.tmpl files. These files allow the ClearDDTS administrator to define formal roles and designate the users assigned to those roles.
Some examples of roles might be:
Each of these roles may be formal and have certain permissions in the release process. For example, if a user is a member of a Configuration Control Board, that user may be allowed to make certain state transitions or approve changes to the product.
ClearDDTS supports these roles as part of the project creation and modification process (thus on a per project basis). To activate Role support, you need to modify the ~ddts/class/<classname>/mprj3.tmpl and ~ddts/class/<classname>/aprj3.tmpl files associated with the Class where role support is to be used.
The mprj3.tmpl and aprj3.tmpl files have example code for role support as follows:
################################################################## # # R O L E S U P P O R T # # Add the Roles and the names of the users in those Roles as shown # in the two examples below. You may then use the master.tmpl file # to see if the person is assigned to the role # defined. # # For example a: # # Foo: . # . # whoami # if not oneof -d $~/projects/$Project/proj.control CM-board # bin/echo "You are not on the CM Control Board! >&2 # abort # fi # . # . # placed in the master.tmpl file will cause an error if a user # attempts an action and is not a member of the CM board. #. ################################################################# # # #CM-board: "\n\nThe following relates to CM ROLES.\n\n" # "\nList LOGIN names of users that are members of the\n" # "Configuration Control Board for this project.\n" # "%s" # help aprj12.hlp # if not null # goodusers # fi # #CM-authority: "\nList LOGIN names of users that may approve changes.\n" # "%s" # help aprj12.hlp # if not null # goodusers # fi # #################################################################
The CM-board and CM-authority are the names of the "roles" and the "users" defined for those fields and are entered at project creation or project modification time. These roles and the users assigned to them may be queried in the master.tmpl file using the oneof command shown in the previous example. (See template(5) man page.)
There is no restriction on the number of roles or on the content of the role field. For example, the content of the role field might be a UNIX group instead of a UNIX login id. The oneof command will return true/false as to whether a user is a member of the role. (See also oneof -d in the template(5) man page.)