Clearcase 7.0.0 Managing SW Projects I1167120
Clearcase 7.0.0 Managing SW Projects I1167120
Clearcase 7.0.0 Managing SW Projects I1167120
Version 7.0.0
Windows, UNIX, and Linux
GI11-6712-00
Version 7.0.0
Windows, UNIX, and Linux
GI11-6712-00
Before using this information, be sure to read the general information under Appendix D, Notices, on page 295.
7th edition (May 2006) This edition applies to version 7.0.0.0 of IBM Rational ClearCase (product number 5724G29) and IBM Rational ClearCase LT (product number 5724G31) and to all subsequent releases and modifications until otherwise indicated in new editions. This edition replaces G126-5330-00. Copyright International Business Machines Corporation 1992, 2006. All rights reserved. US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
Contents
Figures . . . . . . . . . . . . . . . ix Tables . . . . . . . . . . . . . . . xi About this book . . . . . . . . . . xiii
Who should read this book . . . . . . . . . xiii Typographical conventions . . . . . . . . . xiii Online documentation . . . . . . . . . . xiv Help system . . . . . . . . . . . . . xiv Reference pages. . . . . . . . . . . . xiv Command syntax . . . . . . . . . . . xiv Tutorial . . . . . . . . . . . . . . xiv PDF manuals . . . . . . . . . . . . xiv Product-specific features . . . . . . . . . . xiv Manual organization . . . . . . . . . . . xv Related information . . . . . . . . . . . xv Rational ClearCase documentation roadmap . . xv Rational ClearCase LT documentation roadmap xvi Contacting IBM Customer Support for Rational software products . . . . . . . . . . . . xvi Downloading the IBM Support Assistant . . . xvii The rebase operation . . . . . . . . . . Recommending the baseline . . . . . . . . . Recommended baselines . . . . . . . . . Monitoring project status . . . . . . . . . . Overview of the UCM integration with Rational ClearQuest . . . . . . . . . . . . . . Associating UCM and Rational ClearQuest objects . . . . . . . . . . . . . . . Schema enabled for UCM . . . . . . . . State types . . . . . . . . . . . . . . Queries in a Rational ClearQuest schema enabled for UCM . . . . . . . . . . . . . . 19 24 25 26 26 26 28 28 28
Part 1. Introduction . . . . . . . . . 1
Chapter 1. Choosing between UCM and base ClearCase . . . . . . . . . . . 3
Differences between UCM and base ClearCase Branching and creating views . . . . . Using components to organize files . . . Creating and using baselines . . . . . Managing activities . . . . . . . . Enforcing development policies . . . . . . . . . . . . . . . . . . . . . . 3 3 4 5 5 5
. 57 . 57 . 59
iii
Default promotion level for recommending baselines . . . . . . . . . . . . . . Default view types . . . . . . . . . . . . Permissions to modify projects and streams . . . Allow all users to modify the project . . . . . Allow all users to modify the stream and its baselines . . . . . . . . . . . . . . Policies for all deliver operations . . . . . . . Do not allow deliver to proceed with checkouts in the development stream . . . . . . . . Rebase before delivery . . . . . . . . . . Policies for deliver operations to nondefault targets Deliver changes from the foundation in addition to changes from the stream . . . . . . . . Allow deliveries that contain changes to missing or non-modifiable components . . . . . . . Allow interproject deliver to project or stream . . Require that all source components are visible in the target stream . . . . . . . . . . . Policies for the UCM integration with Rational ClearQuest . . . . . . . . . . . . . . For submitting records from a Rational ClearCase client . . . . . . . . . . . . . . . For WorkOn . . . . . . . . . . . . . For delivery . . . . . . . . . . . . . For changing activities . . . . . . . . . . Policies and interproject deliveries . . . . . .
64 64 65 65 65 65 65 65 66 67 68 69 69 69 69 70 70 72 73
About setting up the project . . . . . . . . . 85 Creating a project from scratch . . . . . . . . 85 Creating the project VOB . . . . . . . . . 86 Creating components for storing baseline dependencies . . . . . . . . . . . . . 87 Creating components for storing elements . . . 88 Creating the project . . . . . . . . . . . 91 Creating an integration view . . . . . . . 93 Creating and setting an activity in the integration stream (Linux and the UNIX system only) . . . 94 Creating the directory structure . . . . . . . 94 Importing directories and files from outside Rational ClearCase version control. . . . . . 95 Making baselines of newly populated components . . . . . . . . . . . . . 96 Creating the dependency relationships for composite baselines in the project . . . . . . 96 Recommending a baseline for new components 97 Creating a project based on an existing Rational ClearCase configuration . . . . . . . . . . 97 Creating the PVOB from an existing Rational ClearCase configuration . . . . . . . . . 97 Making components from existing VOBs . . . 97 Making a baseline from a label . . . . . . . 98 Creating the project . . . . . . . . . . . 99 Finishing the project configuration . . . . . . 99 Creating a project based on an existing project. . . 99 Capturing final baselines in a composite baseline 99 Creating the project from another project . . . 99 Creating an integration view . . . . . . . 100 Enabling use of the UCM integration with Rational ClearQuest . . . . . . . . . . . . . . 100 To enable a project to work with a Rational ClearQuest user database . . . . . . . . 100 Changing the project to a different Rational ClearQuest user database . . . . . . . . 101 Migrating activities . . . . . . . . . . 101 Setting project policies . . . . . . . . . 101 Assigning activities . . . . . . . . . . 102 Disabling the link between a project and a Rational ClearQuest user database . . . . . 102 Fixing projects that contain linked and unlinked activities . . . . . . . . . . . . . . 103 How the UCM integration with Rational ClearQuest is affected by Rational ClearQuest MultiSite . . . . . . . . . . . . . . 104 Working with IBM Rational Suite (Windows) . . . 105 Creating a development stream for testing baselines . . . . . . . . . . . . . . . 106 To create a development stream . . . . . . 106 Creating a feature-specific development stream . . 107 About creating feature-specific development streams . . . . . . . . . . . . . . 107
109
109 109 110 110 110
About managing a project . . . . . . . . . Adding components . . . . . . . . . . . To add a component to a stream . . . . . . To make a component modifiable within the project . . . . . . . . . . . . . . . To synchronize a view with a new configuration
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
To synchronize a child stream with project modifiable components . . . . . . . . To synchronize a child stream view with new parent stream configuration. . . . . . . To edit the view load rules . . . . . . . Element relocation . . . . . . . . . . Building components . . . . . . . . . . About building components . . . . . . Locking the shared stream . . . . . . . Finding work that is ready to be delivered . Undoing a deliver operation . . . . . . Building and testing the components . . . Creating a new baseline . . . . . . . . . About making a baseline . . . . . . . To make a baseline . . . . . . . . . To unlock the stream . . . . . . . . . Testing the baseline . . . . . . . . . . To test in a separate development stream . . Rebasing the test development stream . . . Fixing problems in baselines . . . . . . Recommending the baseline . . . . . . . To change a baseline promotion level . . . To recommend a baseline or set of baselines . Resolving baseline conflicts . . . . . . . . Conflicts between a composite baseline and an ordinary baseline . . . . . . . . . . Conflicts between composite baselines . . . Monitoring project status . . . . . . . . Viewing baseline histories . . . . . . . Comparing baselines . . . . . . . . . Querying Rational ClearQuest user databases Using Rational ClearCase Reports (Windows systems only) . . . . . . . . . . . Cleaning up the project . . . . . . . . . Removing unused objects . . . . . . . Locking and making obsolete the project and streams . . . . . . . . . . . . .
. 110 . . . . . . . . . . . . . . . . . . . . . . . . . . 111 111 111 112 112 112 113 113 114 114 114 115 116 116 116 117 118 118 119 119 120 120 120 122 122 123 124
. .
. .
. 139 . 140
163
. . . . . . . . . . . 163 163 163 164 164
165 165 166 166 167 168 169 . 170 . 170 . 172
Contents
Historical view defined by a version label . . . Historical view defined by a time rule . . . . Views for project builds . . . . . . . . . . View that uses results of a nightly build . . . Variations that select versions of project libraries View that selects versions of application subsystems . . . . . . . . . . . . . View that selects versions that built a particular program . . . . . . . . . . . . . . Sharing config specs among Linux, the UNIX system, and Windows system . . . . . . . . Path separators . . . . . . . . . . . . Paths in config spec element rules . . . . . Config spec compilation . . . . . . . . .
173 173 174 174 174 175 175 177 177 177 178
Quick start for evaluations . . . . . . . . Editing the configuration file . . . . . . . . Overview of the configuration file . . . . . Locating the configuration file . . . . . . . Configuration file use and format . . . . . Summary of configuration parameters . . . . Connecting Rational ClearCase clients and a Rational ClearQuest user database . . . . . . Establishing the Rational ClearQuest Web interface . . . . . . . . . . . . . . Defining the Rational ClearQuest user database and database set . . . . . . . . . . . Establishing the schemas . . . . . . . . Establishing Rational ClearCase MultiSite support . . . . . . . . . . . . . . About code page conversion . . . . . . . Testing the configured connections . . . . . Troubleshooting the configured connections . . Making policy choices . . . . . . . . . . Allowing multiple associations . . . . . . Controlling query usage . . . . . . . . . Allowing use of the graphic user interface (GUI) Forcing checkin success before committing associations . . . . . . . . . . . . . Enhancing performance . . . . . . . . . . Using the association batch feature . . . . . Controlling and using automatic associations Debugging and analyzing operations . . . . . Generating operational information . . . . . Testing the integration . . . . . . . . . Customizing the integration . . . . . . . . About the Integration Query wizard . . . . . . To start the Integration Query wizard . . . .
200 200 200 201 201 201 203 203 204 205 207 207 208 209 209 209 210 211 211 211 211 214 215 215 216 217 217 217
Chapter 13. Setting up the base ClearCase integration with Rational ClearQuest . . . . . . . . . . . . 191
Overview of the base ClearCase integration with Rational ClearQuest . . . . . . . . . . What the integration does . . . . . . . How the integration works . . . . . . . Policy regarding customization and support . Checklist of configuration steps . . . . . Planning for the base ClearCase integration with Rational ClearQuest . . . . . . . . . . Setting up the Rational ClearQuest user database for base ClearCase . . . . . . . . . . . Adding Rational ClearCase definitions to a Rational ClearQuest schema . . . . . . Setting policies and installing triggers in a ClearCase VOB . . . . . . . . . . . . Using a shared configuration file and triggers Installing triggers in a VOB on Linux and the UNIX system . . . . . . . . . . . To start the Rational ClearQuest Integration Configuration tool . . . . . . . . . . To specify multiple record types . . . . . To list triggers installed in a VOB . . . . . . . . . 191 191 191 194 195
Chapter 15. Using element types to customize file element processing . . 229
About element types and file processing . . File types in a typical project . . . . . . How element types are assigned . . . . . Sample magic file on the UNIX system . . Sample Magic File on the Windows system Element types and type managers . . . . Other applications of element types . . . Predefined and user-defined element types . Predefined and user-defined type managers . Creating a new type manager (the UNIX system) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229 229 230 230 230 230 231 232 232
. 232
vi
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
Writing a type manager program (the UNIX system) . . . . . . . . . . . . . Type manager for manual page source files . . Creating the type manager directory. . . . Inheriting methods from another type manager Implementing a new compare method . . . Icon use by GUI browsers . . . . . . . .
Moving view profile information to UCM . Preparing your view profile project . . Moving the view profile information .
. . .
. . .
Chapter 16. Using Rational ClearCase throughout the development cycle . . 241
About using Rational ClearCase throughout the development cycle . . . . . . . . . . . Project overview . . . . . . . . . . . Development strategy . . . . . . . . . Project manager and Rational ClearCase administrator . . . . . . . . . . . Use of branches . . . . . . . . . . Creating project views . . . . . . . . Creating branch types . . . . . . . . . Creating standard config specs . . . . . . Creating, configuring, and registering views . . Development begins . . . . . . . . . . Techniques for isolating your work . . . . Creating baseline 1 . . . . . . . . . . Merging two branches . . . . . . . . Integration and test . . . . . . . . . Labeling sources . . . . . . . . . . Removing the integration view . . . . . Merging ongoing development work . . . . Preparing to merge . . . . . . . . . Merging work . . . . . . . . . . . Creating Baseline 2 . . . . . . . . . . Merging from the r1_fix branch . . . . . Preparing to merge from the major branch . Merging from the major branch . . . . . Decommissioning the major branch . . . . Integration and test . . . . . . . . . Final validation: creating Release 2.0 . . . . Labeling sources . . . . . . . . . . Restricting use of the main branch . . . . Setting up the test view . . . . . . . . Setting up the trigger to monitor bug-fixing . Fixing a final bug . . . . . . . . . . Rebuilding from labels . . . . . . . . Wrapping up . . . . . . . . . . . . 241 . 241 . 243 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243 243 245 245 245 245 246 246 247 247 247 248 248 248 249 250 251 252 252 253 254 254 254 255 255 255 256 256 257 257
Contents
vii
viii
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
Figures
1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14. 15. 16. 17. 18. 19. 20. 21. 22. 23. 24. 25. 26. 27. 28. 29. 30. 31. 32. Branching hierarchy in base ClearCase . . . . 4 Project manager, developer, and integrator work flows . . . . . . . . . . . . . 10 VOB containing multiple components . . . . 12 Baselines of two components . . . . . . . 13 Composite baseline . . . . . . . . . . 14 Baseline predecessors and descendants 15 Rebase operation . . . . . . . . . . . 19 Advance rebase operation . . . . . . . . 21 A test stream to stabilize a baseline . . . . 22 Promoting baselines . . . . . . . . . . 25 Association of UCM and Rational ClearQuest objects in integration . . . . . . . . . 27 Components used by Transaction Builder project . . . . . . . . . . . . . . 31 Storing multiple components in a VOB 32 Using a read-only component . . . . . . 34 Using a feature-specific development stream 35 Stream relationships. . . . . . . . . . 37 Stream hierarchy with multiple levels . . . . 38 Direct stream relationships for alternate target deliver operations . . . . . . . . . . 39 Indirect stream relationships for alternate target deliver operations . . . . . . . . 40 Alternate target intra-project deliver operation 41 Sharing changes by a rebase operation . . . 42 Sharing changes by an alternate target deliver operation . . . . . . . . . . . . . 43 Rebase operation and alternate target deliver operation . . . . . . . . . . . . . 44 Using a system-level composite baseline 46 Loosely coupled relationship between baselines . . . . . . . . . . . . . 47 Tightly coupled relationship between baselines 48 Changing a regular composite to a pure composite baseline . . . . . . . . . . 50 Creation of a composite baseline descendant 50 Related projects sharing one PVOB . . . . . 54 Using one PVOB as an administrative VOB for multiple PVOBs . . . . . . . . . . . 55 Multiple PVOBs linked to the same Rational ClearQuest user database . . . . . . . . 58 One schema repository for multiple Rational ClearQuest user databases . . . . . . . 59 33. 34. 35. 36. 37. 38. 39. 40. 41. 42. 43. 44. 45. 46. 47. 48. 49. 50. 51. 52. 53. 54. 55. 56. 57. 58. 59. 60. 61. 62. 63. 64. 65. 66. Component modifiability and visibility 63 Default and nondefault deliver targets in a stream hierarchy . . . . . . . . . . . 66 Delivering changes made in a foundation baseline . . . . . . . . . . . . . . 68 State transitions of UCM-enabled BaseCMActivity record type . . . . . . . 79 A test stream to stabilize a baseline . . . . 117 Composite baselines with the same component . . . . . . . . . . . . 120 Composite baselines with a conflict . . . . 121 Composite baselines with an override baseline . . . . . . . . . . . . . 121 An organization for release-oriented projects 142 Structure for component-oriented projects 144 Composite baselines representing subsystems 145 Managing a follow-on release . . . . . . 148 Alternate target inter-project deliver operation 149 Incorporating a patch release . . . . . . 150 Baselines distributed to a different project 152 Making a change to an old version . . . . 168 Multiple-level auto-make-branch . . . . . 169 Development config spec versus QA config spec. . . . . . . . . . . . . . . 171 Checking out a branch of an element 172 Requirements tracing . . . . . . . . . 186 Versions involved in a typical merge 220 Rational ClearCase merge algorithm . . . . 220 Selective merge from a subbranch . . . . . 223 Removing the contributions of some versions 224 Merging a new release of an entire source tree . . . . . . . . . . . . . . . 226 Project plan for Release 2.0 development 242 Development milestones: evolution of a typical element . . . . . . . . . . . 244 Creating baseline 1 . . . . . . . . . . 247 Updating major enhancements development 249 Merging Baseline 1 changes into the major branch . . . . . . . . . . . . . . 251 Baseline 2 . . . . . . . . . . . . . 252 Element structure after the pre-Baseline-2 merge . . . . . . . . . . . . . . 254 Final test and release . . . . . . . . . 255 Run-time processing sequence . . . . . . 267
ix
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
Tables
1. 2. 3. 4. 5. 6. 7. Recommended directory structure for components . . . . . . . . . . . . 33 State Types in UCM-Enabled Schema . . . . 78 Environment variables required for integration 83 Queries in a UCM-enabled schema . . . . 124 Configuration checklist . . . . . . . . 195 Configuration parameters summary . . . . 202 Files used in a typical project . . . . . . 229 8. 9. 10. 11. View profile features and their UCM counterparts . . . . . . . . . . . . Parameters supplied with Rational ClearCase Reports . . . . . . . . . . . . . Fields modifiers . . . . . . . . . . . Field type supplied with Rational ClearCase Reports . . . . . . . . . . . . . 262 271 273 273
xi
xii
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
Typographical conventions
This manual uses the following typographical conventions: v ccasehomedir represents the directory into which Rational ClearCase, Rational ClearCase LT, or Rational ClearCase MultiSite has been installed. By default, this directory is /opt/rational/clearcase on the UNIX system and C:\Program Files\Rational\ClearCase on Windows. v cquest-home-dir represents the directory into which Rational ClearQuest has been installed. By default, this directory is /opt/rational/clearquest on the UNIX system and C:\Program Files\Rational\ClearQuest on Windows. v Bold is used for names the user can enter; for example, command names and branch names. v A sans-serif font is used for file names, directory names, and file extensions. v A serif bold font is used for GUI elements; for example, menu names and names of check boxes. v Italic is used for variables, document titles, glossary terms, and emphasis. v A monospaced font is used for examples. Where user input needs to be distinguished from program output, bold is used for user input. v Nonprinting characters appear as follows: <EOF>, <NL>. v Key names and key combinations are capitalized and appear as follows: Shift, Ctrl+G. v [ ] Brackets enclose optional items in format and syntax descriptions. v { } Braces enclose a list from which you must choose an item in format and syntax descriptions. v | A vertical bar separates items in a list of choices. v ... In a syntax description, an ellipsis indicates you can repeat the preceding item or line one or more times. Otherwise, it can indicate omitted information. Note: In certain contexts, you can use ... within a pathname as a wildcard, similar to * or ?. For more information, see the wildcards_ccase reference page.
xiii
v If a command or option name has a short form, a slash ( / ) character indicates the shortest legal abbreviation. For example:
lsc/heckout
Online documentation
This section describes how you can access the online documentation for Rational ClearCase products.
Help system
To access the Help, use the Help menu, the Help button, or the F1 key. To display the contents of the online documentation set, perform one of the following actions: v On Linux or the UNIX system, type cleartool man contents . v On Windows, click Start > Programs > IBM Rational > IBM Rational ClearCase > Help. v On Windows, Linux, or the UNIX system, to display contents for Rational ClearCase MultiSite, type multitool man contents. v Use the Help button in a window to display information about that window, or press F1.
Reference pages
To access reference pages from the IBM Rational ClearCase Command Reference, use the cleartool man and multitool man commands. For more information, see the man reference page in the IBM Rational ClearCase Command Reference.
Command syntax
To access online documentation by using the command line, use the help command option or the cleartool help command.
Tutorial
The tutorial for a Rational ClearCase product provides a step-by-step tour of the important features of the product. To start the tutorial, perform one of the following actions: v On Linux or the UNIX system, type cleartool man tutorial . v On Windows, click Start > Programs > IBM Rational > IBM Rational ClearCase > ClearCase Tutorial.
PDF manuals
To access PDF manuals for Rational ClearCase products, use the command line to navigate to the following directories: v On Linux or the UNIX system, ccasehomedir/doc/books v On Windows, ccasehomedir\doc\books
Product-specific features
This manual describes Rational ClearCase and Rational ClearCase LT. Rational ClearCase LT does not include all features available in Rational ClearCase. In addition, some user interfaces differ in the two environments. This manual uses the following label to call out differences: Product Note. When the term Rational ClearCase is used outside of a Product Note section, it refers to both products.
xiv
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
Manual organization
The manual is divided into the following parts: v Part 1, Introduction. An introductory part highlights the features of UCM and base ClearCase. v Part 2, Working in UCM. Read this part if you plan to use UCM to implement your teams development process. v Part 3, Working in base ClearCase. Read this part if you plan to use the base ClearCase features to implement a customized development process for your team. Several appendices carry information of special interest and legal notices.
Project Management Guide to Managing Software Projects More Information Command Reference Online documentation Help files
Administration Installation and Upgrade Guide Administrator's Guide (Rational ClearCase/ Rational ClearCase LT) Administrator's Guide (Rational ClearCase MultiSite) Platforms Guide (Rational ClearCase)
xv
Software Development
Administration
xvi
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
For more information about ISA, including instructions for downloading and installing ISA and product plug-ins, go to the ISA Software Support page. IBM Support Assistant: http://www.ibm.com/software/support/isa/
xvii
xviii
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
Summary of changes
This edition adds material describing composite baselines, the usage of multiple UCM projects, and the set up of the base ClearCase integration with Rational ClearQuest. v In Chapter 2, new sections under Starting from a baseline on page 13, describe composite baselines, baselines and their uses, and baselines and streams. Under Making a baseline on page 19, new sections describe the rebase operation, directions of rebase operations (advance, revert, and lateral), and rules for rebase operations. v In Chapter 3, the following information is new: Under Identifying read-only components on page 33, new text describes modifiability of components without a VOB root directory. Under Choosing a stream strategy on page 34, new sections describe stream configurations, baseline contents, and stream relationships. Under Pure composite baselines on page 47, new sections describe dependency relationships in composite baselines, pure composite baselines and whether to use them, and creation of composite baseline descendants. Under Multiple PVOBs and feature levels on page 56, a new section describes feature levels in environments with multiple PVOBs. Under Using mergetype to manage merge behavior on page 56, a new mergetype, copy, is described. In Planning how to use the UCM integration with Rational ClearQuest on page 57, under Use of multiple user databases on page 59, the need for unique names is described. v In Chapter 4, under Policies for the UCM integration with Rational ClearQuest on page 69, two new policies are described: Disallow submitting records from ClearCase client on page 69 and Allowed record types on page 70. v In Chapter 5, under Creating users and adding credentials on page 82, a new section describes creating and maintaining credentials for Rational ClearQuest database sets used in the UCM integration. v In Chapter 7, the following information is new: Under Adding components on page 109, a new section, Element relocation on page 111, describes the use of the mkelem_cpver.pl script. Under Resolving baseline conflicts on page 120, new information is added to the section Conflicts between composite baselines on page 120. v In Chapter 8, under Supported triggers on page 129, lock and unlock are added. Also, under Using the same script on page 132, the invocation of ratlperl is described. v Chapter 9, in Project uses on page 141, has new information that describes release-oriented and component-oriented projects and composite baselines in each type, and describes bootstrap projects. v In Chapter 12, under Using the same script on page 189, the invocation of ratlperl is described. v Chapter 13 consolidates information from multiple sources to describe the base ClearCase integration with Rational ClearQuest. Planning for the base ClearCase integration with Rational ClearQuest on page 196
Copyright IBM Corp. 1992, 2006
xix
Setting up the Rational ClearQuest user database for base ClearCase on page 196 Editing the configuration file on page 200 Connecting Rational ClearCase clients and a Rational ClearQuest user database on page 203 Making policy choices on page 209 Enhancing performance on page 211 Debugging and analyzing operations on page 215 v In Chapter 14, under Common merge scenarios on page 222, a new procedure is described in Merging a new release of an entire source tree on page 225 for using clearfsimport to accomplish the merge.
xx
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
Part 1. Introduction
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
4
Figure 1. Branching hierarchy in base ClearCase
As project manager, you tell developers which rules to include in their config specs so that their views access the appropriate set of versions. UCM uses branches also, but you do not have to manipulate them directly because it layers streams over the branches. A stream is a Rational ClearCase object that maintains a list of activities and baselines and determines which versions of elements appear in a developers view. In UCM, a multiple-stream project contains one integration stream, which records the shared set of elements of the project, and multiple development streams in which developers work on their parts of the project in isolation from the team. The project integration stream uses one branch. Each development stream uses its own branch. You can create a hierarchy of development streams, and UCM creates the branching hierarchy to support those streams. Although most customers use Rational ClearCase to implement a parallel development environment, UCM and base ClearCase also support serial development. In base ClearCase, you implement a serial development environment by having all developers work on the same branch. In UCM, you create a single-stream project, which contains one stream, the integration stream. All developers work on the integration stream rather than on development streams. Serial development is intended only for very small project teams whose developers work together closely. As project manager of a UCM project, you need not write rules for config specs. Streams configure developers views to access the appropriate versions on the appropriate branches.
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
By organizing related files and directories into components, you can view your system as a small number of identifiable components, rather than one large set of directories and files.
Managing activities
In base ClearCase, you work at the version and file level. UCM provides a higher level of abstraction: activities. An activity is a Rational ClearCase object that you use to record the work required to complete a development task. For example, an activity may be to change a graphical user interface (GUI). You may need to edit several files to make the changes. UCM records the set of versions that you create to complete the activity in a change set. Because activities appear throughout the UCM user interface, you can perform operations on sets of related versions by identifying activities rather than having to identify numerous versions. Because activities correspond to significant project tasks, you can track the progress of a project more easily. For example, you can determine which activities were completed in which baselines. If you use the UCM integration with IBM Rational ClearQuest, you gain additional project management control, such as the ability to assign states and state transitions to activities. You can then generate reports by issuing queries such as show me all activities assigned to Pat that are in the Ready state.
v They minimize project build problems by identifying conflicting changes made by multiple developers as early as possible. v They establish greater communication among team members. These are examples of common development policies: v Developers must synchronize their private work areas with the project recommended baseline before delivering their work to the project shared work area. v Developers must notify other team members by e-mail when they deliver work to the project shared work area. In base ClearCase, you can use tools such as triggers and attributes to create mechanisms to enforce development policies. UCM includes a set of common development policies, which you can set through the graphic user interface (GUI) or command-line interface (CLI). You can set these policies at the project and stream levels. In addition, you can use triggers and attributes to create new UCM policies.
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
Figure 2 illustrates the connection between the project management, development, and integration cycles. This manual describes the steps performed by project managers and integrators. See Developing Software online help for information about the steps performed by developers.
Project Manager
Create project
Establish policies
Developer
Join a project
Integrator
Build components
Make baselines
Recommend baselines
10
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
Create project
Establish policies
Create a PVOB
Create components
Create baselines
To create and set up a project, you must perform the following tasks: v Create a repository for storing project information v Create components that contain the set of files that the developers work on v Create baselines that identify the versions of files with which the developers start their work To use the UCM integration with Rational ClearQuest, you must perform additional setup tasks.
Creating a PVOB
File elements, directory elements, derived objects, and metadata are stored in a Rational ClearCase repository called a versioned object base (VOB). In UCM, each project must have a project VOB (PVOB). A PVOB is a special kind of VOB that stores UCM objects, such as projects, activities, and change sets. A PVOB must exist before you can create a project. Check with your site Rational ClearCase administrator to see whether a PVOB has already been created. For details on creating a PVOB, see Creating the project VOB on page 86.
11
The directory and file elements of a component reside physically in a VOB. The component object resides in a PVOB. Within a component, you organize directory and file elements into a directory tree (see Figure 3).
PVOB VOB
GUI Admin
Reports
The directory trees for the GUI, Admin, and Reports components appear directly under the VOB root directory. You can convert existing VOBs or directory trees within VOBs into components, or you can create a component from scratch. For details on creating a component from scratch, see Creating components for storing elements on page 88. For details on converting a VOB into a component, see To make a VOB into a component on page 97.
Stream hierarchies
In the basic UCM process, the integration stream is the only shared work area for the entire project. In a multiple-stream project, you may want to create additional shared work areas for developers who are working together on specific parts of the project. You can accomplish this by creating a hierarchy of development streams. For example, you can create a development stream and designate it as the shared
12
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
work area for developers working on a particular feature. Developers then join the project at the development stream level (rather than at the integration stream) and create their own development streams and views under the development stream for this feature. The developers deliver work to and rebase their streams to recommended baselines in the development stream for the feature. See Choosing a stream strategy on page 34 for details on development stream hierarchies.
Single-stream projects
Although UCM is typically used to implement a parallel development environment, UCM also supports serial development by letting you create a single-stream project. A single-stream project contains one stream, the integration stream. All developers work on the integration stream rather than on development streams. Developers have their own views that are attached to the integration stream. Serial development should be used only for very small project teams whose developers work together closely. See Choosing a stream strategy on page 34 for details on single-stream projects.
Version
Version
Baselines named BL1 and BL2 in the integration stream identify the versions in component A and component B, respectively. When developers join the project, they populate their work areas with the versions of directory and file elements represented by the recommended baselines of the project. Alternatively, developers can join the project at a feature-specific
Chapter 2. Understanding UCM
13
development stream level, in which case they populate their work areas with the development streams recommended baselines. This practice ensures that all members of the project team start with the same set of files.
Composite baselines
If your project team works on multiple components, you may want to use a composite baseline. A composite baseline selects baselines in other components (see Figure 5).
Component A
Component Proj
Baseline BL1
PB1
Component B
The PB1 composite baseline selects baselines BL1 and BL2 of components A and B, respectively. The Proj component does not contain any elements of its own. It contains only the composite baseline that selects the recommended baselines of the project components. By using a composite baseline in this manner, you can identify one baseline to represent multiple baselines, and, by extension, the entire project.
14
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
prog.c Bl1 1
lib.c 1
num.h 1
msg.h 1
util.h 1
Bl2
2 3
2 3
Bl3
In Figure 6, baseline BL1 is the predecessor of baseline BL2 and baseline BL2 is a descendant of baseline BL1. When baseline BL2 was created, there were new versions of prog.c, msg.h, and util.h, but for the files lib.c and num.h, baseline BL2 falls back to the baseline BL1 versions. Similarly, baseline BL3 is a descendant of baseline BL2; and baselines BL1 and BL2 are predecessors of baseline BL3. Baseline BL3 captures changes made after baseline BL2 was created, but it uses the baseline BL1 version of num.h and the baseline BL2 version of msg.h. Because version 4 of msg.h is checked out, it is not included in baseline BL3. In the relationship among baselines, a descendant contains its predecessors so that, for example, all changes captured in baseline BL2 are also in baseline BL3. The relationship between a baseline and a component is very similar to the relationship between a version and an element. For example, baselines exist in streams, but versions exist on branches. Both baselines and versions have predecessors. Baselines have the following uses: v Record work done and mark milestones. v Define stream configurations. v Provide access to delivered work.
15
Setting policies
Project Manager
Create project
Establish policies
UCM includes a set of policies that you can set to enforce development practices among members of the project team. By setting policies, you can improve communication among project team members and minimize the problems you may encounter when integrating their work. For example, you can set a policy that requires developers to update their work areas with the latest recommended baseline of the project before they deliver work. This practice reduces the likelihood that developers will need to work through complex merges when they deliver their work. For a description of all policies you can set in UCM, see Chapter 4, Setting policies, on page 63. You can set policies on projects and streams. In addition to the set of policies that UCM provides, you can create triggers on UCM operations to enforce customized development policies. See Chapter 8, Using triggers to enforce UCM development policies, on page 129 for details about creating triggers.
16
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
Assigning work
Project Manager
Create project
Establish policies
This task is optional and is possible only if you use the UCM integration with Rational ClearQuest. As project manager, you are responsible for identifying and scheduling the high-level tasks for your project team. In some organizations, the project manager creates activities and assigns them to developers. In other organizations, the developers create their own activities. See Assigning activities on page 102 for details on creating and assigning activities in a Rational ClearQuest user database.
Build components
Make baselines
Recommend baselines
In your role as project integrator, you are responsible for building the work delivered by developers, creating baselines, and testing those baselines. When you make baselines in the integration stream, you lock the stream to prevent developers from delivering work. This practice ensures that you work with a static set of files. It is acceptable to perform quick validation tests of the new baselines in the integration stream. However, you should not lock the integration stream for a long time because you will create a backlog of deliveries. To perform more rigorous testing, such as regression testing, you should create a development stream to be used solely for stabilizing and testing baselines. See Creating a development stream for testing baselines on page 106 for details on creating a testing stream.
17
Building components
Integrator
Build components
Make baselines
Recommend baselines
Before you make new baselines, build the components in the integration stream by using the current baselines plus any work that developers have delivered to the stream since you created the current baselines. Lock the integration stream before you build the components to ensure that you work with a static set of files. If the build succeeds, you can make baselines that select the latest delivered work. If your project uses feature-specific development streams, perform this task on those streams and on the integration stream.
18
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
Making a baseline
Integrator
Build components
Make baselines
Recommend baselines
To ensure that developers stay in sync with each others work, make new baselines regularly. A new baseline includes the work developers have delivered to the parent stream since the last baseline. If your project uses feature-specific development streams, perform this task on those streams and on the integration stream. In some environments, the lead developer working on a feature may assume the role of integrator for a feature-specific development stream.
Integration stream
Rebasing
BL1
Figure 7. Rebase operation
BL2
A component in Pats development stream is configured with baseline BL1. A rebase operation changes the configuration of the stream to baseline BL2 from the
Chapter 2. Understanding UCM
19
integration stream. The rebase operation merges files and directories from the integration stream or feature-specific development stream to the development stream. A rebase operation reconfigures a stream by adding, dropping, or replacing one or more of the stream foundation baselines. It is typically used to advance a streams configuration, that is, to replace its current foundation baselines with descendant ones. For more information about baselines, see Baselines and their uses on page 14. Foundation baselines of the target stream are replaced with the set of recommended baselines from the source stream. If an element in the stream being rebased contains any changes, the rebase operation merges the changes into the latest version of that element in the stream, thereby creating a new version. All such new versions are captured in the change set of the integration activity that the rebase operation creates. The rebase operation changes the foundation baselines of a stream. Baselines provide a configuration that includes delivered work. If a specific stream must use work that has been included in a baseline in an appropriate stream, you rebase the specific stream to the desired baseline. In a rebase operation, a developer selects one or more baselines to add or drop from the configuration of the stream. Just as a view can only select one version of an element, a stream can only include one baseline for each component. If more than one baseline were allowed in a stream foundation for a particular component, the selection of versions in that component would be ambiguous. During a rebase operation, the specified baselines replace the current baselines, if any, for their components. Changes that have been made on the stream are merged into new versions, if necessary. A deliver operation always involves merging elements. A rebase operation only involves merging if elements that have been modified in the stream also have new versions selected by the new baseline.
20
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
a1, a2, a3
b1, b2, b3
PA.BL2
Development streams D1 and D2 deliver work (activities a1, a2, a3, b1, b2, and b3) to the integration stream. In the integration stream, a descendant baseline PA.BL2 is made to capture the work. To include the new work in their configurations, streams D1 and D2 rebase to descendant baseline PA.BL2. Restrictions on advancing rebase operations occur when the descendant baseline is not from the parent stream. In a rebase operation, you can select a baseline from any stream. For example, you can select a baseline from a stream that is a descendant of the stream foundation that is in a stream that is not its parent stream. Thus, a development stream could rebase to a baseline created in a sibling development stream. Therefore, the rebasing stream could acquire work that has not been delivered to the parent stream. If several streams were allowed to deliver the same work, there would be confusion during the merge operation. (Alternative target delivery is a special case, and a project manager can set policies to allow a stream to accept changes that did not originate in the delivering stream). A common example of an advance rebase operation occurs when a project uses a test stream (see Figure 9). The project integrator creates the baseline PA.BL1 for a milestone. The work to stabilize the code in the baseline is done on the test stream DS that is dedicated to this task. Because the project A integration stream can have more activities delivered as the baseline PA.BL1 is being tested, the integration stream is not used. The test stream is isolated from deliver operations ongoing in the parent stream, the project A integration stream.
21
Project A Integration stream PA.BL0 DS (test stream) PA.BL1 PA.BL1 a1, a2, a3 PA.BL1.S PA.BL2 PA.BL0 D1
D1.BL1 PA.BL3
Although the PA.BL1.S baseline is a descendant of their current foundation baseline PA.BL0, development streams like D1 are not allowed to rebase to it. If this rebase operation were allowed, the development streams could deliver the build stabilization work before stream DS does. Therefore, the test stream DS must first deliver its work in the baseline PA.BL1.S to the parent of the development streams, the project A integration stream. When the work from test stream DS is contained in the parent stream and the baseline that contains that work is ready to be released, the project integrator can recommend the baseline. Then the development streams can rebase to the baseline PA.BL1.S from the test stream. Tip:: The deliver operation changes the relationship between baselines in a stream. In Figure 9, when a new baseline PA.BL2 is created in the project A integration stream, it becomes a descendant of PA.BL1 as with any baseline, but it also becomes a descendant of PA.BL1.S from the test stream. Because baseline PA.BL1.S was delivered to the integration stream, baseline PA.BL2 contains baseline PA.BL1.S, which is a requirement of the predecessor and descendant relationship.
22
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
23
used to revert a baseline (see Revert rebase operations on page 22); to add or drop a component in the configuration of a stream; and to switch to a baseline that is neither an ancestor nor a descendant of the current foundation (see Lateral rebase operations on page 23). When you advance, revert, drop, or switch a baseline, you need to satisfy the general rules and the following additional ones: v To advance the configuration of a stream, the new baseline must contain the current foundation baseline. v To revert or drop a baseline for a component in a stream, one of the following conditions must be met: The component is nonmodifiable. The component is modifiable but has not been modified in the stream, and the component is not in the configuration of any child streams. v To switch to a baseline that is neither an ancestor nor a descendant of the current foundation, one of the following conditions must be met: The component is nonmodifiable. The component is modifiable but has not been modified in the stream, and the component is not in the configuration of any child streams. The component has been modified, but the new baseline contains the current foundation baseline; and the component is not in the configuration of any child streams. These rules ensure that any changes made in a stream are not lost when the configuration changes.
Build components
Make baselines
Recommend baselines
As work on your project progresses and the quality and stability of the components improve, change the baseline promotion level attribute to reflect important milestones (see Figure 10).
24
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
Production Bl8
The promotion level attribute typically indicates a level of testing. For example, Figure 10 shows the evolution of baselines through three levels of testing; the BL8 baseline is ready for production.
Recommended baselines
When baselines pass the level of testing required to be considered stable, make them the recommended set of baselines. Developers then rebase their development streams to the recommended baselines. You can set a policy that requires developers to rebase their development streams to the set of recommended baselines before they deliver work. This policy helps to ensure that developers update their work areas whenever a baseline passes an acceptable level of testing. Every stream has foundation baselines. The foundation baselines of an integration stream are its default recommended baselines. A development stream has no default recommended baselines. A stream can recommend a baseline if certain rules are true. These rules establish consistency in child streams. If a child stream rebases to the new recommended baseline and subsequently delivers activities to its default target, only activities created on the development stream need to be delivered. The rules also prevent a stream from reverting to the configuration of a development stream that has rebased to baselines that are ahead of the current recommended baselines.
Chapter 2. Understanding UCM
25
For more information about recommending baselines, see Recommending the baseline on page 118.
Create project
Establish policies
Several tools are provided to help you track the progress of your project: v The UCM integration with Rational ClearQuest includes some Rational ClearQuest queries, which you can use to retrieve information about activities in your project. For example, you can see all activities that are in an active state or all active activities assigned to a particular developer. In addition, you can create customized Rational ClearQuest queries. v The Compare Baselines GUI compares any two baselines of a component and displays the differences in activities and versions associated with each baseline. You can use this feature to determine when a particular feature was included in a baseline. v The Component Tree Browser (Windows only) displays the baseline history of a component. The GUI includes a feature that lets you filter the display so that you see only specified streams or baselines at or above a specified promotion level. v The Rational ClearCase Report Builder and Report Viewer (Windows only) let you generate and view reports specific to your project environment. The Report Builder provides a set of reports organized by Rational ClearCase object, such as project, stream, element, and view. In addition, you can customize the procedures used to generate and display reports. For more information about using these tools, see Monitoring project status on page 122.
26
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
PVOB
Project 1
Activity 1
Project 2
The links between the project and activity objects in the PVOB and the record objects in the Rational ClearQuest user database show the bidirectional linking of these objects. When you enable a project to link to a Rational ClearQuest user database, the integration stores a reference to that database in the projects PVOB. Every project that is enabled for Rational ClearQuest is linked to a project record of record type UCM_Project in the Rational ClearQuest user database. Every activity in a project that is enabled for Rational ClearQuest is linked to a record in the database. An activitys headline is linked to the headline field in its corresponding Rational ClearQuest record. If you change an activitys headline in a Rational ClearCase repository, the integration changes the headline in the Rational ClearQuest user database to match the new headline, and the reverse is also true. Similar to the linking of the activity headline, an activitys ID is linked to the ID field in its Rational ClearQuest record. It is possible for a Rational ClearQuest user database to contain some records that are linked to activities and some records that are not linked. In Figure 11, ClearQuest User Database 1 contains a record that is not linked to an activity. You may encounter this situation if you have a Rational ClearQuest user database in place before you adopt UCM. As you create activities, the integration creates corresponding Rational ClearQuest records. However, any records that existed in
27
that user database before you enabled it to work with UCM remain unlinked. In addition, UCM does not link a record to an activity until a developer sets work to that record.
State types
States are used to track the progress of change requests from submission to completion. A state represents a particular stage in this progression. Each movement from one state to another is a state transition. The UCM integration with Rational ClearQuest uses a particular state transition model. To implement this model, the integration uses state types. A state type is a category of states that UCM uses to define state transition sequences. You can define as many states as you want, but all states in a UCM-enabled record type must be based on one of the following state types: v Waiting v Ready v Active v Complete Multiple states can belong to the same state type. However, you must define at least one path of transitions between states of state types as follows: Waiting to Ready to Active to Complete. For details on state types, see Setting state types on page 78.
28
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
29
Amount of integration
Determine the relationships between the various components. Related components that require a high degree of integration belong to the same project. By including related components in the same project, you can build and test them together frequently, thus avoiding the problems that can arise when you integrate components late in the development cycle.
30
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
Figure 12 shows the initial set of components planned for the Transaction Builder system. A team of 30 developers work on the system. Because a high degree of integration between components is required, and most developers work on several components, the project manager included all components in one project. For information about using multiple UCM projects for your development, see Project uses on page 141 and Using a mainline project on page 142.
Customer GUI
Admin GUI
Reporting
Modeler
Admin
Security
Organizing components
After you map your system architecture to an initial set of components and determine which projects will access those components, refine your plan by performing the following tasks: v Decide how many VOBs to use v Identify any additional components v Define the component directory structures v Identify read-only components
31
v If you make a component at the VOB root directory, that VOB can never contain more than that one component. For this reason, create components one level beneath the VOB root directory. Doing so allows you to add components to the VOB in the future. v Whether you make a component at the level of or one level beneath the VOB root directory, the component name must be unique within its PVOB.
VOB
/Dev
GUI
Admin
Reports
Libs
Figure 13. Storing multiple components in a VOB
32
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
33
One project team may be responsible for maintaining a component, and another project team may use that component to build other components (see Figure 14).
Project A Project B
cm_libs modifiable
cm_libs read-only
The Project A team members maintain a set of library files in the cm_libs component. Project B team members refer to some of those libraries when they build their components. In Project A, the cm_libs component is modifiable. In Project B, the same component is read-only. With respect to the cm_libs component, Project A and Project B have a producer-consumer relationship. For more information, see Modifiable components on page 63. Because making a baseline of a component to change its members modifies the related component, the related component that is used for a composite baseline should be modifiable. A component without a VOB root directory (that is, one used to make a pure composite baseline) should be modifiable except in the following circumstances: v The component is to hold only read-only components as members. v No baseline is ever to be made in the component. You cannot make a baseline of a read-only component without a VOB root directory.
34
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
Stream hierarchies
As an alternative to using the integration stream as the sole shared work area for the project, you can use the UCM development stream hierarchy feature to create multiple shared work areas. This approach supports a project organization that consists of small teams of developers where each team develops a specific feature in feature-specific development streams (see Figure 15).
Integration
Permissions_dev 1 1
2 X
Pat's_dev
Pedro's_dev
The project manager created a development stream called Permissions_dev for two developers who are working on a permissions feature. The developers, Pat and Pedro, joined the project at the Permissions_dev level rather than at the integration stream level. They deliver completed work to the Permissions_dev stream. Periodically, the integrator or lead developer responsible for managing the Permissions_dev stream incorporates the delivered work into new baselines, and the developers rebase their development streams to those new baselines. When the two developers finish working on the permissions feature, they deliver their last work to the Permissions_dev stream. The integrator incorporates their delivered work into a final set of baselines and delivers those baselines to the integration stream.
35
Stream relationships
The relationships among streams determines how changes can move in a project (see Figure 16).
36
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
Integration stream
PA.BL1
Stream D2c
D1.BL0
Stream D2c_1
An integration stream has foundation baselines represented by PA.BL1 which are also its recommended baselines. Child stream D1 has foundation baselines represented by PA.BL1 and has recommended baselines D1.bl0 and D1.bl1. Family terminology is used to describe where in the hierarchy a particular stream is located. v Streams with the same parent are called siblings. For example, in Figure 16, streams D2a, D2b, and D2c are descendants from the same parent (stream D1). Streams D2a and D2b use the baselines in D1.bl0 as their foundation baselines. Stream D2c uses the baselines in D1.bl1 as its foundation baselines. Tip: Although stream D2c uses different foundation baselines than its siblings, all components in its siblings are also in its foundation baselines. v The parent of a parent stream is called a grandparent. For example, in Figure 16, the integration stream is the grandparent of streams D2a, D2b, and D2c and the development stream D1 is the grandparent of streams D2b_1 and D2c_1. The foundation baselines in D2b.bl0 of stream D2b_1 are the recommended baselines in the parent stream D2b. The foundation baselines in D2c.bl0 of stream D2c_1 are the recommended baselines in the parent stream D2c. v Streams whose parent streams are siblings are called cousins. For example, in Figure 16, streams D2b_1 and D2c_1 are cousins because their parent streams D2b and D2c are siblings. Although the cousin streams have different foundation baselines, the baselines are ancestors of the same foundation baselines in the grandparent stream D1.
Chapter 3. Planning the project
37
PA.BL1
c1, c2, c3
D2.BL1
D2.BL1
D1.BL1
D1.BL1
PA.BL2
PA.BL2
A development stream is created as a child of either the integration stream or of another development stream. For example, stream D1 is a child of the integration stream, stream D2 is a child of stream D1, and D3 is a child of stream D2. The parent-child relationship between streams defines the default target of deliver operations and the default source of baselines for rebase operations. The default relationships are the following: v A child stream delivers to its default target, the parent stream, any undelivered activities that it holds. For example: Stream D3 delivers activities c1, c2, and c3 to its default target, stream D2. Stream D2 delivers to its default target, stream D1, activities b1, b2, and b3 and the activities that have been delivered to it from its child streams. Stream D1 delivers to the integration stream activities a1, a2, and a3 plus the activities that are delivered to it from its child streams.
38
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
v A child stream rebases to baselines in the parent stream to receive activities that were delivered by other development streams. Typically, these change sets are in recommended baselines. For example: Stream D3 rebases to recommended baselines in stream D2. Stream D2 rebases to recommended baselines in stream D1. Stream D1 rebases to recommended baselines in the integration stream. Although the integration stream is a child of the project, it does not have a default relationship. If the project manager wants the integration stream to have a default relationship, an integration stream in another project can be specified as the default target of deliver operations and the source of recommended baselines to be used for rebase operations.
Alternate targets
All streams in the same project can deliver activities to streams other than the default target. Such alternate target streams are restricted by the foundation baselines in the source stream and the target stream. A policy in the project controls whether streams can control access (see Policies for deliver operations to nondefault targets on page 66). Policies in the streams control stream access. A stream cannot be the target of a deliver operation if the project or stream policy prohibits access. One policy determines whether a stream can accept activities in a deliver operation from a stream in a different project.
D1.BL0
D2c
D1.BL1
D2a.BL1 D1
D2a.BL1
Figure 18. Direct stream relationships for alternate target deliver operations
Streams that share the same foundation baselines have a direct relationship and can share changes by using alternate target deliver operations. For example, child streams D2b and D2c share as their foundation baselines the recommended baselines in D1.bl0 from parent stream D1. All the elements that are in the foundation baselines of streams D2b and D2c are in the foundation baselines of the child stream D2a.
39
Using an alternate target deliver operation, you can migrate activities to a sibling stream or to a stream related to a sibling stream rather than to a parent stream. Delivering activities to any stream other than the parent stream can also include other activities from the foundation baselines of the source stream. What changes are migrated depends on the relationship of the foundation baselines of the source stream relative to the target stream. For example, in a deliver operation from stream D2b to D2c, from stream D2c to D2b, or from stream D2b_1 to D2c, because the foundation baselines are the same, only the changes in the source stream are migrated. Some alternate target deliver operations can be forward. This involves delivering activities to a sibling stream that has an advanced baseline or has newer foundation baselines. For example, in Figure 18, migrating changes from stream D2b to D2a involves a forward deliver operation. Because all changes in foundation baselines of stream D2b are in those of D2a, only the activities that are in stream D2b are delivered. However, alternate target deliver operations typically migrate more changes than you at first might anticipate. The alternate target deliver operation can also be backward. This involves delivering activities to a sibling stream that has not rebased to the newer, recommended baselines. For example, in Figure 18, migrating changes from stream D2a to D2b involves a backward deliver operation. Because the target stream D2b does not have all the changes that the source stream D2a has, the operation additionally migrates to stream D2b activities from baseline D2a.bl1 in stream D2a. Some alternate target deliver operations involve indirect baseline relationships (see Figure 19).
D1 PA.BL1
D1.BL0
D2c
D1.BL1
D2a.BL1 D1
D2b.BL1
D2a.BL1
Figure 19. Indirect stream relationships for alternate target deliver operations
A stream can migrate its changes to a stream that has an indirect relationship. The deliver operation often includes activities from the foundation baselines of the source stream. The following are examples. v From the child of one stream to the child of a sibling stream (cousin to cousin). For example, a deliver operation from stream D2b_1 to D2a_1 includes activities contained in baseline D2b.bl1.
40
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
v From a grandchild to a grandparent stream or to another direct ancestor. For example, a deliver operation from stream D2a_1 to D1 includes activities contained in baseline D2a.bl1. A deliver operation from stream D2b_1 to stream D1 includes activities contained in baseline D2b.bl1.
b1, b2, b3
Deliver operation
Two developers in project A work on different portions of a feature in their own streams D1 and D2, which are siblings. The two developers need to integrate their work before it is delivered to the integration stream. No other interaction is needed. The developer using stream D2 uses an alternate target deliver operation to migrate the changes in activities b1, b2, and b3 to the sibling stream D1. The developer in stream D1 tests the work and delivers all the activities to the default deliver target, the project A integration stream. This configuration works well where a low level of isolation is necessary.
41
Project A Integration stream PA.BL0 Stream D1 Stream D2 PA.BL1 a1, a2, a3 b1, b2, b3 D2.BL1 PA.BL2 PA.BL0
PA.BL1
D1.BL1 PA.BL2
Typically, stream D1 cannot rebase to baselines from stream D2 because they do not meet the requirement that the baselines must be contained in the parent stream. If you deliver to the parent stream the activities in a baseline in one stream, a sibling stream can be configured with those changes. In Figure 21, if the baseline D2.BL1 is first delivered to the parent stream (the project integration stream in this example), you can rebase stream D1 to the baselines in D2.BL1 in the sibling stream D2. Delivering to the parent stream ensures that, in a default target deliver operation, only activities that originated in stream D1 are delivered in baselines D1.bl1 to the parent stream. Sharing by a rebase operation in this manner requires integration one level higher than the stream in which the changes originated.
42
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
Project A Integration stream PA.BL0 Stream D1 Stream D2 PA.BL1 a1, a2, a3 b1, b2, b3 D2.BL1 PA.BL0
PA.BL1
D1.BL1 PA.BL2
Deliver operation
If you integrate changes in a sibling stream (rather than in a parent stream; see Sharing changes by a rebase operation on page 41), you can use an alternate target deliver operation to share changes between sibling streams. For example, if you deliver activities b1, b2, and b3 in stream D2 to stream D1, you must also deliver activities in baselines in PA.BL1 and merge the changes with the versions in activities a1, a2, and a3. This complex deliver operation can be simplified by using a rebase operation before the alternate target deliver operation (see Simplify a deliver operation with a rebase operation on page 43). All of the integrated changes are migrated to the parent stream (the project integration stream) when you deliver your work from stream D1.
43
D1 PA.BL1
Because streams D1 and D2 are siblings, stream D2 can deliver its activities to stream D1. However, stream D2 contains changes in it foundation baselines that are not in stream D1. If stream D2 were to deliver activities a1, a2, and a3 to stream D1, all the additional activities in baselines in PA.BL2 would have to be delivered also. However, if you rebase stream D1 to the baselines in PA.BL2 in the common parent stream before delivering the activities in stream D2, this complex alternate target deliver operation can be simplified. During the rebase operation, the changes in activities b1, b2, and b3 are preserved. After the rebase operation, no activities other than a1, a2, and a3 have to be delivered from stream D2 to D1.
Single-stream projects
For most customers, a parallel development environment consisting of private and shared work areas makes sense. However, small teams of developers working together closely may prefer a serial development environment. UCM supports this by letting you create a single-stream project. A single-stream project contains one stream, the integration stream, and does not allow users to create development streams. When developers join a single-stream project, they create a view attached to the integration stream. You may want to use a single-stream project during the initial stage of development when several developers want to share code quickly. When the development effort expands and you need a parallel development environment, you can create a multiple-stream project based on the final baselines in the single-stream project. The following are the main advantages of single-stream projects: v Developers who work in dynamic views see each others work as soon as they check in their files. Developers who work in snapshot views see each others work as soon as they check in their files and update their views. In a multiple-stream project, developers see each others changes only during deliver and rebase operations. v Developers have a simplified work environment. Because all work is done on the integration stream, developers do not need to maintain a development
44
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
stream and two views, one attached to the development stream and one attached to the integration stream. In addition, developers do not need to perform deliver or rebase operations. v Your role as integrator is simplified. Because developers work on the same stream and see each others changes immediately, you do not need to create baselines frequently. In contrast to a multiple-stream project, developers do not depend on baselines to integrate their work. The primary purpose of baselines in a single-stream project is to identify major milestones. The following are the main disadvantages of single-stream projects: v Developers have limited support for sharing files simultaneously. Although multiple developers can check out an element in the same stream at the same time, only one developer can reserve the checkout. A reserved checkout guarantees the developers right to check in a new version of the element. All other developers must check out the element as unreserved, which means that they cannot check in their versions until after the reserved checkout has been checked in or canceled. Developers with unreserved checkouts must merge their changes with the changes made by the reserved checkout. v Because changes are shared as soon as developers check in their files, developers assume the full responsibility for testing their work and must be extremely vigilant to ensure that they do not introduce bugs to the project. In contrast, a multiple-stream project allows the integrator or a software quality engineering team to perform extensive testing of new baselines on a dedicated testing stream and to recommend baselines only after they pass those tests. v Because changes are shared as soon as developers check in their files, developers might keep files checked out longer than they would in a multiple-stream project. If a view is lost, all changes made but not checked in that view are also lost. Therefore, have your Rational ClearCase administrator frequently back up views for single-stream projects.
Read-only streams
During the evolution of a project, you might need to provide some users with access to baselines while ensuring that they do not make any changes to components. You can address this requirement by creating a Read-Only development stream for those users. You cannot make baselines in Read-Only streams, nor can you create child streams beneath them. You can create view-private files, such as derived objects in Read-Only streams. Common use cases for Read-Only streams include the following: v Your quality engineering team needs to build and test a particular configuration. v Your customer support team needs access to a library that was built in a previous release. v Your release engineering team needs to create a release based on a combination of old and new baselines.
45
v How to name baselines (see Defining a baseline naming convention on page 52) v The set of promotion levels (see Identifying promotion levels to reflect state of development on page 52) v How to test baselines (see Planning how to test baselines on page 52)
SB
Project A ProjA_Comp
Project B ProjB_Comp
PB Core
Project A uses a composite baseline, PA, to select baselines in the GUI and Admin components. Project B also uses a composite baseline, PB. Baselines that are selected by a composite baseline are referred to as members. A composite baseline is said to depend on the member baseline. After you create a composite baseline to represent the project baseline, the next time you invoke the make baseline operation on the component that contains the project baseline, UCM performs the operation recursively. If a component that contributes to the composite baseline has changed since its latest baseline, UCM creates a new baseline in that component. For example, assume that developers made changes to files in the GUI component after the integrator created the 1 baseline. The next time you make a new project baseline, UCM creates a new
46
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
baseline in the GUI component that incorporates the changed files, and the new project baseline selects the new GUI baseline. A composite baseline can select other composite baselines. Thus, member baselines may themselves be composite baselines. The chain of dependencies forms an acyclic directed graph, with no limit on the depth of the membership. Composite baselines do not necessarily have to model any source or build dependencies. For example, if your system is so large that it consists of multiple projects, you may want to use a composite baseline to represent the system baseline. In Figure 24, SB is a composite baseline that selects the PA and PB baselines of Project A and Project B, respectively. In addition to using a composite baseline to represent the project, you can use multiple composite baselines within the same project. When working with multiple composite baselines, you can encounter situations where two composite baselines select different baselines of the same component. When this happens, you need to resolve the conflict by choosing one of the member baselines. To avoid these conflicts, choose a simple baseline design, rather than one that uses a complex hierarchy of composite baselines. For information about baseline conflicts, see Resolving baseline conflicts on page 120.
X.BL1
A.BL1
C.BL3
The objects A.BL1 and C.BL1 are baselines on components A and C that are used to group directory and file elements. Baselines A.BL1 and C.BL1 are members of the composite baseline X.BL1 on the component X that was created without a root directory in a VOB. Baseline X.BL1 directly depends on baselines A.BL1 and C.BL1. However, the dependency between A.BL1 and C.BL1 is incompletely expressed. The components have to be used together, but it is not clear whether component A depends on C or component C depends on A.
47
You cannot change the existing dependency relationships in a composite baseline. To change dependency relationships, you must create a new baseline, a descendant of the changing baseline. For the composite baseline, you can add dependency references to new components (to create a new dependency relationship) or can drop dependency references to existing components (to discontinue a dependency relationship). For either operation, a new composite baseline is created. At any time, a composite baseline can have member baselines added or dropped. Although it appears that components are manipulated to create composite baselines, the dependency relationship is made between baselines and not components. One might say that some components are dependant on other components, but the dependency relationships have a limited scope. The dependency relationship may last for the life of a particular project, but it might be different for other projects. The dependency relationships change over time as components are added or dropped. So the relationship must be made between versions of components, the baselines, rather than between the components themselves. Because a component without a VOB root directory has no elements (and, therefore, no associated code), a new composite baseline created on such a component can only indicate changes in the dependency relationship. A composite baseline on a such a component is an aggregation of baselines. When you use a pure composite baseline, a new baseline on component X only means that there was some change in the membership of the baseline. Using a pure composite baseline provides greater configuration flexibility than using a composite baseline on a component that has a root directory in a VOB. Use pure composite baselines whenever possible when you configure composite baselines.
A.BL1
C.BL3
Figure 26. Tightly coupled relationship between baselines
A.BL1 is a baseline on component A that groups directory and file elements and is also a composite baseline that selects baseline C.BL3 of component C. Baseline C.BL3 is a member of composite baseline A.BL1. Composite baseline A.BL1 depends on the member baseline C.BL3. A change to the baseline in component A could be caused by a change in the configuration of component A (that is, a member being added or dropped) or by a new baseline in component C. This type of component arrangement is tightly coupled, for example, if code in component A depends on code in component C.
48
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
In the tightly coupled relationship, the composite baseline A.BL1 fulfills two roles: selecting baselines from other components and identifying a set of versions in its component. Determining the reason for making a new descendant of this type of composite baseline is expensive (in terms of performance). Using a composite baseline that has tightly coupled relationships imposes configuration restrictions. For example, you may only be able to do an advanced rebase operation.
49
LIB.BL1
LIB_NR0
C.BL3
A.BL1
LIB.BL1
C.BL3
A.BL1
The project manager can create a component without a VOB root directory for each component that has a composite baseline and contains elements. For example, composite baseline LIB.BL1 is for a component that has its own elements. The project manager drops the dependency references to components C and A from baseline LIB.BL1. The project manager creates a new component LIB_NR that does not have a root directory. Then a new composite baseline LIB_NR0 can be made based on the rootless component. And you can add dependencies on the baseline LIB.BL1 of the original component and on baselines C.BL3 and A.BL1 of the other components.
A.BL1
A.BL2
B.BL1
B.BL2
C.BL3
D.BL1
C.BL4
D.BL1
c1, c2, c3
Figure 28. Creation of a composite baseline descendant
When you create a new baseline on component A, the work done on component C causes a new baseline, C.BL4, to be created to capture the changes. Because baseline C.BL3 was replaced by C.BL4, and baseline C.BL3 was a member of composite baseline B.BL1, a new baseline, B.BL2, on component B is made to record the relationship with baseline C.BL4. Because baseline B.BL1 was replaced by baseline B.BL2, a new baseline A.BL2 on component A is needed.
50
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
Unless you explicitly add dependencies to a composite baseline or drop dependencies from a composite baseline, when a baseline is created following on a composite baseline, the new baseline inherits the members of its predecessors. When a new descendant baseline is created, all dependencies of the composite baselines are checked and new baselines are created as needed. A new baseline need only be created for the composite baseline, not for any member baselines of unchanged components. Unless a new baseline is needed for a project that is not using the composite baseline, you should not have to create a new baseline for component D. Baseline B.BL2 inherits baseline D.BL1 unchanged. A new baseline for component D would not be a member of the composite baseline B.BL2.
Ongoing baselines
After developers start working on their streams in the new project and make changes, create baselines on the integration stream and on any feature-specific development streams on a frequent (nightly or weekly) basis. This practice has several benefits: v Developers stay in sync with each others work. It is critical to good configuration management that developers have private work areas where they can work on a set of files in isolation. Yet extended periods of isolation can cause problems. Developers are unaware of each others work until you incorporate delivered changes into a new baseline, and they rebase their development streams. v The amount of time required to merge versions is minimized. When developers rebase their development streams, they may need to resolve merge conflicts between files that the new baseline selects and the work in their private work areas. When you create baselines frequently, they contain fewer changes, and developers spend less time merging versions.
Chapter 3. Planning the project
51
v Integration problems are identified early. When you create a baseline, you first build and test the project by incorporating the work delivered since the last baseline. By creating baselines frequently, you have more opportunities to discover any serious problems that a developer may introduce to the project inadvertently. By identifying a serious problem early, you can localize it and minimize the amount of work required to fix the problem. If you are working in a single-stream project, you do not need to create baselines frequently. Developers see each others changes as soon as they check in files; they do not rebase to the latest recommended baselines. The primary purpose of baselines in a single-stream project is to identify major project milestones, such as the end of an iteration or a beta release.
52
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
When you make a new baseline, you need to lock the integration stream to prevent developers from delivering additional changes. This allows you to build and test a static set of files. Because validation tests are not exhaustive, you probably do not need to lock the integration stream for a long time. However, more extensive testing requires substantially more time. Keeping the integration stream locked for a long time is not a good practice because it prevents developers from delivering completed work. One solution to this problem is to create a development stream to be used solely for extensive testing. After you create a new baseline that passes a validation test, your testing team can rebase the designated testing development stream to the new baseline. When the baseline passes the next level of testing, promote it. When you are confident that the baseline is stable, make it the recommended baseline so that developers can rebase their development streams to it. For information on creating a testing development stream, see Creating a development stream for testing baselines on page 106. For information on testing baselines, see Testing the baseline on page 116.
Planning PVOBs
UCM objects such as projects, streams, activities, and change sets are stored in project VOBs (PVOBs). PVOBs can also function as administrative VOBs. You need to decide how many PVOBs to use for your system and whether to take advantage of the administrative capabilities of the PVOB.
53
V4.0_Webotrans
V4.0.1_Webotrans
GUI
Admin
GUI
Admin
Webotrans PVOB
Consider using multiple PVOBs only if your projects are so large that PVOB capacity becomes an issue. For more information, see Using multiple PVOBs.
54
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
PVOB3 Proj3
C1
C2
VOB1
VOB3
VOB2
/C1
/C3
/C2
= AdminVOB hyperlinks
Figure 30. Using one PVOB as an administrative VOB for multiple PVOBs
The arrows from the PVOBs and the component VOBs represent AdminVOB hyperlinks to PVOB3. Because the component VOBs and the PVOBs share a common administrative VOB, all three projects can modify all three components. For PVOBs that do not share a common administrative VOB, a project may select a component from another PVOB but the component will be Read-Only within that project. In Figure 30, a PVOB serves as an administrative VOB.
55
As an alternative to using a PVOB as an administrative VOB, you can link PVOBs and component VOBs to an administrative VOB. This approach might be appropriate if your development team is moving from base ClearCase to UCM and you currently use an administrative VOB. If you plan to use multiple PVOBs, create the PVOB that will serve as the administrative VOB first. When you create the other PVOBs, specify the first PVOB as the administrative VOB.
56
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
(or a rebase operation), an attempt is made to merge these executable files to the target versions unless the files are of an element type for which different merge behavior is specified. To define different merge behavior for special types of files in your environment, you can create an element type and specify one of the following mergetypes: v copy During a merge or findmerge operation within a delivery or a rebase, a version whose element type has the mergetype copy is not merged. The source version is copied to the target version without user intervention. v never A merge or findmerge operation ignores versions whose element type has never as a mergetype. v user A merge or a findmerge operation performs trivial merges only. Nontrivial merges must be made manually. The graphic user interface (GUI) tools provide extra options for user mergetype to keep the target version, copy the source version (from the source stream), or back out of the deliver operation. Note: If you fail to specify a mergetype of copy, never, or user for these element types, developers may encounter problems when they attempt to deliver work or rebase their streams. For example, default merge managers cannot handle data in these files. Developers create executable files when they build and test their work prior to delivering it. If these files are under version control as derived objects, they are included in the change set of the current activity. For information about creating element types, see Chapter 15, Using element types to customize file element processing, on page 229, and the mkeltype reference page in the IBM Rational ClearCase Command Reference.
57
Project 1
Project 2 UCM_Project1
Figure 31. Multiple PVOBs linked to the same Rational ClearQuest user database
Give the projects unique names. For example, in Figure 31, if Project 3 were named either Project 1 or Project 2 (which is valid in the UCM environment), the generated name in the Rational ClearQuest user database would not be unique and would cause the software to run erroneously. This naming requirement states that the project names that appear in the Rational ClearQuest user database must be unique.
58
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
PVOB1
Project 1
Schema Repository
Schema 1
PVOB2
Project 2
Figure 32. One schema repository for multiple Rational ClearQuest user databases
The databases that are named ClearQuest User Database 1 and ClearQuest User Database 2 are linked to the same schema repository. If you use multiple user databases, give each one a unique name. If a developer tries to access a user database whose name is not unique, the authentication can fail. In using the command line interface to be authenticated, a developer can specify only the name of the user database. (The graphic user interface requires that the database set (connection) be supplied.) If multiple user databases share the same name, the software cannot distinguish the difference in databases that have the same name. Using a single schema repository allows developers to switch between projects easily. If you store the schemas in different schema repositories, developers must connect to each schema repository once when they switch projects. The user name and password are stored locally for each connection that they use. The project manager or developer can provide or update the credentials by using the cmregister command.
59
specific functionality. Applying a package to a schema provides a way to add functionality quickly so that you do not have to build the functionality from scratch. v The UnifiedChangeManagement package has been applied to at least one record type. This package adds fields and scripts to the record type, and adds the Unified Change Management tab to the record types forms. v The UCMPolicyScripts package has been applied to the schema. This package contains the scripts for three Rational ClearQuest development policies that you can enforce. Rational ClearQuest includes two predefined UCM-enabled schemas: UnifiedChangeManagement and Enterprise. You can perform the following actions with these schemas: v Start using the integration readily by using one of the predefined schemas. v Use the Rational ClearQuest Designer and the Rational ClearQuest Package Wizard to enable a custom schema or another predefined schema to work with UCM. v Use one of the predefined UCM-enabled schemas as a starting point and modify it to suit your needs.
60
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
Which policies do you want to enforce? The integration includes policies that you can set to enforce certain development practices. You can also edit the policy scripts to change the policies. See Chapter 4, Setting policies, on page 63 for details.
61
62
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
Modifiable components
In most cases, you want components to be modifiable. For information on when to use read-only components, see Identifying read-only components on page 33.
Project Y
From the source stream, an alternate target deliver operation can contain activities with changes in components that (in the target stream) are read-only or are not visible. This condition can occur for one of the following reasons:
Copyright IBM Corp. 1992, 2006
63
v A limited set of components or different sets of components are configured in streams from the same project. v Streams from different projects can have different modifiability. For example, in Figure 33, components B and C in project X can be modifiable while the same components in project Y are read-only. v Streams from different projects can be configured with different sets of components. In project X, components D and E are not configured and therefore are not visible. Likewise in project Y, component A is not configured and is not visible. By default, if one of these conditions occurs, the deliver operation is prohibited. The project manager can allow such deliver operations to proceed by setting a policy on the target project or stream (see Require that all source components are visible in the target stream on page 69).
64
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
created. Snapshot views require developers to copy the latest delivered files and directories to their computer (a snapshot view update operation), which they may forget to do.
65
source streams to the target stream current recommended baselines before they deliver work to the target stream. The policy can be set per project or per stream, for interproject and intraproject deliver operations. The goal of this policy is to have developers build and test their work in their development work areas against the work included in the most recent stable baselines before they deliver to the target stream. This practice minimizes the amount of merging that developers must do when they perform deliver operations.
Feature1 1 1
Developer1 2 X X
Developer2
Default
Default
Nondefault
Nondefault
Figure 34. Default and nondefault deliver targets in a stream hierarchy
Developers who work on that feature deliver work to the feature-specific development stream Feature1. In Figure 34, the integration stream and the Feature1 development stream are ancestors of the Developer1 and Developer2 development
66
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
streams. The streams Feature1, Developer1, and Developer2 are descendants of the integration stream. The default target for a deliver operation from a development stream is the parent stream of that stream. Developers may also deliver to nondefault target streams. The arrows in Figure 34 illustrate default and nondefault deliver targets. The following policies apply only to such nondefault target streams: v Deliver changes from the foundation in addition to changes from the stream v Allow deliveries that contain changes to missing or non-modifiable components on page 68 v Allow interproject deliver to project or stream on page 69 v Require that all source components are visible in the target stream on page 69
Deliver changes from the foundation in addition to changes from the stream
Set this policy to control accepting changes that did not originate in the delivery stream. There are two versions of this policy: one for intraproject deliveries and one for interproject deliveries. The policy can be set per project or per stream. UCM uses foundation baselines to configure a stream. A view attached to a stream selects the versions of elements identified by the stream foundation baselines plus the versions of elements associated with any activities created in the stream. For example, in Figure 35, 1 is the foundation baseline for the Feature1 development stream. The X baseline is the foundation baseline for the Developer1 development stream. If the developer working in the Developer1 stream delivers work to the integration stream, the deliver operation includes the activities created in the Developer1 stream plus the files represented by the X foundation baseline. The integrator responsible for the integration stream may want to receive work that the developer working in the Developer1 stream has completed; however, the integrator may be unaware that the deliver operation also contains changes made in the X baseline. You may want to set this policy to Disabled so that target streams do not accept deliver operations that contain changes in the source streams foundation baselines. If you set this policy to Enabled, the target stream accepts changes in the source stream that result from differences in the foundation baselines of the two streams in addition to changes in the source stream that the developer makes while working on assigned activities.
67
Integration
2 X
Developer1
68
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
Require that all source components are visible in the target stream
Set this policy to control whether streams accept deliveries that contain changes to components that are not in the target stream configuration. The policy can be set per project or per stream. For information about component visibility, see Component modifiability and visibility on page 63. If you set this policy to disabled, UCM allows the deliver operation, but the changes to any missing components are not included. This policy is ignored if interproject delivery is disabled.
69
can determine which record types are used in the Rational ClearQuest user database for new activity records that are created outside the Rational ClearQuest client (see Allowed record types). This policy is not customizable.
For WorkOn
The policy described in Perform ClearQuest action before work on applies when the developer clicks WorkOn in the Rational ClearQuest record form.
For delivery
The policies described in this section apply when developers deliver their work in their project.
70
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
See Policies and interproject deliveries on page 73 for details about deliveries between two projects that are enabled for Rational ClearQuest.
71
v If the deliver operation contains activities that are mastered by a third replica, the deliver operation fails. This policy is not customizable. See Policies and interproject deliveries on page 73 for details about deliveries between two projects that are enabled for Rational ClearQuest.
72
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
73
74
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
75
in a prescribed order. These packages must be added in the order described for each step. Integrating your schema with UCM packages requires that the following actions be done in the order described: 1. Adding the AMStateTypes Package. 2. Setting the Default Actions for UCM. 3. Adding the UCMPolicyScripts Package. 4. Adding the UnifiedChangeManagement Package. 5. Adding the UCMProject Package. 6. Adding the BaseCMActivity Package (optional). 7. Saving the Schema Changes. 8. Configuring Rational ClearCase UCM. Note: To avoid errors, you must install packages in the order described. The AMStateTypes Package provides additional support for UCM and its state types. Installing this package requires that you map schema states to the following state types: Waiting, Ready, Active, and Complete. The package adds the am_statetype field to the enabled record type. The UCMPolicyScripts Package adds three global scripts and does not add any record types. The UnifiedChangeManagement package does the following: v Adds the UCMUtilityActivity record type. v Adds UCM_Project stateless record type. v Adds UCM queries to the Rational ClearQuest client workspace under the Public Queries folder. v Adds the ucm_base_ synchronize action to the enabled record type. Although the BaseCMActivity package is not necessary, you may want to apply it to your schema. The BaseCMActivity package adds the BaseCMActivity record type to your schema. The BaseCMActivity record type is a lightweight activity record type. You may want to use the BaseCMActivity record type as a starting point and then modify it, for example, to include additional fields and states. If you want to rename the BaseCMActivity record type, be sure to do so before you create any records of that type.
76
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
7. Add the UnifiedChangeManagement package to the schema. For information on applying packages, see IBM Rational ClearQuest MultiSite Administrators Guide. The AMStateTypes package is also applied. 8. In the second page of the wizard, select your schema. Click Next. 9. The third page of the wizard prompts you to specify the schema record types. Set the check boxes of the record types that you want to enable. Click Finish. All selected record types must meet the requirements listed in Requirements for enabling custom record types on page 78. 10. In the Setup State Types page, assign state types to the states for each record type. For information about assigning state types, see Assigning state types to the states of a record type. For information about performing the task, see To map record states to state types. Click Finish. 11. Set default actions for the states of each enabled record type (see To set default actions for states on page 80). Default actions are state transition actions that are taken when a developer begins to work on an activity or delivers an activity (see State transition default action requirements for record types on page 79). 12. In the Rational ClearQuest Designer workspace, navigate to the record type Behaviors (click schema > Record Types > Record Type > States and Actions > Behaviors). Double-click Behaviors to display the Behaviors grid. a. Verify that the Headline field is set to Mandatory for all states. b. Verify that the Owner field is set to Mandatory for all Active and Ready state types. 13. Validate the schema changes by clicking File > Validate. Fix any errors that are displayed, and then check in the schema by clicking File > Check In. 14. Do one of the following actions: v Click Database > Upgrade Database to upgrade the user database so that it is associated with the UCM-enabled version of the schema. v Create a new user database that is based on the UCM-enabled version of the schema.
77
v If you are running Package Wizard in the Rational ClearQuest Designer, advance to the Setup State Types page. v If the Setup State Types page of the wizard does not appear, click Package > Setup State Types. 3. In the Setup State Types window, for each record type that is listed in Record Type, do the following: a. For each state in the States column, click in the adjacent cell under State Type to display the list of available state types. b. Select one of the entries. c. To display the states of another record type, click the arrow in the Record Type and select another of the available record types. See Setting state types on page 78 for a description of the four state types, and the rules for setting them.
78
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
Table 2. State Types in UCM-Enabled Schema (continued) State type Complete Description The developer has either worked on and completed the activity, or not worked on and abandoned the activity.
Submitted
Postpone
Reopen
Figure 36. State transitions of UCM-enabled BaseCMActivity record type
Complete
In addition to this single path requirement, states must adhere to the following rules: v All Waiting type states must have a default action that transitions to another Waiting type state or to either a Ready or Active type state.
79
v If a Ready type state has an action that transitions directly to a Waiting type state, that Waiting type state must have a default action that transitions directly to that Ready type state. v All Ready type states must have a default action that transitions to another Ready type state or to an Active type state. v All Ready type states must have at least one action that transitions directly to a Waiting type state. v For the BaseCMActivity record type, its initial state must be a Waiting type.
80
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
81
record form of a UCM-enabled record type, you can provide the developers on your team with the ability to decompose a parent activity into several child activities. To have the state of the parent activity changed to Complete when all child activities have been completed, you need to write a hook. See IBM Rational ClearQuest MultiSite Administrators Guide for an example of such a hook.
82
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
Delivers changes in a stream in one project to a stream in another project. v A developer transitions a Rational ClearQuest activity record. Create and maintain the credentials on the users system for each database set. The credential information is stored on the system so that the user can be logged in by the integration server when a different user database is accessed. If no credentials exist for a user when a connection to another user database is required, an error message is generated. Use the crmregister command for the following purposes: v Create a new entry or overwrite an existing entry. For example:
crmregister add -database MY_DB -connection 07.00 -user jsmith -password mypassword
v Modify the specified fields for a specified user database. For example:
crmregister replace -database MY_DB -password mynewpassword
83
84
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
Set up project
Establish policies
Create a PVOB
Create components
Create a project
85
You can create and set up a new project that is not based on an existing project or on an existing set of VOBs.
86
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
The ucmproject option indicates that you are creating a PVOB instead of a VOB. The /usr/vobstore/myproj2_pvob.vbs path specifies the location of the PVOB storage directory. A PVOB storage directory is a directory tree that serves as the repository for the PVOB contents. A PVOB storage directory contains the same subdirectories as a VOB storage directory. For details about VOB storage directory structure, see the IBM Rational ClearCase Administrators Guide. If you are in an MVFS environment and developers use dynamic views, perform the following two steps. 2. Create the PVOB mount point to match the PVOB tag. For example:
mkdir /vobs/myproj2_pvob
The PVOB assumes the role of administrative VOB. When you create components, AdminVOB hyperlinks are automatically made between the components and the PVOB. If you are creating multiple PVOBs and anticipate that projects in those PVOBs may need to modify some of the same components, choose one PVOB to act as the administrative PVOB and create it first. When you create the other PVOBs, use the cleartool mkhlink command to create an AdminVOB hyperlink between each PVOB and the PVOB that acts as the administrative VOB. For more information about using multiple PVOBs, see Planning PVOBs on page 53. When you create components, AdminVOB hyperlinks are made between the components and the PVOB that serves as the administrative VOB.
87
2. The left pane of the Project Explorer lists folders for all PVOBs in the local Rational ClearCase domain. Each PVOB has its own root folder. The root folder is created using the name of the PVOB. Navigate to the PVOB that you created. 3. Locate a folder called Components, which contains entries for each component in the PVOB. Right-click the Components folder and click New > Component Without a VOB. 4. In the Create Component Without a VOB window, enter a name and description for the component. Click OK.
This baseline selects the /main/0 version of the root directory of the component. It serves as the starting point for successive baselines of the component.
88
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
4. Specify where to store the VOB. You can choose one of the recommended locations or enter the UNC path of a different location. Click Browse to search the network for shared resource locations. 5. Identify the PVOB that will store the project information about the components. Click the arrow to see the list of available PVOBs. Select the PVOB that you previously created (see Creating the project VOB on page 86).
If you are in an MVFS environment and developers use dynamic views, perform the following two steps. 2. Create the VOB mount point to match the VOB tag. For example:
mkdir /vobs/testvob13
To create a multiple-component VOB in Rational ClearCase LT (Linux and the UNIX system)
On the Rational ClearCase LT server host, use the cleartool mkvob command. For example:
cleartool mkvob nc -tag /testvob13 -stgloc vobstore
89
2. Enter a name for the component. The component name must be unique within its PVOB. Enter a comment to describe the purpose of the component. Set This VOB will contain UCM components. 3. Set Create VOB as a single VOB-level component. 4. Specify where to store the component. You can choose one of the recommended locations or enter the UNC path of a different location. Click Browse to search the network for shared resource locations. 5. Identify the PVOB that will store the project information about the component. Click the arrow to see the list of available PVOBs. Select the PVOB that you previously created (see Creating the project VOB on page 86). The component is created with an initial baseline that points to the \main\0 version of the component root directory.
To create one component per VOB (Linux and the UNIX system)
1. Make a view by using the cleartool mkview command. For a dynamic view, also issue the cleartool setview command. For example:
cleartool mkview tag myview /net/host2/view_store/myview.vws cleartool setview myview
3. If you are in an MVFS environment and developers use dynamic views, perform the following steps. a. Create the VOB mount point to match the VOB tag. For example:
mkdir /vobs/testvob1
4. Do one of the following steps to create the component: v Issue the cleartool mkcomp command. For example:
cleartool mkcomp nc root /vobs/testvob1 testcomp1@/vobs/myproj2_pvob
In this example, the mkcomp command creates a component named testcomp1 based on the VOB named testvob1. Although this example uses different names for the VOB and component, you can use the same name for both. The component name must be unique within its PVOB. The VOB and PVOB must be mounted before you issue the command. All projects that use the myproj2_pvob PVOB can access the testcomp1 component. v Convert an existing VOB into a component by using the Rational ClearCase Project Explorer. See To make a VOB into a component on page 97 for more information.
90
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
To create a project
1. Start Project Explorer (see To start Project Explorer on page 88). 2. The left pane of the Project Explorer lists root folders for all PVOBs in the local Rational ClearCase domain. Product Note: On the Rational ClearCase LT server, there is only one PVOB. Each PVOB has its own root folder. The root folder is created using the name of the PVOB. The folder Components contains entries for each component in the PVOB. Folders can contain projects and other folders. Select the root folder for the PVOB that you want to use for storing project information. 3. Click File > New > Folder to create a project folder. You do not need to create a project folder, but it is a good idea. As the number of projects grows, project folders are helpful in organizing related projects. 4. In the left pane, select the project folder or root folder. Click File > New > Project. The New Project Wizard appears. 5. In the New Project Wizard, enter a descriptive name for the project and provide a comment to describe the purpose of this project. v Enter a name for the project integration stream or accept the default name (project-name_Integration). v Select the type of project to create. A traditional parallel development project lets users create multiple streams so that developers can have private and shared work areas. A single-stream project contains only one stream, the integration stream. Users cannot create development streams in a single-stream project. See Choosing a stream strategy on page 34 for information about single-stream and multiple-stream projects. 6. Indicate whether you want to create the project based on an existing project. Because you are creating a project from scratch, click No. 7. Choose the baselines that the project will use. These baselines are either the foundation baselines upon which all work within the project is built or the baselines from which other projects start. a. Click Add to open the Add Baseline window. In the Component list, select one of the components that you previously created. v On Windows systems, click Change > All Streams. v On Linux and the UNIX system, click the arrow at the end of the From Stream field and set All Streams. The component initial baseline appears in the Baselines list.
Chapter 6. Setting up the project
91
b. Select the baseline. c. Set Allow project to modify the component unless you want the component to be read-only. (See Identifying read-only components on page 33 for information on when you may want to use read-only components.) d. Click OK. The baseline now appears in the list. Continue to use the Add Baseline window until the project contains its full set of foundation baselines, including the baseline for the component that stores the project composite baseline. 8. Specify the development policies to enforce for this project. Set the check boxes for the policies that you want to enforce. See Chapter 4, Setting policies, on page 63 for information about each policy. 9. Indicate whether to configure the project to work with the UCM integration with Rational ClearQuest. To enable the project to work with Rational ClearQuest, click Yes, use the following ClearQuest connection and, in ClearQuest Link, select the database set (connection) and Rational ClearQuest user database that you have set up to use with this project. You are asked to authenticate with your Rational ClearQuest user name and password. See Enabling use of the UCM integration with Rational ClearQuest on page 100 for details about the integration. You can click Policies to set UCM policies related to the integration or access the Policies page of the project to set them after the project is created.
For information about using a baseline naming convention, see Defining a baseline naming convention on page 52. To set a baseline naming template: Use the blname_template option with the cleartool mkproject or chproject command to set a template. For example:
cleartool chproject -blname_template project,component,date mck_proj1
This example sets a template that uses the project name, component name, and date in all baseline names created in the mck_proj1 project. Use commas to separate the tokens in the command-line entry. When you create baselines, the
92
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
commas are replaced with underscores. See IBM Rational ClearCase Command Reference for details about using chproject and mkproject.
93
d. Stream 2. Select the integration stream and click File > New > View. On the Windows system, the View Creation Wizard is displayed. On Linux and the UNIX system, the Create View window is displayed. 3. Accept the default values to create an integration view attached to the integration stream. By default, the View Creation Wizard and the Create View window use this convention for the integration view name:
username_project-name_int
Creating and setting an activity in the integration stream (Linux and the UNIX system only)
Before you can add elements to the integration stream, you need to create and set an activity.
If your integration view is a snapshot view, change directory to it. 2. Issue the cleartool mkactivity command. For example:
cleartool mkactivity headline Create Directories create_directories
The Rational ClearCase GUI tools use the name specified with headline to identify the activity. The last argument, create_directories, is the activity-selector. Use the activity-selector when you issue cleartool commands. 3. By default, when you make an activity with the cleartool mkactivity command, your view is set to that activity. Your view is not set to an activity if you create multiple activities in the same command line or if you specify a stream with the in option. If you need to set your integration view to the activity, use the cleartool setactivity command. For example:
cleartool setactivity create_directories
94
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
This example creates a directory element called design. By default, the mkelem command leaves the element checked out. To add elements, such as subdirectories, to the directory element, you must leave the directory element checked out. 4. When you finish adding elements to the new directory, check it in. For example:
cleartool ci nc design
5. When you finish creating directory elements, check in the component root directory. For example:
cleartool ci nc .
For more information about creating directory and file elements, see Developing Software online help and the mkelem reference page.
Importing directories and files from outside Rational ClearCase version control
If you have a large number of files and directories that you want to place under Rational ClearCase version control, you can speed the process by using the clearexport and clearimport command-line utilities. These utilities allow you to migrate an existing set of directories and files to a Rational ClearCase repository from another version control software system, such as SourceSafe, RCS, or PVCS. You have the following options: v Migrate source files directly into a component (see To migrate source files into a component on page 95). v Use clearexport and clearimport on VOBs, and then convert the VOBs to components. For details on converting VOBs into components, see Creating a project based on an existing Rational ClearCase configuration on page 97. v Migrate directories and flat files that are not currently under any version control. Use the clearfsimport command-line utility. Run clearfsimport from within a UCM view to import directories and files directly onto a stream. You can then create a baseline in the stream without having to label the versions. See the clearfsimport reference page for details. v On Windows systems, use the Import Wizard, a graphic user interface (GUI) that you can use as an alternative to the clearexport and clearimport commands. For details on using clearexport and clearimport, see the IBM Rational ClearCase Administrators Guide and the clearexport and clearimport reference pages.
95
2. Create and set a non-UCM view. On Windows systems, use the View Creation Wizard. To start the View Creation Wizard, from Rational ClearCase Explorer click Base ClearCase > Create View. On Linux and the UNIX system, use the cleartool mkview and setview commands. 3. In the view context, run clearimport to populate the component with the files and directories from the data file. 4. In the component, create a baseline from a labeled set of versions. If the versions that you want to include in the baseline are not labeled, create a label type and apply it to the versions.
96
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
does not include the Basename token, or if no template is set, the Base Name or Baseline Title field does not appear in the Create Baseline Dependencies window. 5. Click OK.
97
2. In the Available VOBs list, select the VOB that you want to make into a component. Click Add to move the VOB to the VOBs to Import list. You can add more VOBs to the VOBs to Import list. If you change your mind, you can select a VOB in the VOBs to Import list and click Remove to move it back to the Available VOBs list. 3. When you are finished, click Import.
The recurse option causes the label to be applied to all versions at or below the current working directory. 2. In the Project Explorer, select the PVOB. Do one of the following: On Linux and the UNIX system, click Tools > Import > Import Label. Step 1 of the Import Label Wizard appears. On the Windows system, click Tools > Import > Label as Baseline. 3. In the Available Components list, select the component that contains the label from which you want to create a baseline. Click Add to move that component to the Selected Components list. If you change your mind, select a component in the Selected Components list and click Remove to move the component back to the Available Components list.
98
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
4. In Step 2 on page 98, select the label type that you want to import, and enter the name of the baseline that you want to create for the versions identified by that label type. Then select the baseline promotion level. Note: You cannot import a label type from a global label type definition.
99
Continue to use the existing PVOB. You can create the project based on the existing PVOB (see To create a project based on an existing project on page 100).
100
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
5. To set the Rational ClearQuest development policies that you want to enforce, click Policies and ClearQuest. See Policies for the UCM integration with Rational ClearQuest on page 69 for a description of these policies. Click OK when you are finished. For a new project: If you are creating a new project, you can enable the project to work with Rational ClearQuest by setting Yes, use the following ClearQuest connections and selecting the connection and user database in Step 5 of the New Project Wizard. For information about the procedure to create a new project, see Creating the project on page 91.
Migrating activities
If your project contains activities when you enable it to work with a Rational ClearQuest user database, the UCM integration with Rational ClearQuest creates records for each of those activities by using the UCMUtilityActivity record type. To store all of your project activities in records of some other record type, enable the project when you create it, before team members create any activities. After the migration is complete, any new activities that you create can link to records of any UCM-enabled record type.
101
The query displays all UCM-enabled projects that are associated with the current Rational ClearQuest user database. 3. Select a project from the Results set. The project form appears. 4. On the form, click Actions and select Modify. Set the check boxes for the policies to be enabled. Because not all policies are stored in the Rational ClearQuest user database for a project, you may have to set some policies from Rational ClearCase control. For descriptions of the policies, see Policies for the UCM integration with Rational ClearQuest on page 69.
Assigning activities
Project Manager
Create project
Establish policies
After you establish policies, you create activities so that work can be assigned and scheduled.
Disabling the link between a project and a Rational ClearQuest user database
There may be times when you want to disable the link between a project and a Rational ClearQuest user database.
102
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
103
1. In the Project Explorer, display the project property sheet, and click the ClearQuest tab. 2. Click Link all unlinked activities mastered at this replica. The integration checks all of the project activities and links any that are unlinked. The integration then displays the following summary information: v Number of activities that had to be linked. v Number of activities that were previously linked. v Number of activities that could not be linked because they are not mastered in the current PVOB replica. In this case, the integration also displays a list of replicas on which you must run the Link all unlinked activities mastered at this replica operation again to correct the problem. 3. At each replica on the list described in Step 2, repeat Step 1 and Step 2.
How the UCM integration with Rational ClearQuest is affected by Rational ClearQuest MultiSite
If you use Rational ClearCase MultiSite to replicate the PVOB and ClearQuest MultiSite to replicate the Rational ClearQuest user database and schema repository involved in the UCM integration with Rational ClearQuest, you need to be aware of several requirements. v Replica and naming requirements v Transferring mastership of the project v Linking activities to Rational ClearQuest records on page 105 v Changing project policy settings on page 105 v Changing the project name on page 105
104
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
105
Build components
Make baselines
Recommend baselines
When you make a new baseline, lock the integration stream so that you can build and test a static set of files. Otherwise, developers can inadvertently cause confusion by delivering changes while you are building and testing. Locking the integration stream for a short period of time is acceptable; locking the integration stream for several days can result in a backlog of completed but undelivered activities. To avoid locking out developers for a long period of time, you may want to create a development stream and use it for extensive testing of baselines (see To create a development stream on page 106). If your project uses feature-specific development streams, you may want to create a testing stream for each feature-specific development stream so that you can test the baselines created in those streams. If the development stream is configured to be read-only, you can build and test the new baselines, and developers can deliver changes to the integration stream without being concerned about interfering with the building and testing process. For information on testing baselines, see Testing the baseline on page 116.
106
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
6. In the Create a Development Stream window, set Prompt me to create a View for this stream. Click OK. The View Creation Wizard (the Windows system) or Create View window (Linux and the UNIX system) appears. 7. Complete the steps of the View Creation Wizard or the fields of the Create View window to create a view for the development stream.
107
108
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
Adding components
Over time, the scope of your project typically broadens, and you may need to add components to a stream and to projects (see To add a component to a stream on page 110). Adding a component to a stream requires that you rebase to the baseline of the new component after the component is added. By default, a component is added to the project as read-only. To allow developers to deliver changes for that component, make the component modifiable (see To make a component modifiable within the project on page 110). Before you can access the component that you added to a stream from a view that is attached to the stream, you must synchronize the view with the new configuration (see To synchronize a view with a new configuration on page 110). To enable a child stream to access a modifiable component that you added to a parent stream, you must do the following tasks: v Synchronize the child stream with the new set of modifiable components in the project (see To synchronize a child stream with project modifiable components on page 110). v Synchronize the child stream view with the new configuration of the parent stream (see To synchronize a child stream view with new parent stream configuration on page 111). If snapshot views are attached to a stream to which you added a component, you need to edit the view load rules to include the components that you add to the stream (see To edit the view load rules on page 111). The load rules of a snapshot view specify which components are loaded into the view. In addition, you need to know whether any developers working on the project use snapshot views for their development views. When a developer who uses a snapshot view
Copyright IBM Corp. 1992, 2006
109
rebases to a baseline that contains a new component, the snapshot view config spec is updated, but the view load rules are not updated. When you add a component, take the following actions for developers who use snapshot views: v Notify the developers that they need to rebase their development streams to the baseline of the newly added component. v Instruct the developers to update the load rules for their development views to load the newly added component.
110
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
Element relocation
After you create components and add them to a UCM configuration, you should not change the configuration. Change flow and integration in UCM depend on stable components. If you absolutely must relocate directory and file elements, you can run a UCM-supplied script mkelem_cpver.pl. The script must be run in a strictly-controlled situation to prevent undesired configuration changes. You must use ratlperl to run the script. The script does the following operations: v Copies directory and file elements (one source version to one target version) within a VOB or between VOBs. New elements are created in the target directory with the views version of the original element from the source directory. v Uncatalogs the elements in the source directory. v Preserves the history of the source elements to allow work to continue in other streams. The script does not do the following operations: v Retain source history in the target version. (A comment attached to the target version records the path of the source version for historical purposes.) v Roll back when errors are encountered. (No support is provided for undoing the operation. The project manager must fix any errors.) v Integrate changed content in other streams. If you deliver or rebase content between streams, be careful to distinguish between the previous and current names of the relocated elements.
To relocate elements
1. In a shell or command prompt window, change directory to a view that is attached to a stream that contains the components whose elements you want to relocate. 2. If the view is a snapshot view, update it. 3. Set the view to an activity that you reserve for this operation. 4. Run the script and specify the source path and target path for the relocation. For example:
cleartool mkact -head "Move XML utility code to libks" my-app-xml-move
111
The xml directory and all its contents are copied to the new location under the ks directory. If the script encounters a hard link, it creates a separate element. After the relocation, if developers try to deliver or rebase operations that involve a relocated element, they see warning messages that the element is not visible. Any changes that are made to the source elements must be manually merged from the source location to the target elements in the new location.
Building components
Integrator
Build components
Make baselines
Recommend baselines
A responsibility of the project integrator is to build and test components to ensure that the changes to the software are stable and meet the goals of the project before the changes are made available in new baselines.
112
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
could break your build operations and produce bad baselines. You may want to create a script that checks for deliveries in progress, and run the script before you lock the stream.
To lock a stream
1. In the Project Explorer, select the stream. 2. Click File > Properties to display the stream property window. 3. Click the Lock tab. 4. Click Locked and then click OK.
113
integration view, they cannot undo the changes easily. When this happens, you may need to remove the checked-in versions by using the cleartool rmver xhlink command. Warning: The rmver command erases part of your organizational development history, and it may have unintended consequences. Therefore, be very conservative in using this command, especially with the xhlink option. See the rmver reference page in the IBM Rational ClearCase Command Reference for details. Removing a version does not guarantee that the change is really gone. If a successor version was created or if the version was merged before you removed the version, the change still exists. You may need to check out the file, edit it to remove the change, and check the file back in.
Build components
Make baselines
Recommend baselines
Project integrators are responsible for making baselines before they recommend them.
114
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
v An incremental baseline is a baseline that is created by recording the last full baseline and those versions that have changed since the last full baseline was created. v A full baseline is a baseline that is created by recording all versions below the component root directory. Generally, incremental baselines are faster to create than full baselines; however, the contents of a full baseline can be searched faster than the contents of an incremental baseline can. While you are making the baseline, you should lock the stream (see Locking the shared stream on page 112). After you create a baseline, unlock the integration or feature-specific development stream so that developers can resume delivering work to the stream.
To make a baseline
1. Lock the stream to prevent developers from delivering work while you create the baseline (see To lock a stream on page 113). Developers can continue to work on activities in their development streams. 2. Verify the stability of the project by testing its components. 3. Make the baseline. Do one of the following: v Make baselines for all components in the stream (see To make new baselines for all components in the stream on page 115). v Make a baseline for certain activities (see To make a baseline for a set of activities on page 116). v Make a baseline for one specific component (see To make a baseline of one component on page 116). 4. Unlock the stream so that developers can deliver work (see To unlock the stream on page 116). For information on baselines, see Specifying a baseline strategy on page 45.
115
116
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
Project A Integration stream PA.BL0 DS (test stream) PA.BL1 PA.BL1 a1, a2, a3 PA.BL1.S PA.BL2 PA.BL0 D1
D1.BL1 PA.BL3
The steps are: 1. Make a baseline that contains the changes to be tested (see PA.BL1 in Figure 37). 2. Do one of the following: v Create a development stream dedicated to stabilization (see stream DS in Figure 37). For information about creating a development stream, see To create a development stream on page 106. v Rebase a dedicated development stream to the baseline that you made (see Rebasing the test development stream on page 117). 3. Use as the foundation baseline of the test stream the baseline that you created (see PA.BL1 in Figure 37). 4. Control the changes that are being made in the stabilization stream DS. Other work from development streams in the project can be delivered to the integration stream without affecting the stabilization stream. Fixes implemented in the stabilization stream are isolated from activities delivered to the integration stream. 5. When the code in the test stream is stable, make a baseline in the test stream (see PA.BL1.S in Figure 37). 6. Deliver the baseline PA.BL1.S to the integration stream. 7. In the integration stream, recommend the baseline from the stabilization stream so that development streams can rebase to it. (This is an example of an advance rebase operation; see Advance rebase operations on page 21.)
117
Build components
Make baselines
Recommend baselines
118
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
As work on your project progresses and the quality and stability of the components improve, you make new baselines and want to make the work available to the team. Do the following: v Change the baseline promotion level attribute to reflect a level of testing that the baseline has passed. v Recommend baselines that have passed extensive testing.
119
AC.BL1
BCD_BL1
A.BL1
C.BL3
B.BL1
C.BL1
D.BL1
Baseline C.BL3 a member of composite baseline AC.BL1 and baseline C.BL1 a member of composite baseline BCD.BL1.
120
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
If baselines AC.BL1 and BCD.BL1 are configured in project Y, it is unclear to Rational ClearCase which baseline on component C to use, baseline C.BL1 or C.BL3 (see Figure 39).
Project Y
E.BL1
AC.BL1
BCD_BL1
E_BL0
A.BL1
C.BL3
B.BL1
C.BL1
D.BL1
In the Rational ClearCase environment, a view must have an unambiguous rule for selecting versions of an element. In UCM, a stream can only use one baseline to select the versions in a component. Rebase operations and baseline recommendations that would result in conflicts are blocked. To resolve the conflict, you are forced to explicitly specify a baseline for the component in question. This chosen baseline is said to override the members of the composite baselines in conflict. A baseline that you explicitly specify as an override baseline in the foundation set of a stream, regardless of whether it resolves a conflict, overrides any baseline of that component that is implied by a composite baseline. To resolve the conflict on component C shown in Figure 39, the project integrator chooses baseline Cx.BL3 (see Figure 40).
Project Y
AC.BL1
BCD_BL1
E_BL0
A.BL1
C.BL3
B.BL1
C.BL1
D.BL1
Because an override was selected, the baseline C.BL3 in composite baseline AC.BL1 and the baseline C.BL1 in composite baseline BCD.BL1 are ignored. Baseline Cx.BL3 is used to select versions in component C. Tip: The override applies only for the baseline for component C in the foundation baselines of the stream, but the composite baseline itself remains the same. You can choose as the override any baseline of the component involved in the conflict. The overriding baseline does not have to be one of the conflicting baselines. The project integrator can select a baseline that is compatible with the
Chapter 7. Managing the UCM project
121
other baselines in the baseline set of the project. In Figure 40, the project integrator could have chosen baseline C.BL1 as the override, instead of baseline Cx.BL3. However, the integrator must ensure that the versions selected by composite baseline AC.BL1 are compatible with the versions selected by baseline C.BL1. With the selection of the override Cx.BL3, the AC and BCD subsystems need to be checked to ensure that they are compatible with baseline Cx.BL3. Baseline overrides stay in effect until you do one of the following: v Explicitly remove the overriding baseline from the foundation set (for example, with cleartool rebase dbaseline). v Replace completely the foundation set. This happens when you rebase to the recommended baselines of the parent stream (cleartool rebase recommended). The decision to select a baseline override is solely for the project integrator. It is not a decision that can be automated. Each project team has to determine the correct override in each instance of a conflict.
Create project
Establish policies
Several tools are provided to help you track the progress of your project. You can do the following operations: v v v v View baseline histories Compare baselines Query a Rational ClearQuest user database Generate reports (Windows only)
122
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
and integration arrows that represent deliver operations, for example, from the development stream to the integration stream .
Baselines and streams in the specified component are listed. The format is similar to that of the lsvtree command. For more information, see the lscomp reference page.
Comparing baselines
You can display the differences between two baselines graphically or from a command shell.
The Compare Baselines window opens. v Open the Compare Baselines window from within the baseline Property window. 1. In Project Explorer, select the integration stream, and click File > Properties to display the integration stream Property window. 2. Click the Baselines tab and then select the component that contains the baseline you want to compare. 3. Select the baseline; then right-click it and click Compare with Previous Baseline or Compare with Another Baseline. The Compare Baselines window opens. For more information, see About the Compare Baselines window.
123
Members Shows the baselines that contribute to each baseline of a composite baseline Activities Lists the activities (if any) that contribute to the baseline. A baseline could contain no activities if it or its member baselines are the initial baselines of the component. Versions Lists the change sets associated with the activities in the baseline.
UCMProjects UCMCustomQuery1
124
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
You can also create your own queries by clicking Query > New Query within the Rational ClearQuest client. In the Choose a record type window that opens, select All_UCM_Activities if you want the query to search all UCM-enabled record types.
125
You can delete a project only if it does not contain any streams. When you create a project with the Project Creation Wizard, the wizard also creates an integration stream. Therefore, you can delete a project only if you created it with the cleartool mkproject command, or if you first delete the integration stream. For more information on removing projects, see the rmproject reference page in the IBM Rational ClearCase Command Reference. To remove an unused project, see To delete an unused object.
126
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
v For a project, see About deleting projects on page 125. v For a stream, see About deleting streams on page 126. v For a component, see About deleting components on page 126. v For a baseline, see About deleting baselines on page 126. v For an activity, see About deleting activities on page 126. 2. Select the object in the Project Explorer, and click File > Delete. To delete a baseline (see About deleting baselines on page 126), use the cleartool rmbl command.
127
128
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
Overview of triggers
A trigger is a monitor that causes one or more procedures or actions to be run whenever a certain Rational ClearCase operation is performed. Typically, the trigger runs a Perl, batch, or shell script. You can use triggers to restrict operations to specific users and to specify the conditions under which they can perform those operations. In addition, you can use triggers on certain UCM operations to enforce customized development policies for your project team. You can create triggers and use them to implement various development policies in UCM projects. For additional information about trigger usage, see the cleartool mktrigger and mktrtype reference pages.
Supported triggers
You can use triggers with the following UCM operations: v chbl v chfolder v chproject v chstream v deliver v mkactivity v mkbl v mkcomp v mkfolder v mkproject v mkstream v rebase v rmbl v rmcomp v rmfolder v rmproject v rmstream v setactivity v setplevel You can also use triggers with the following Rational ClearCase operations on UCM objects: v lock v unlock
129
You can define trigger types that can be set on lock and unlock operations and can restrict them to some individually named UCM objects or all UCM objects (activities, baselines, components, folders, projects, and streams).
Scope of triggers
A trigger type defines a trigger for use within a VOB or PVOB. When you create a trigger type, with the cleartool mktrtype command, you specify the scope to be one of the following: v An element trigger type applies to one or more elements. You attach an instance of the trigger type to one or more elements by using the cleartool mktrigger command. v An all-element trigger type applies to all elements in a VOB. v A type trigger type applies to type objects, such as attributes types, in a VOB. v A UCM trigger type applies to a UCM object, such as a stream or a project, in a PVOB. v An all-UCM-object trigger type applies to all UCM objects in a PVOB.
130
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
Perform ClearQuest Action Before Work On v For delivery Perform ClearQuest Action Before Delivery Transfer ClearQuest Mastership Before Delivery Perform ClearQuest Action After Delivery Transition to Complete After Delivery Transfer ClearQuest Mastership After Delivery v For changing an activity Perform ClearQuest Action Before Changing Activity Perform ClearQuest Action After Changing Activity Transition to Complete After Changing Activity Some of these policies have Rational ClearQuest global hook scripts associated with them, which you can edit or replace in Rational ClearQuest Designer to customize the policy for your environment. You can also write your own Rational ClearQuest hooks to enforce development policies. In general, if the policy you want to enforce involves a Rational ClearQuest action, use one of the Rational ClearQuest policies previously mentioned or use Rational ClearQuest hooks. If the policy you want to enforce involves a Rational ClearCase action, use UCM triggers. Some operations might have Rational ClearCase triggers and Rational ClearQuest hooks associated with them. For example, you might define a trigger that sends e-mail to team members when a developer completes a deliver operation, and you might have the Perform ClearQuest Activity After Delivery policy enabled. Under Rational ClearCase and Rational ClearQuest control, triggers, hooks, and UCM operations are run in the following order: v Rational ClearCase preoperation trigger v Rational ClearQuest preoperation hook v UCM action v Rational ClearQuest postoperation hook v Rational ClearQuest transition activity hook v Rational ClearCase postoperation trigger You can use the Rational ClearQuest API to write code that runs in the Rational ClearQuest environment. For example, you can modify records that users submit or validate the records before they are committed to the user database. For code examples that work with cqperl on Linux and the UNIX system or that use CAL methods in Rational ClearQuest hook scripts on the Windows system, see IBM Rational ClearQuest API Reference.
131
Tip: The command line example is broken across lines to make the example easier to read. You must enter the command on one line. On Linux or the UNIX system, only the script precheckin.sh runs. On the Windows system, only precheckin.bat runs. To prevent users on a new platform from bypassing the trigger process, triggers that specify only execunix always fail on the Windows system. Likewise, triggers that specify only execwin fail on Linux and the UNIX system.
Note: In your scripts, you can run ratlperl directly. Ensure that you include the following default paths to execute the scripts successfully: v On Linux and the UNIX system: /opt/rational/common/ v On the Windows system: <install_location>\Rational\Common\ The value install_location is the root folder in which you installed Rational ClearCase.
132
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
v For more information on using the execunix and execwin options, see the mktrtype reference page.
133
$POSTOPCMDW = -execwin "ccperl \\\\pluto\\c$\\ucmscripts\\ex1_postop.pl"; if ($Config{osname} eq MSWin32) { $PVOBTAG = \cyclone-pvob; } else { $PVOBTAG = /pvobs/cyclone-pvob; } my my my my my my my $PREOPCMDU = ; $POSTOPCMDU = ; $STREAM = "cc5testproj_Integration\@$PVOBTAG"; $PREOPTRTYPE = "trtype:ex1_preop\@$PVOBTAG"; $POSTOPTRTYPE = "trtype:ex1_postop\@$PVOBTAG"; $CANXTRTYPE = "trtype:ex1_cancel\@$PVOBTAG"; $ATTYPE = "attype:deliver_in_progress\@$PVOBTAG"; $PVOBTAG . "\n"; $STREAM . "\n"; $PREOPTRTYPE . "\n"; $POSTOPTRTYPE . "\n"; $CANXTRTYPE . "\n"; $ATTYPE . "\n";
print `cleartool mktrtype -ucmobject -all -preop deliver_start $PREOPCMDU $PREOPCMDW -stream $STREAM -nc $PREOPTRTYPE`; print `cleartool mktrtype -ucmobject -all -postop deliver_complete $POSTOPCMDU $POSTOPCMDW -stream $STREAM -nc $POSTOPTRTYPE`; print `cleartool mktrtype -ucmobject -all -postop deliver_cancel $POSTOPCMDU $POSTOPCMDW -stream $STREAM -nc $CANXTRTYPE`; print `cleartool mkattype -vtype integer -default 1 -nc $ATTYPE`;
134
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
$msg = cleartool describe -fmt "%a" $STREAM; print $msg."\n"; if ($ENV{"CLEARCASE_CMDLINE"} eq "") { open(TEMPFH, "> $tempfile"); print TEMPFH $msg."\n"; close(TEMPFH); $cmdline = "clearprompt text -outfile $tempfile -multi_line -dfile \"$tempfile\" -prompt \"Describe Results\""; $cmdoutput = $cmdline; } if (index($msg, "deliver_in_progress") >=0) { print "***\n"; print "*** A deliver operation is already in progress. Please try again later.\n"; print "***\n"; exit 1; } $cmdline = "cleartool mkattr -default $ATTYPE $STREAM"; print $cmdline."\n"; $msg = $cmdline; $exit_value = $? >> 8; if (!($exit_value eq 0)) { print "***\n"; print "*** A deliver operation was started just before yours.\n"; print "*** That deliver operation is already in progress. Please try again later.\n"; print "***\n"; exit 1; } exit 0;
135
136
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
# Perl script to send mail on deliver complete. ################################################################## # Simple package to override the "open" method of Mail::Send so we # can control the mailing mechanism. package SendMail; use Config; use Mail::Send; @ISA = qw(Mail::Send); sub open { my $me = shift; my $how; # How to send mail my $notused; my $mailhost; # On Windows use SMTP if ($Config{osname} eq MSWin32) { $how = smtp; $mailhost = "localmail0.company.com"; } # else use defaults supplied by Mail::Mailer Mail::Mailer->new($how, $notused, $mailhost)->open($me); } # ################################################################## # Main program my @to = "developers\@company.com"; my $subject = "Delivery complete"; my $body = join , ("\n", "UCM Project: ", $ENV{CLEARCASE_PROJECT}, "\n", "UCM source stream: ", $ENV{CLEARCASE_SRC_STREAM}, "\n", "UCM destination stream: ", $ENV{CLEARCASE_STREAM}, "\n", "UCM integration activity: ", $ENV{CLEARCASE_ACTIVITY}, "\n", "UCM activities delivered: ", $ENV{CLEARCASE_DLVR_ACTS}, "\n", "UCM view: ", $ENV{CLEARCASE_VIEW_TAG}, "\n" ); my $msg = new SendMail(Subject=>$subject); $msg->to(@to); my $fh = $msg->open($me); $fh->print($body); $fh->close(); 1; # return success # ##################################################################
137
For information about sharing scripts, see Sharing triggers among different types of platform on page 131. The following mktrtype command creates a preoperation trigger type called block_integration_mkact.
cleartool mktrtype -ucmobject -all -preop mkactivity -execwin "ccperl ^ \\pluto\disk1\triggers\block_integ_mkact.pl" -execunix "Perl ^ /net/jupiter/triggers/block_integ_mkact.pl" block_integration_mkact@\my_pvob
The trigger type fires when a developer attempts to make an activity. The following preoperation trigger script runs when the block_integration_mkact trigger fires.
# Get the integration stream name for this project my $istream = cleartool lsproject -fmt "%[istream]p" $ENV{"CLEARCASE_PROJECT"}; # Get the current stream and strip off VOB tag $_ = $ENV{"CLEARCASE_STREAM"}; s/\@.*//; my $curstream = $_; # If its the same as our stream, then it is the integration stream if ($istream eq $curstream) { # Only allow this mkact if it is a result of a deliver # Determine this by checking the parent op kind if ($ENV{"CLEARCASE_POP_KIND"} ne "deliver_start") { print "Activity creation is only permitted in integration streams for delivery.\n"; exit 1 } } exit 0
The script uses the cleartool lsproject command and the CLEARCASE_PROJECT environment variable to determine the name of the projects integration stream. An integration activity is created to keep track of changes that occur during a deliver operation. The script uses the CLEARCASE_POP_KIND environment variable to determine whether the activity being created is an integration activity. If the mkactivity operation is the result of a deliver operation, the value of CLEARCASE_POP_KIND, which identifies the parent operation, is deliver_start. If the value of CLEARCASE_POP_KIND is not deliver_start, the activity is not an integration activity, and the script disallows the mkactivity operation.
138
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
cleartool mktrtype -nc -ucmobject -all -preop mkstream,mkbl,mkactivity \ -execunix "perl /net/jupiter/triggers/role_restrictions.pl" \ -execwin "ccperl \\pluto\disk1\triggers\role_restrictions.pl" \ role_restrictions@\my_pvob
The trigger type fires when a user attempts to make a baseline, stream, or activity.
my %map_op_to_roles = ( mkactivity => [ "projectmgr", "integrator", "developer" ], mkbl => [ "projectmgr", "integrator" ], mkstream => [ "projectmgr", "integrator", "developer" ], ); # Which users belong to what roles? my %map_role_to_users = ( projectmgr => [ "kate" ], integrator => [ "kate", "mike" ], developer => [ "kate", "mike", "jones" ], ); # Does user belong to any of the roles that can perform this operation? my ($role,$tmp_user); for $role (@{ $map_op_to_roles{$op} }) { for $tmp_user (@{ $map_role_to_users{$role} }) { if ($tmp_user eq $user) { return 1; } } } return 0; } sub Main { my $user = $ENV{CLEARCASE_USER}; my $proj = $ENV{CLEARCASE_PROJECT}; my $op = $ENV{CLEARCASE_OP_KIND};
Chapter 8. Using triggers to enforce UCM development policies
139
my $pop
= $ENV{CLEARCASE_POP_KIND};
my $perm = has_permission($user, $op, $proj); printf("$user %s permission to perform $op in project $proj\n", $perm ? "has" : "does NOT have"); exit($perm ? 0 : 1); } Main();
The script maps the mkactivity, mkbl, and mkstream operations to the roles that are permitted to perform them. For example, only users designated as project managers or integrators can make a baseline. The script uses the CLEARCASE_USER environment variable to retrieve the users name, the CLEARCASE_OP_KIND environment variable to identify the operation the user attempts to perform, and the CLEARCASE_POP_KIND environment variable to identify the parent operation. If the parent operation is deliver or rebase, the script does not check permissions.
140
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
Project uses
Generally, multiple-project organization falls into one of two categorizations: release-oriented and component-oriented.
Release-oriented projects
A project team can organize its work for product releases. First, the team might work on Release 1 of the product. To work on Release 2, the team branches off Release 1 and begins new development work in the Release 2 stream, and, when Release 3 work begins, it might branch off the Release 2 stream. After Release 1 ships to end users, patches for the release might be developed in its own project, which branches off Release 1. The patch project delivers its work to Release 2, so that the bug fixes can be incorporated into the new release. This type of project organization results in a cascade of branches that can cause some difficulty. To avoid the difficulty, a slightly different project organization is generally recommended for release-oriented projects (see Figure 41). In the release-oriented organization shown in Figure 41, all projects start from a foundation baseline in the Mainline project. The Webotrans_1.0 project delivers its release to the Mainline project. A patch release project Rel_1_Patch can be started from a stable baseline in the project Webotrans_1.0 and can deliver its work to the Mainline project integration stream. Instead of cascading from the previous release, a follow-on project Webotrans_2.0 is then started from the baseline in the integration stream of the Mainline project. A release-oriented project must have modifiable access to all of the components that are contained in the final product. Developers working on one component of the project need to consistently and frequently coordinate their work with developers working on other components. This type of project organization in UCM works well when there is tight coupling between components.
141
/main MP.BL0
Mainline project
R2.B1
R2.Final
Deliver operation
142
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
project manager delivers the final recommended baselines to the mainline projects integration stream. These baselines in the mainline projects integration stream serve as the foundation baselines for the Webotrans 2.0 project. When the Webotrans 2.0 team finishes its work, the project manager delivers the final recommended baselines to the mainline project integration stream, and so on. The advantage to this approach is that each project final recommended baselines are available in the mainline project integration stream.
Component-oriented Projects
Development teams can organize their work in terms of reusable assets. These teams use projects to create individual components and composite baselines that select baselines of several components. Low-level or core components can be used to construct mid-level components or subsystems, until the highest level components are integrated into a product. The goal of a component-oriented project is to produce a composite baseline or a set of baselines that represents the integration of the shared components into a subsystem (see Figure 42).
143
Project Y BCD.BL0
Project Z
AC.BL1
ABCDE.BL1
BCD.BL1
In Figure 42, project X uses components A and C to produce a set of baselines that define the X subsystem, and project Z uses components B, C, and D to implement the Z subsystem. Project Y uses the subsystems created by the X and Z projects, represented by the baselines that these projects produce. Additionally, project Y does custom work in component E. The key attribute of managing the configuration is that all the code of a subsystem is released together. To the development team, the important factor is that the subsystem represents assets that can be easily reused. Designing a product, or a family of products based on subsystems allows the development effort to be divided into logical units. This organization simplifies the development efforts, allows better management for risk, and provides opportunities for code reuse. The key aspect of this organization is that each project has access to two classes of components: modifiable components and read-only components. Each project does its development work on modifiable components, and only one project can modify these components. The read-only components are shared, but projects do not plan to modify the read-only components, because that violates the sharing model. Accordingly, these shared components are specified to be read-only in the project. The teams in a development group with this type of project organization are restricted to a limited number of components that they can modify. Because the lower level components can be shared, the changes must be made in a central, compatible manner, in the project dedicated to that component. For example, if project Y needs changes in the A and C components, that work must be done in project X. In a component-oriented organization, each project has more freedom in selecting baselines of shared components. Because these shared components are not modified by the project, theoretically the project should be able to change from one version of a shared component to any other version of that component. The component-oriented project organization works well when components are loosely coupled with well-defined interfaces. This type of project organization tends to promote component reuse more effectively than the release-oriented project organization does.
144
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
AC.BL1
BCD_BL1
E_BL0
A.BL1
C.BL3
B.BL1
C.BL1
D.BL1
Project Y is composed of the custom component E and the components AC and BCD, which both share component C. It does not matter whether baseline E.BL1 is a product, a .DLL, a lower-level library, or another component. In the composite baseline E.BL1, a component-oriented approach to development can be more prone to baseline conflicts than a release-oriented approach. The frequency of baseline conflicts depends on the following factors. v The number of shared components v The processes in the development organization v The coordination among the different teams developing subsystems The more closely the teams that produce each component coordinate their work, the less likely conflicts will occur. If development teams need complete freedom in selecting baselines of the components that they use, conflicts are more likely. Conflicts occur because of the difficulty in ensuring that a random baseline of one component, for example, AC, will work with a random baseline of another component. Baseline E.BL1 can be considered as consuming baselines AC.BL1 and BCD.BL1. However, it is not a true producer and consumer relationship. Composite baseline E.BL1 is not using the AC.BL1 baseline; it is using AC.BL1 plus the override, baseline Cx.BL3 (see Figure 43). Therefore, baseline E.BL1 is not actually using the product of project X. The X project does produce AC baselines, but, in a situation with conflicts, the baseline is a guideline rather than a rule for projects that need the AC component.
145
If these subsystems were in a release-oriented organization, composite baselines would represent a tight coupling of baselines, for example, baselines A.BL1 and C.BL3 shall be used to make baseline AC.BL1. But in a component-oriented organization, composite baselines represent a looser coupling, that is, baselines A.BL1 and C.BL3 should be used to make baseline AC.BL1. But the project integrator can chose to override the coupling between baselines. Therefore, in a component-oriented organization of projects, a composite baseline is more of an indication of the components that should be used to create a subsystem rather than a requirement to use them. Therefore, selecting a baseline override in a component-oriented organization needs to be careful and deliberate. Project integrators need to be aware that, in selecting a baseline override, they are changing the decisions made by the project that produced the component. There might be specific reasons why the BCD component is compatible with the C.BL1 baseline, for example, a different baseline could cause the component to fail. Often, using a descendant of baseline C.BL1 is successful, but the selection of override baselines is not restricted in the ClearCase environment. There is no guarantee of the relationship between baseline C.BL1 and the override baseline Cx.BL3. As the time approaches for a component to be completed, the use of baseline overrides can be destabilizing to a product, because they can represent significant code differences. These differences can be managed by coordinating the work of the projects that produce each subsystem. As the time for completing a component approaches, the teams can agree on the lower-level components so that conflicts are reduced.
Bootstrap projects
If baseline relationships are known at the start of development and they do not change much after that, you can use a bootstrap project to configure other projects with a single composite baseline as the foundation baseline. When you create a composite baseline for a project, the foundation baselines of the integration stream are not affected. After the creation of the composite baseline, the foundation of the stream still contains the baselines of the individual member components. For development streams in the project to appropriately use the composite baseline, you simply recommend just the composite baseline in the integration stream. If all the member baselines remain listed in the foundation of the integration stream, individual developers who have to rebase to the recommended baseline can be confused by multiple baselines being listed. To reduce the confusion, set up a special project to bootstrap the composite baseline for other projects. The bootstrap project includes all of the components in its foundation. You create the composite baseline in the bootstrap project and then create a development project with this initial composite baseline as its foundation. As a result, in the development project, the integration stream and the development streams have similar foundation sets. The project integrators do not have to keep track of the individual baselines, since the project can start with a single, all-inclusive composite baseline. Developers in the projects that follow are less likely to be confused when they select a baseline during a rebase operation.
146
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
component-oriented projects. You can mix the two strategies, so that some projects produce certain components, and other projects integrate components into a release.
147
BL2
Create project
Beta
Beta
BL1
FCS
FCS
148
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
7.
8.
9. 10.
This updates the Change Baseline window with the set of baselines available in the other project integration stream. In the Change Baseline window, select the component. The Baselines list displays all baselines available for the selected component in the other projects integration stream. Select the baseline to which you want to rebase your integration stream. Click OK. The baseline that you selected now appears in the Change Rebase Configuration window. Repeat Step 4 on page 148 through Step 7 on page 149 until you finish selecting the set of baselines to which you want to rebase your integration stream. Click OK to close the Change Rebase Configuration window. Click OK in the Rebase Stream Preview window. All nonconflicting changes are merged automatically. If there are conflicting changes, a prompt asks you whether to start Diff Merge, a tool with which you resolve conflicting changes. For details on using Diff Merge, see the Diff Merge Help and Developing Software online help.
Tip: You can rebase your projects integration stream only if the baseline to which you are rebasing is a successor of the current foundation baseline of your integration stream. In the previous example, the FCS baseline is a successor to the Beta baseline, which is the current foundation baseline for the Webotrans 4.1 integration stream.
PA.BL1 PA.BL1
Stream DA
a1 DA.BL2 Project PB
DB.BL1
Deliver operation
Work is in progress in project PA, but must be delivered before work in stream DA can be completed. Follow-on work continues in project PB which starts from
Chapter 9. Managing multiple projects
149
recommended baselines PA.BL2 in the integration stream of project PA. (The integration streams in projects PA and PB are siblings because they share a parent, project PA.) You can migrate the changes in activity a1 to a cousin stream DB in project PB by using an alternate target deliver operation. Only the changes in activity a1 are delivered because the remaining contents of stream DA are in stream DB. Work on the feature that started in stream DA can be continued in stream DB.
Create projects
FCS
FCS
FCS
BL1
BL1
BL2
BL2 merge
Figure 46. Incorporating a patch release
In this example shown in Figure 46: v Both the Webotrans 3.0 Patch and Webotrans 4.0 projects use the FCS baselines of the components in the Webotrans 3.0 project as their foundation baselines.
150
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
The purpose of the patch release is to fix a problem detected after Webotrans 3.0 was released. Webotrans 4.0 represents the next major release of the Webotrans product. v Development continues in both the 3.0 Patch and 4.0 projects, with the integrators creating baselines periodically. v The developers working on the 3.0 Patch project finish their work, and the integrator incorporates the final changes in the BL2 baseline. The integrator then needs to deliver those changes from the 3.0 Patch integration stream to the 4.0 integration stream so that the 4.0 project contains the fix.
151
BL1
BL2
BL2
FINAL
BL3
The integrators rebase the integration stream in the Webotrans 3.0 Patch project to baselines BL1 and BL2 from the Webotrans 4.0 project. Rebasing in this situation allows the integrators to test and validate the patch with ongoing development in the follow-on project. When the integrators deliver the patch changes in the FINAL baseline, the process of testing and validating the patch in Webotrans 4.0 integration stream is made much easier. Note: From an integration stream, you can deliver only baselines and not individual activities.
use strict; my my my my $mergeopts = print; $project = shift @ARGV; $pvob = shift @ARGV; $bl;
152
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
chdir ($pvob) or die("cant cd to project VOB $pvob"); print("######## Getting recommended baselines for project $project\n"); my @recbls = split( , cleartool lsproject fmt "%[rec_bls]p" $project); foreach $bl (@recbls) { my $comp = cleartool lsbl fmt "%[component]p" $bl; my $vob = cleartool lscomp fmt "%[root_dir]p" $comp; print("######## Merging changes from baseline $bl of $vob\n"); my $st = system("cleartool findmerge $vob fver $bl $mergeopts"); $st == 0 or die("findmerge error"); } exit 0;
The script finds the recommended baselines for the integration stream from which you are merging. It then uses the cleartool findmerge command to find differences between the versions represented by those recommended baselines and the latest versions in the target branch. For details, see the findmerge reference page. You can add error handling and other logic appropriate for your site to this script before using it.
153
154
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
155
156
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
157
The IBM Rational ClearCase Administrators Guide includes detailed information on these topics.
158
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
Branch names
It is a good idea to establish naming conventions that indicate the work the branch contains. For example, rel2.1_main is the branch on which all code for Release 2.1 ultimately resides, rel2.1_feature_abc contains changes specific to the ABC feature, and rel2.1_bl2 is the second stable baseline of Release 2.1 code. (If necessary, branch names can be much longer and more descriptive, but long branch names can crowd a version tree display.) Note: Make sure that you do not create a branch type with the same name as a label type. This can cause problems when config specs use labels in version selectors. For example, make all branch names lowercase, and make all label names uppercase.
159
Using labels
A label is a user-defined name that can be attached to a version. Labels are a powerful tool for project managers and system integrators. By applying labels to groups of elements, you can define and preserve the relationship of a set of file and directory versions to each other at a given point in the development life cycle. For example, you can apply labels to these versions: v All versions considered stable after integration and testing. Use this baseline label as the foundation for new work. v All versions that are partially stable or contain some usable subset of functionality. Use this checkpoint label for intermediate testing or as a point to which development can be rolled back in the event that subsequent changes result in regressions or instability. v All versions that contain changes to implement a particular feature or that are part of a patch release.
160
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
For more information on these mechanisms, see Chapter 12, Implementing project development policies, on page 179. A lock on an element or directory prevents all developers (except those included on an exception list) from modifying it. Locks are useful for implementing temporary restrictions. For example, during an integration period, a lock on a single objectthe main branch typeprevents all users who are not on the integration team from making any changes. The effect of a lock can be small or large. A lock can prevent any new development on a particular branch of a particular element; another lock can apply to the entire VOB, preventing developers from creating any new element of type compressed_file or using the version label RLS_1.3. Locks can also be used to retire names, views, and VOBs that are no longer used. For this purpose, the locked objects can be tagged as obsolete, effectively making them invisible to most commands.
Global types
The Rational ClearCase global type facility makes it easy for you to ensure that the branch, label, attribute, hyperlink, and element types they need are present in all VOBs your project uses. The IBM Rational ClearCase Administrators Guide has more information about creating and using global types.
Generating reports
An event record is created and stored each time an element is modified or merged. Many Rational ClearCase commands include selection and filtering options that you can use to create reports based on these records. The scope of such reports can cover a single element for a set of objects or for entire VOBs. You can use event records and metadata to implement project policies. (For more detail, see Chapter 12, Implementing project development policies, on page 179.) Event records and other metadata can also be useful if you need to generate reports on activities managed by Rational ClearCase operations (for example, the complete history of changes to an element). a variety of report-generation tools are provided. For more information on this topic, see the fmt_ccase reference page in the IBM Rational ClearCase Command Reference.
Integrating changes
During the lifetime of a project, the contents of individual elements diverge as they are branched and usually converge in a merge operation. Typically, the project manager periodically merges most branches back to the main branch to ensure that the code base maintains a high degree of integrity and to have a single latest version of each element from which new versions can safely branch. Without regular merges, the code base quickly develops a number of dangling branches, each with slightly different contents. In such situations, a change made to one version must be propagated by hand to other versions, a tedious process that is prone to error. As a project manager, you must establish merge policies for your project. Typical policies include the following: v Developers merge their changes to the main branch. This can work well when the number of developers or the number of changed files is small and the developers are familiar with the mechanics of merging. Developers must also
Chapter 10. Managing projects in base ClearCase
161
understand the nature of other changes they may encounter when the merge target is not the immediate predecessor of the version being merged, which happens when several developers are working on the same file in parallel. v Developers merge their changes to an integration branch. This provides a buffer between individual developers merges and the main branch. The project manager or system integrator then merges the integration branch to the main branch. v Developers must merge from the main branch to their development branch before merging to the main branch or integration branch. This type of merge promotes greater stability by forcing merge-related instability to the developers private branches, where problems can be resolved before they affect the rest of the team. v The project manager designates slots for developer merges to the main branch. This is a variation on several of the mechanisms already described. It provides an additional level of control in situations where parallel development is going on. For more information about merging, see Chapter 14, Integrating changes, on page 219.
162
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
163
The view also selects all other elements (that is, all elements that you have not checked out) on a read-only basis. If another user checks in a new version on the main branch of such an element, the new LATEST version appears in this dynamic view immediately. By default, snapshot views also include the two version selection rules shown above. In addition, snapshot view config specs include load rules, which specify which elements or subtrees to load into the snapshot view. For details on creating snapshot views, see Developing Software online help. Product Note: Rational ClearCase LT supports only snapshot views.
In this example, the config spec continues to select version 7 of element cmd.c, which is read-only. A read-write copy of this version, cmd.c.checkedout, is created in view-private storage. (This is not a recommended way of working.) The /main/LATEST rule selects the most recent version on the main branch to appear in the view. In addition, a /main/LATEST rule is required to create new elements in a view. If you create a new element when this rule is omitted, your view does not select that element. (Creating an element involves creating a main branch and an empty version, /main/0.)
164
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
sources, or you must store the config spec in a directory on Linux and the UNIX system that is also accessible from the Windows platform. If you want to modify this config spec (for example, to adopt the no-directory-branching policy), only the contents of major.csp need to change.
This command causes the view server to flush its caches and reevaluate the current config spec.
For the purposes of this chapter, suppose that the lib directory has this substructure:
lib/ libcalc.a libcmd.a libparse.a libpub.a libaux1.a libaux2.a libcalc/ libcmd/ libparse/ libpub/ libaux1/ libaux2/ (checked-in staged version library) (checked-in staged version library) (checked-in staged version library) (checked-in staged version library) (checked-in staged version library) (checked-in staged version library) (sources for calc library) (sources for cmd library) (sources for parse library) (sources for pub library) (sources for aux1 library) (sources for aux2 library) of of of of of of
Sources for libraries are located in subdirectories of lib. After a library is built in its source directory, it can be staged to /vobs_monet/lib.
165
On Linux and the UNIX system, the build scripts for the project executable programs can instruct the link editor, ld(1), to use the libraries in this directory (the library staging area) instead of a more standard location (for example, /usr/local/lib). On the Windows system, you can use the libraries in this directory (the library staging area) instead of a more standard location by setting the LIB environment variable or by changing the makefile. The following labels are assigned to versions of vobs_monet elements. Version Labels R1.0 R2_BL1 R2_BL2 R2.0 Description First customer release Baseline 1 prior to second customer release Baseline 2 prior to second customer release Second customer release
These version labels have been assigned to versions on the main branch of each element. Most project development work takes place on the main branch. For some special tasks, development takes places on a subbranch. Subbranches major Description Used for work on the applications graphical user interface, certain computational algorithms, and other major enhancements Used for fixing bugs in Release 1.0
r1_fix
Windows Note: Config specs allow absolute VOB pathsabsolute paths that begin with a VOB tag but do not include a drive or view tag prefix. This form of path is required to specify VOB elements without regard for current drive assignments or active views. For example: \vob_gopher\lib\* (absolute VOB path, where \vob_gopher is the VOB tag) \monet\src\* (absolute VOB path, where \monet is the VOB tag) Z:\monet\src\* (drive-specific path; not recommended) M:\myview\vob_gopher\lib\* (view-extended path; not recommended)
166
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
The major branches are created at versions that constitute a consistent baseline: a major release, a minor release, or a set of versions that produces a working version of the application. In this config spec, the baseline is defined by the version label BASELINE_X.
Note the following points about the configuration: v Elements can be checked out (Rule 1). v The checkout command creates a branch named r1_fix at the initially selected version (the auto-make-branch clause in Rule 3). A key aspect of this scheme is that the same branch name, r1_fix, is used in every modified element. The only administrative overhead is the creation of a single branch type, r1_fix, with the mkbrtype command. This config spec is efficient. Two rules (Rules 2 and 3) configure the appropriate versions of all elements: v For elements that have been modified, this version is the most recent on the r1_fix subbranch (Rule 2). v For elements that have not been modified, this version is the one labeled R1.0 (Rule 3). Figure 48 illustrates these elements. The r1_fix branch is a subbranch of the main branch. But Rule 2 handles the more general case, too. The ... wildcard allows the r1_fix branch to occur anywhere in the version tree of any element, and at different locations in the version trees of different elements.
167
1 r1_fix 0 2
R1.0
1 Created by Rule 2
3 4
A view configured with this config spec is appropriate in the following situation: v All changes from the baseline designated by the BASELINE_X version label must be made on a branch named major.
168
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
v Moreover, you are working on a special project, whose changes are to be made on a subbranch of major, named autumn. Figure 49 shows what happens in such a view when you check out an element that has not been modified since the baseline.
Rule 4 main 0
Rule 3 main 0
Rule 2 main 0
1 major 2 0
1 major 2 0 autumn 1 1 0
1 major 2 0 autumn 1 0
1
Figure 49. Multiple-level auto-make-branch
1. After an element is checked out, the mkbranch clause in Rule 4 creates the major branch at the BASELINE_X version. 2. The mkbranch clause in Rule 3 creates the autumn branch at \main\major\0. 3. When the checkout operation finishes, Rule 2 applies; the most recent version, \main\major\autumn\0, is checked out. For more information about multiple-level branching, see the config_spec and checkout reference pages.
169
The backslash ( \ ) is required in the C shell only, to keep the exclamation point ( ! ) from indicating a history substitution. On the Windows system:
cleartool find . branch "{brtype(major) && ! attype_sub(QAOK)}" print
The attype_sub primitive searches for attributes on versions and branches of an element and on the element itself. This scheme allows the QA team to monitor the progress of the rest of the group (see Figure 50).
170
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
main 0
1 major 2 0 3 1 4 2 Version that the development config spec selects Version that the QA config spec selects
The development config spec always selects the most recent version on the major branch, but the QA config spec may select an intermediate version.
171
major 0
Performing a checkout in this view checks out version /main/major/3, not version /main/major/2, and generates the following message:
cleartool: Warning: Version checked out is different from version previously selected by view. Checked out "cmd.c" from version "/main/major/3".
This behavior reflects the Rational ClearCase restriction that new versions can be created only at the end of a branch. Although such operations are possible, they are potentially confusing to other team members. And, in this situation, it is almost certainly not what the developer who checks out the element wants to happen. You can avoid the problem by making the following indicated changes in the config spec: (0) element * CHECKEDOUT (0a) element * /main/major/temp/LATEST (1) element file src/* /main/major/{QAOK=="Yes"} mkbranch temp (2) element * /main/LATEST The modified config spec creates another branching level at the version that the attribute selects.
172
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
The output of the cleartool ls command distinguishes jacksons files from the others: each entry includes an annotation as to which configuration rule applies to the selected version. This is a research view, not a development view. The selected set of files may not be consistent: some of jacksons changes may rely on changes made by others, and those other changes are excluded from this view. Thus, this config spec omits the standard CHECKEDOUT and /main/LATEST rules.
173
174
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
For example, lib_selector attributes can take values such as experimental, stable, and released.
175
record the makefile version in the config record by including the special clearmake macro invocation $(MAKEFILE) in the target dependency list in the following formats: On the Windows system:
monet.exe: $(MAKEFILE) monet.obj ... link out:monet.exe monet.obj ...
The clearmake command always records the versions of explicit dependencies in the config record. Alternatively, you can configure the makefile at the source level: attach a version label to the makefile at build time, and then use a config spec like the one in Historical view defined by a version label on page 173 or View to modify an old configuration on page 167 to configure a view for building. You can also use the special target .DEPENDENCY_IGNORED_FOR_REUSE. For more information, see IBM Rational ClearCase Guide to Building Software.
176
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
As described in Fixing bugs in the program on page 176, you can modify this config spec to change the build configuration to a development configuration.
Sharing config specs among Linux, the UNIX system, and Windows system
In principle, you can share config specs among Linux, the UNIX system, and the Windows system. That is, users on all types of systems, using views whose storage directories reside on another type of platform, can set and edit the same set of config specs. You should avoid sharing config specs across platforms. If possible, maintain separate config specs for each platform. However, if you must share config specs, adhere to the following requirements: v Use slashes (/) in paths instead of backslashes (\). v Use relative paths instead of full paths, whenever possible. And do not use VOB tags in paths. You can ignore this requirement if your VOB tags on Linux, the UNIX system, and Windows systems all use single, identical path components that differ only in their leading slash characters, for example \src and /src. v Always edit and set config specs on Linux or the UNIX system. For more information, see Path separators on page 177, Paths in config spec element rules on page 177, and Config spec compilation on page 178.
Path separators
When writing config specs to be shared by the Windows, Linux, and the UNIX system, you must use slash (/) as the path separator instead of backslash (\). In Rational ClearCase configurations on Linux or the UNIX system, only slashes are recognized. Tip: The cleartool command recognizes both slashes and backslashes in paths; clearmake is less flexible. See IBM Rational ClearCase Guide to Building Software for more information.)
177
v Shared VOBs are registered with identical, single-component VOB tags in the network regions of the Windows system and Linux and the UNIX system. (The VOB tags \r3vob and /r3vob are treated as if they were identical because they differ only in the leading slashes.)
If the VOB is registered with VOB tag \vob_p2 on a Windows network region, but with VOB tag /vobs/vob_p2 in the network region on Linux and the UNIX system, only Windows computers can compile the config spec. To address the problem, do one of the following: v Use relative paths that do not include VOB tags, for example:
element ...\abc_proj_src\* \main\rel2\LATEST
v On Linux and the UNIX system, change the VOB tag so that it has a single component, for example, /vob_p2.
178
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
179
ACCEPT=0 REJECT=1 WORDCOUNT=echo $CLEARCASE_COMMENT | wc -w if [ $WORDCOUNT -ge 10 ] ; then exit $ACCEPT else exit $REJECT fi
The trigger action script analyzes the users comment (passed in an environment variable), and disallows unacceptable ones.
Developers apply the Status attribute to many different versions of an element. Its value in early versions on a branch is likely to be inactive and under_devt; on later versions, its value is QA_approved. The same value can be used for several versions, or moved from an earlier version to a later version. To enforce consistent application of this attribute to versions of all source files, you can create a CheckStatus trigger whose action script prevents developers from checking in versions that do not have a Status attribute. Trigger definition on Linux and the UNIX system:
cleartool mktrtype element all preop checkin \ c "all versions must have Status attribute" \ exec Perl /public/scripts/check_status.pl CheckStatus
180
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
Alternatively, you can use the configuration records of the release derived objects to control the labeling process:
clearmake vega ... sometime later, after QA approves the build: cleartool mklabel config vega@@17-Jun.18:05 REL2
Using configuration records to attach version labels ensures accurate and complete labeling, even if developers have created new versions since the release build. Development work can continue while quality assurance and release procedures are performed. To prevent version label REL2 from being used again, you must lock the label type:
cleartool lock nusers vobadm lbtype:REL2
The object is locked to all users except those specified with the nusers option, in this case, vobadm.
181
If all fixes are made in one or more views with this configuration, the changes are isolated on branches of type rel2_bugfix. The mkbranch option causes such branches to be created, as needed, when elements are checked out. This config spec selects versions from rel2_bugfix branches, where branches of this type exist; it creates such a branch whenever a REL2 version is checked out.
v To select your own work, plus the latest versions as of Sunday evening:
element * CHECKEDOUT element * /main/LATEST -time Sunday.18:00
v To select your own work, new versions created in the graphics directory, and the versions that went into a previous build:
element * CHECKEDOUT element graphics/* /main/LATEST element * -config myprog@@12-Jul.00:30
v To select your own work, the versions either you (jones) or Mary has checked in today, and the most recent quality-assurance versions:
element * CHECKEDOUT element * /main/{ created_since(06:00) && ( created_by(jones) || created_by(mary) ) } element * /main/{QAed=="TRUE"}
v To use the config spec include facility to set up standard sets of configuration rules for developers to add to their own config specs:
element * CHECKEDOUT element msg.c /main/18 include /usr/cspecs/rules_for_rel2_maintenance
v Lock the header files for all users except Mary and Fred:
cleartool lock nusers mary,fred src/pub/*.h
182
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
183
$ver = $ENV{CLEARCASE_XPN}; $user = $ENV{CLEARCASE_USER}; $comment = $ENV{CLEARCASE_COMMENT}; $var = "Version: $ver\nUser: $user\nComment: $comment\n"; $smtp->datasend($var); $smtp->dataend(); $smtp->quit;
2. Place the trigger on the attached list of all existing file elements within the GUI source tree:
cleartool find /vobs/gui_src type f \ exec cleartool mktrigger InformWriters $CLEARCASE_PN
This trigger type ApplyMetrics applies to all elements; it fires when any element of type c_source is checked in. (When a new c_source element is created, the element is monitored.) If a developer attempts to check in a c_source file that fails the apply_metrics.sh or appl_met.bat test, the checkin fails. Tip: The apply_metrics.sh script and the appl_met.bat file can read the value of CLEARCASE_PN from its environment. Having it accept a file name argument provides flexibility because the script or batch file can be invoked as a trigger action, and developers can also use it manually.
184
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
Then, define an all-element trigger type, EcoTrigger, which fires whenever a new version is created and runs a script to attach the ECO attribute. Trigger definition:
cleartool mktrtype element all postop checkin \ c "associate change with bug number" \ execunix Perl /public/scripts/eco.pl \ execwin ccperl \\neon\scripts\eco.pl EcoTrigger Created trigger type "EcoTrigger".
When a new version is created, the attribute is attached to the version. For example:
cleartool checkin c "fixes for 4.0" src.c Enter the bug number associated with this checkin: 2347 Created attribute "ECO" on "/vobs/dev/src.c@@/main/2". Checked in "src.c" version "/main/2". cleartool describe src.c@@/main/2 version "src.c@@/main/2" ... Attributes: ECO = 2347
The hyperlink inheritance feature enables the implementation of requirements tracing: v When the source module, hello.c, and the design document, hello_dsn.doc, are updated, you create a new hyperlink connecting the two updated versions:
cleartool mkhlink -c "source doc" DesignDoc hello.c /vobs/design/hello_dsn.doc Created hyperlink "DesignDoc@90@/vobs/dev".
v When either the source module or the design document incorporates a minor update, no hyperlink-level change is required. The new version inherits the hyperlink connection of its predecessor.
Chapter 12. Implementing project development policies
185
To list the inherited hyperlink, use the ihlink option to the describe command. On Linux and the UNIX system:
version that inherits hyperlink-> version to which -> hyperlink is explicitly attached cleartool describe ihlink DesignDoc hello.c@@/main/2 hello.c@@/main/2 Inherited hyperlinks: DesignDoc@90@/vobs/dev /vobs/dev/hello.c@@/main/1 -> /vobs/doc/hello_dsn.doc@@/main/1
v When either the source module or the design document incorporates a significant update, which renders the connection invalid, you create a null-ended hyperlink to sever the connection.
cleartool mkhlink -c "sever connection to design doc" DesignDoc hello.c Created hyperlink "DesignDoc@94@/vobs/dev".
Figure 52 illustrates the hyperlinks that connect the source file to the design document.
186
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
When user tony tries to run the chmaster command on a restricted object, the command fails. For example:
cleartool chmaster c "give mastership to london" london@/vobs/dev \ /vobs/dev/acc.c@@/main/lex_dev cleartool: Warning: Trigger "elem_chmaster_ACL" has refused to let chmaster proceed. cleartool: Error: Unable to perform operation "change master" in replica "lex" of VOB "/vobs/dev".
187
replica to master a branch at any given time. Therefore, if a developer at another site needs to work on the element, mastership of the branch must be transferred to that site. Rational ClearCase MultiSite provides the following models for transferring mastership of a branch: v The push model, in which the administrator at the replica that masters the branch uses the chmaster command to give mastership to another replica. This model is not efficient in a branch-sharing situation, because it requires communication with an administrator at a remote site. For more information about this model, see the IBM Rational ClearCase Administrators Guide. v The pull model, in which the developer who needs to work on the branch uses the reqmaster command to request mastership of it. Tip: The developer can also request mastership of branch types. For more information, see the IBM Rational ClearCase Administrators Guide. The pull model requires the Rational ClearCase MultiSite administrators to enable requests for mastership in each replica and to authorize individual developers to request mastership. If you decide to implement this model, you must provide the following information to your Rational ClearCase MultiSite administrator: Replicated VOBs that should be enabled to handle mastership requests Identities (domain names and user names) of developers who should be authorized to request mastership Branch types and branches for which mastership requests should be denied (for example, branch types that are site specific, or branches that must remain under the control of a single site) The IBM Rational ClearCase MultiSite Administrators Guide describes the process of enabling the pull model and a scenario in which developers use the pull model. The Developing Software online help describes the procedure developers use to request mastership.
188
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
This technique allows a single trigger type to use different paths for the scripts or to use completely different scripts on Linux or the UNIX system and the Windows computer. For example:
cleartool mktrtype element all nc preop checkin execunix /public/scripts/precheckin.sh execwin \\neon\scripts\precheckin.bat pre_ci_trig
Tip: The command line example is broken across lines to make the example easier to read. You must enter the command on one line. On Linux or the UNIX system, only the script precheckin.sh runs. On the Windows system, only precheckin.bat runs. To prevent users on a new platform from bypassing the trigger process, triggers that specify only execunix always fail on the Windows system. Likewise, triggers that specify only execwin fail on Linux and the UNIX system.
Note: In your scripts, you can run ratlperl directly. Ensure that you include the following default paths to execute the scripts successfully: v On Linux and the UNIX system: /opt/rational/common/ v On the Windows system: <install_location>\Rational\Common\ The value install_location is the root folder in which you installed Rational ClearCase.
189
190
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
Chapter 13. Setting up the base ClearCase integration with Rational ClearQuest
This chapter provides an overview of the base ClearCase integration with Rational ClearQuest and describes how to set up the integration. For information about working in the integration, see Developing Software online help.
191
Query support
Queries in a Rational ClearQuest user database are run by the integration either from a trigger firing or from an explicit developer selection in one of the integration interfaces (either Browse in the GUI or Queryname in the command line interface). You can make these queries available in the following ways: v Provide queries in either the Personal Queries or Public Queries folder in a Rational ClearQuest user database (Rational ClearQuest queries). v Define queries in the integration configuration file (local queries). By default, only local queries are available to developers. The Web interface supports only local queries. For more information, see Controlling query usage on page 210. In making queries available to developers, keep in mind the following limitations:
192
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
v Currently there is no support for queries that prompt the developer for runtime parameters. That is, Rational ClearQuest queries that contain dynamic filters are not supported, and, if dynamic filters are used in queries in the integration, they act as if default values were selected without user interaction. v Only single-line text fields in query results are supported in both Rational ClearQuest and local queries. The integration provides no special handling for multiple-line output within text fields. v The first field in the query result set must be the Rational ClearQuest record ID. For more information, see SetResultSet on page 206.
193
If you are configuring the integration for the first time, use the V2-Perl trigger. If you currently use the V1-Visual Basic trigger, evaluate the V2-Perl trigger and consider migrating to it. The V2-Perl trigger uses a configuration file called config.pl, which specifies your local configuration parameters or centrally-defined configuration parameters.
194
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
Support, you can receive internal documentation that describes making changes through creating and using subclasses in the Perl trigger. To enable local sites to make judicious changes, the requested internal documentation describes the use of subclasses to separate changes that you make and the main body of code that is supplied with the product. For information on using the subclasses, see Customizing the integration on page 217. But local source code changes cannot be and are not supported by IBM Customer Support.
Chapter 13. Setting up the base ClearCase integration with Rational ClearQuest
195
196
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
Chapter 13. Setting up the base ClearCase integration with Rational ClearQuest
197
The base ClearCase integration with Rational ClearQuest uses Rational ClearCase element triggers on cleartool checkin (preoperation and postoperation), checkout (postoperation), and uncheckout (preoperation) commands to allow developers to associate versions with Rational ClearQuest change requests. To start the Rational ClearQuest Integration Configuration tool, see To start the Rational ClearQuest Integration Configuration tool on page 199.
By default, the cqcc_launch script is installed in the following location on each local client:
ccasehomedir/bin
On the Linux and UNIX system, the script is cqcc_launch; on the Windows system, the script is cqcc_launch.bat. In this configuration, each time the integration starts or a trigger fires on a client machine, the local instances of the configuration file, the cqcc_launch script, and trigger scripts are run. This is the default configuration. To define a central location for accessing a shared, centrally located configuration file, in the Rational ClearQuest Integration Configuration tool, provide a sitewide path to the configuration file. To provide the path, change the Path field to a UNC path to a Windows system or to a full path to the Linux or the UNIX system that contains the configuration file and the cqcc_launch script. The integration uses that one central configuration file and the cqcc_launch script for all users of VOBs that are enabled for Rational ClearQuest. All users will run the shared, centrally located copy of the config.pl file. This configuration uses local copies of trigger scripts. If you set Use trigger scripts in Path directory, you can use shared, centrally located trigger scripts with the centrally located configuration file. This setting allows you to centralize the trigger source code in one location. Triggers installed with this option look for the configuration file, cqcc_launch script, and trigger source code in the same directory in which the configuration file is located. This is the best configuration because it is easiest to secure and maintain. If you use a centrally located configuration file or trigger scripts, perform some housekeeping procedures to set up the central location. This set-up involves copying the requisite files from the installed location on a Rational ClearCase system to the central location. For more information, see the online Help in the Rational ClearQuest Integration Configuration tool.
198
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
In support of the configuration, the cqcc_launch script provides as a convenience the following command-line option:
cqcc_launch -vob
This command searches the current VOB for its checkout trigger to determine the correct paths and configuration file to use in launching the script.
Chapter 13. Setting up the base ClearCase integration with Rational ClearQuest
199
Information about the triggers defined in the specified VOB are displayed. For example:
cleartool lstype -kind trtype -invob \my_vob 08-Jun.08:07 username trigger type "cq_ci_trigger" "ClearQuest Integration" 08-Jun.08:07 username trigger type "cq_co_trigger" "ClearQuest Integration" 08-Jun.08:07 username trigger type "cq_postci_trigger" "ClearQuest Integration" 08-Jun.08:07 username trigger type "cq_unco_trigger" "ClearQuest Integration"
Use the describe command to see information about a specific base ClearCase integration with Rational ClearQuest trigger. For example: On Linux and the UNIX system:
cleartool describe trtype:cq_co_trigger@vob:/vobs/my_vob
200
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
If there is no existing file with the same name, the following file is also placed on the system:
ccasehomedir\lib\CQCC\config.pl
If the local configuration file config.pl exists, the installation tries to avoid replacing that file because it contains your changes. The installation action depends on the platform type. v On Linux and the UNIX system, no new version of the config.pl file is installed. The current version is preserved. To take advantage of the latest changes, copy the new information from the configTemplate.pl file to the config.pl file. v On the Windows system, if the installed version is not modified (based on comparing the date stamp on the file and the original installation date), the latest version of the config.pl file is installed. If the installed version is modified, no new version of the file is installed. The current version is preserved. To see the latest changes in configuration information, compare the config.pl and the configTemplate.pl files. If you make changes to your configuration, edit the configTemplate.pl file and save the changes to both configTemplate.pl and config.pl. By locating the configuration file in a central place, you simplify the task of implementing the latest changes. For more information, see Using a shared configuration file and triggers on page 198. If you uninstall Rational ClearCase, both configTemplate.pl and config.pl are removed from the system. However, on Linux and the UNIX system, the config.pl file is first copied to the standard file preservation area and then removed from its original location.
The [ENV] notation indicates whether the related configuration parameter can be set as an environment variable in the developers context. In the Default: entry, value indicates what the integration uses if you do not edit the sample line. The line with values shows all possible selections that you can use in the Sample to enable line. Edit the sample line with your change and remove the pound (#) character from the beginning of the line to enable your change.
201
v Connecting Rational ClearCase clients and a Rational ClearQuest user database on page 203 v Making policy choices on page 209 v Enhancing performance on page 211 v Debugging and analyzing operations on page 215 Table 6 summarizes the configuration parameters that you can set in the config.pl file. Some of the configuration parameters have related environment variables of the same name that you or your developers can set in their local context. These parameters are noted by Yes in the Locally settable column of Table 6. All parameters are described more fully in the subsequent sections about functional capabilities.
Table 6. Configuration parameters summary Configuration parameter CQCC_ASSOC_BATCH_CONFIRM CQCC_ASSOC_BATCH_ENABLE Description Displays a window that confirms that the batch completed successfully. Allows delay in processing multiple Rational ClearQuest association transactions until end of single Rational ClearCase operation or user-defined batch Specifies that a user-defined series is active and normal Rational ClearCase series-end processing should be suppressed Sets one or more change requests for automatic association on checkout and checkin without user interaction Specifies whether developers can use CQCC_AUTO_ASSOCIATE Sets pattern by which developers can make associations in a checkout or checkin comment Forces use of Rational ClearQuest Web interface Specify either 2.0 (Java) or "1.0" (ASP with IIS) as Rational ClearQuest Web server protocol Defines logical name of database and related record types (entities) that support associations. Database set name (connection) for one of multiple schema repositories; used with CQCC_DATABASE_ENTITY_LIST Controls level of output generated for problem diagnosis; 0 (none), 1 (basic), 2 (verbose) Allows use of Perl/TK graphic user interface Records to a log file messages for problem diagnosis Locally settable Yes Yes
CQCC_ASSOC_BATCH_SERIES
Yes
CQCC_AUTO_ASSOCIATE
Yes
CQCC_AUTO_ASSOCIATE_ENABLE CQCC_COMMENT_PATTERN
No No
CQCC_CQWEB_ONLY CQCC_CQWEB_VERSION
No Yes
CQCC_DATABASE_ENTITY_LIST
No
CQCC_DATABASE_SET
Yes
CQCC_DEBUG
Yes
CQCC_GUI_ENABLE CQCC_LOG_OUTPUT
Yes Yes
202
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
Table 6. Configuration parameters summary (continued) Configuration parameter CQCC_MULTIPLE_ASSOCS CQCC_MULTISITE CQCC_POSTCHECKIN_COMMIT Description Allows or prevents multiple defects to be associated with change Enables Rational ClearCase MultiSite support Locally settable No No
Allows commitment of associations in No Rational ClearQuest user database to be delayed until checkin completes in Rational ClearCase VOB Allows developer-selected queries for making associations Controls which queries are presented to developers for associations For Rational ClearQuest Web client to specify user database replica name Specifies number of seconds that a restrictions check can be reused during batch processing Name of Rational ClearQuest Web server Name of folder in which Rational ClearQuest Web server is located Enables secure communications for the Rational ClearQuest Web connection. No No Yes Yes
Allows recording of internal timing data Yes CQCC_DATABASE_SET for Web server Yes
203
a colon (:) and the number of the port; for example, myhost:81 specifies that port number 81 be used instead of port 80. CQCC_SERVERROOT Specifies the root directory in which the Rational ClearQuest Web Interface files are installed; usually cqweb. CQCC_SERVER_SSL Specify TRUE to enable secure communications for the Rational ClearQuest Web connection. The URL is set to use https:. Specify FALSE (the default) to use http: as the protocol. If you enable secure communications, more time is used to establish a new connection when a trigger fires and a connection to a Rational ClearQuest user database is required relative to establishing an ordinary connection. Configuration parameter only CQCC_CQWEB_ONLY Set this to force use of the Rational ClearQuest Web Interface even if the Rational ClearQuest client is installed.
The database name is case sensitive. For each record type that you specify, describe the field names in the schema definition (see Establishing the schemas on page 205). Database sets (connections) allow developers to select from multiple schema repositories when they start a ClearQuest client or the base ClearCase integration with Rational ClearQuest. Only one database set is supported. In the integration, if your site uses multiple database sets, define CQCC_DATABASE_SET to specify the database set that is used for the integration and for the Rational ClearQuest native client interface. In CQCC_DATABASE_SET, supply the database connection name that you created in the Rational ClearQuest Maintenance tool. For example:
&SetConfigParm("CQCC_DATABASE_SET", "cqcc_db");
If you also use the Rational ClearQuest Web interface, supply this name in CQCC_WEB_DATABASE_SET. For example:
&SetConfigParm("CQCC_WEB_DATABASE_SET", "cqcc_db");
204
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
Overview of DefineCQSchema
In the configuration file, edit the DefineCQSchema() definition to provide the required and optional field names. Map your database field names to conventions that are used in SAMPL database. This mapping allows query definitions to be more generic, but also tells the integration what field names to use for its own operations, for example, internal queries that it has to do. Certain field names are required, for example, ID, OWNER, STATE, and HEADLINE. Tip: The ID field must be first in the results set. The field is used to select records for later operations. Add other field names for your convenience, but these other mappable names are not required by the integration. Field names can be used directly in queries that you define if at least the required fields are made known to the integration. The integration uses a CQSchema object to relate the field names that are defined to the field names that you use in your local record types. A CQSchema is loosely related to a Rational ClearQuest schema, but it really just describes record type fields and queries that are needed by the integration. It accomplishes the following tasks: v Defines a new CQSchema and provides a set of similar record types (entities) and properties (DefineCQSchema) v Relates the field names of the defect record type to those used by the record types that you specify (ChangeFieldMap) v Defines one or more queries (SetQuery) that are used by the trigger to provide the QUERY option that the developers see and specifies the final RESTRICTIONS check that is made before associations are made v Defines the query output format (SetResultSet)
DefineCQSchema
$s = DefineCQSchema(NAME=>name, ENTITY_LIST=>entityList, RESTRICTIONS=>queryName);
NAME Used only to provide a unique reference. Change the NAME for the new schema. ENTITY_LIST Provides one or more record types. For example, "defect,feature,patch". RESTRICTIONS Optional; refers to a query within the schema that defines conditions that new associations must meet. For example, the change request must be in a specific state. If you do not provide any restrictions, any existing change requests can be used. For example:
$s = &DefineCQSchema(NAME=>"MainSchema", ENTITY_LIST => "defect", RESTRICTIONS => "STANDARD");
Chapter 13. Setting up the base ClearCase integration with Rational ClearQuest
205
ChangeFieldMap
$s->ChangeFieldMap( name=>value, ...)
ChangeFieldMap() is a hash list that maps standard field names (for example, Owner) to a local name that you specify in value. The name is usually the name of a field in the SAMPL defect record type, but you can use any name that needs mapping in a query. The field map names are used in query or result set lists as variables. For example:
$s->ChangeFieldMap(OWNER => "Owner", STATE => "State", ID => "id", #Note: ID shouldnt need to change HEADLINE => "Headline", PRIORITY => "Priority", SEVERITY => "Severity", RATL_MASTERSHIP => "ratl_mastership", # Other mappable names QUERY_STATES => "Submitted,Assigned,Opened", MODIFY => "modify" );
The value for <OWNER> is translated to the local value that you provide in the OWNER=>"Owner" pair. Tip: If you use multiple record types, the field names in the mapping must be present in all record types.
SetQuery
$s->SetQuery(queryName, clause1, clause2, ...);
SetQuery() provides a named set of filter clauses for the query. It can directly use your local field names or rely on the field map to translate them when left angle brackets (<) and right angle brackets (>) are used. The value queryName is local to the current schema. STANDARD is used for the QUERY option, but you can define a second query to present an alternate restrictions query. The value clauseN is a string defining a condition in the format field operator value. For example:
$s->SetQuery("STANDARD", "<OWNER> eq <*USER*>", "<STATE> in <QUERY_STATES>");
Use only commas to separate multiple values. Tip: SetQuery() is effectively an AND group of clauses. OR or NOT connectives are not supported.
SetResultSet
$s->SetResultSet(queryName,ID,fieldList,formatString);
SetResultSet() identifies the fields that the query should return. The value fieldList is a comma-separated list of field names. The first field must be ID (generated by Rational ClearQuest) because the integration must be able to identify and work with the selected records. A customer-generated ID field does not meet this requirement. The value formatString is a standard printf format string. For example:
206
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
Tip: If you use both local and Rational ClearQuest queries (see Controlling query usage on page 210), the SetResultSet definitions must contain the exact fields in the exact order as your queries.
Sharing a CQSchema
A CQSchema can be shared by different record types if the record types share the small subset of field names that the integration uses. If you have record types that are too different to share one schema, you can define additional CQSchema objects. To define an additional CQSchema, copy the following commands: DefineCQSchema, ChangeFieldMap, SetQuery, and SetResultSet and modify them for additional definitions. Supply the mapping for each schema.
207
The error message indicates the context in which the string is being used and the string or strings involved; and uses question mark (?) characters to indicate inconvertible characters. Additional information is provided on each individual character that can not be converted. v If code page conversion is not enabled or is not yet supported on the client, the integration performs ASCII checking to filter non-ASCII data in strings. Strings that contain non-ASCII data are treated as code page conversion errors. Similar information is reported to identify the context and string contents. Performance overhead for ASCII checking is negligible. With ASCII checking enabled, the integration prevents transmission of incorrectly encoded data between client and server and minimizes potential data corruption and misrepresentation. v The integration can produce large error messages if there are either code page conversion or ASCII check errors. There is a maximum number of lines that are displayed in a conversion error message, after which additional data is truncated. The number of lines is set to 50 by default, but, if your environment requires, the limit can be adjusted to provide less or more information.
This line tells Perl that the file contains UTF-8 strings. 3. Use the Save As command and, in Encoding, select UTF-8 to save the config.pl file in UTF-8 format. This preserves the strings that you entered in the config.pl file as UTF-8 data.
This command connects to your Rational ClearQuest user database, makes some test associations from Rational ClearCase elements to a Rational ClearQuest record, and then removes the test associations. For information about errors, see Troubleshooting the configured connections on page 209.
208
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
If CQCC_MULTIPLE_ASSOCS is FALSE, then only one association is allowed for each version.
Chapter 13. Setting up the base ClearCase integration with Rational ClearQuest
209
CQCC_QUERY_ENABLE
If developers use the Rational ClearQuest client, use the CQCC_QUERY_ENABLE configuration parameter to determine which Rational ClearQuest queries are available to developers to search for associations. The following values control query usage: BOTH Both CQ and LOCAL. Queries defined both in the Rational ClearQuest user database and locally in the configuration file are available. CQ Only named queries defined in the Rational ClearQuest user database schema and visible in Personal Queries and Public Queries folders in the workspace are available. Restriction: To be used with the integration, a query must have the first column defined as the ID field that is generated by Rational ClearQuest. If the ID field is not first, the integration cannot identify and work with the users selections that are returned from the query. See SetResultSet on page 206. LOCAL Only queries defined locally in the configuration file are available. By default, only local queries are shown. OFF The Browse buttons and Queryname menu option are not displayed in the user interface.
For example:
&SetConfigParm("CQCC_QUERY_ENABLE", "BOTH");
Product tip: The full range of query capabilities is available only with the Rational ClearQuest Client through the Rational ClearQuest Perl API. The Rational ClearQuest Web interface displays only local queries due to limitations in the Rational ClearQuest Web API. To open up query capabilities for users of the Rational ClearQuest Client, modify the CQCC_QUERY_ENABLE configuration parameter setting.
CQCC_QUERY_FILTER
The CQCC_QUERY_FILTER configuration parameter refines availability of Rational ClearQuest queries. With the CQCC_QUERY_FILTER setting, you can control which queries from the Rational ClearQuest user database workspace are permissible. Provide a Perl regular expression that the query names must match. For example:
&SetConfigParm("CQCC_QUERY_FILTER", "Public Queries");
If the filter is set to Public Queries, only queries with that string in their path are shown in the list from which the developer selects.
210
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
For example:
&SetConfigParm("CQCC_GUI_ENABLE", "ON");
By default, only the preoperation trigger fires on checkin. With this option enabled (set to TRUE), the preoperation trigger is used to decide associations and a second postoperation trigger fires to make the actual database changes. Using this option can also require an extra Rational ClearQuest login on the postoperation trigger. The extra operations take more time because of the additional Rational ClearQuest login but keeps a more accurate database. Important: You can use the CQCC_ASSOC_BATCH_ENABLE environment variable to help minimize the cost of the extra operations. However, batch operations can be delayed under certain conditions. For information about those conditions, see Using the association batch feature.
Enhancing performance
The performance of the integration triggers can vary depending on how they access Rational ClearCase and Rational ClearQuest configurations. The CQCC_TIMER configuration parameter can record diagnostic timing information about the trigger session (see Producing timing information on page 216).
211
AUTOFLUSH Causes batches to be processed for each file in a defined series instead of waiting for the end of the series. FALSE Disables the association batch feature. Performs each transaction by establishing a new connection to the Rational ClearQuest user database, completing processing the single transaction, and closing the connection. TRUE Enables the association batch feature and reduces the amount of overhead processing. Performs one Rational ClearQuest login, establishes a new connection to the Rational ClearQuest user database, processes multiple transactions in a series, and closes the connection at the end of the series. Use the value TRUE to enable the reduction. For example:
&SetConfigParm("CQCC_ASSOC_BATCH_ENABLE", "TRUE");
This reduction is done by writing Rational ClearQuest transactions to a log file (.cqcc_assoc_batch) that is stored in the developer home directory (on Linux and the UNIX system) or in the application data directory (on the Windows system). When the batch completes, the transaction log file is read back and all the necessary Rational ClearQuest changes are made at the same time. The association batch feature improves performance in many cases. The log is automatically processed at the end of each single operation or at the end of a batch operation. A batch is defined either as a set of files used in one Rational ClearCase operation, for example, a multiple-checkout, or as defined by the user using the CQCC_ASSOC_BATCH_SERIES environment variable (see Defining a batch on page 213). If posting the log file fails, resolve the problem (for example, a login failure) and try again by either doing another Rational ClearCase operation or forcing the log to be processed (see Handling an incomplete posting). The log file can be rerun without causing duplications and is automatically renamed and moved aside when the posting process succeeds. If you use the CQCC_POSTCHECKIN_COMMIT configuration parameter (see Forcing checkin success before committing associations on page 211), then any failed checkins are not written to the log for processing. If you currently have the association batch feature enabled, you can gradually stop using batch processing by specifying AUTOFLUSH. For example:
&SetConfigParm("CQCC_ASSOC_BATCH_ENABLE", "AUTOFLUSH");
Batches are processed for each file in a defined series instead of waiting for the end of the series. Although each file is processed individually to completion, the pending transaction is saved locally to a log file until the transaction successfully completes. If the transaction fails, it is retried with the next Rational ClearQuest operation based on the locally stored information. The performance benefit of batch processing is lost, but reliability is maintained. If you instead disable batch processing suddenly (specify FALSE for CQCC_ASSOC_BATCH_ENABLE) after using it as a standard practice, you could leave unposted transactions in a locally stored batch log.
212
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
this last event is missed, for example, the last checkin failed because the file was identical, the log is not processed and the Rational ClearQuest operations are not posted. The data is not lost and is posted on the next successful Rational ClearCase operation that can begin processing the log. But the log may stay in the stored location for some time before the processing starts. You or the developer can force the log to be processed by using the following command from a command shell in the original VOB context:
cqcc_launch -vob -op batch
The batch operation processes any transactions that are in the log.
Defining a batch
If you use the CQCC_ASSOC_BATCH_ENABLE configuration parameter in the configuration file (see Using the association batch feature on page 211), the developer can also use the environment variable CQCC_ASSOC_BATCH_SERIES to define a batch. A batch is ordinarily the set of files to which a single Rational ClearCase operation is applied. The CQCC_ASSOC_BATCH_SERIES environment variable provides a way for a developer to broaden the meaning of a batch to be a series of Rational ClearCase operations. This is useful for checking in multiple files more efficiently than checking them in one at a time. If the CQCC_ASSOC_BATCH_SERIES environment variable is set to TRUE, the integration assumes that a batch is in effect and operations are logged. When the environment variable is set to FALSE, the next Rational ClearCase operation automatically causes the logged operations to be run. Use this option carefully because Rational ClearQuest changes are deferred if a series is in process. The developer can force the batch log to be flushed. For example, a script that checks in a series of files might look like this example (in the Windows system).
set CQCC_ASSOC_BATCH_SERIES=TRUE cleartool ci -nc file1 cleartool ci -nc file2 set CQCC_ASSOC_BATCH_SERIES=FALSE cqcc_launch -vob -op batch
Set the value to MULTIPLE to avoid seeing the window for every operation. For example:
&SetConfigParm("CQCC_ASSOC_BATCH_CONFIRM", "MULTIPLE");
213
associations), use the CQCC_RESTRICTIONS_TIMEOUT configuration parameter to limit extra processing during the batch. The timeout value controls the number of seconds that a restrictions check can be reused during CQCC_ASSOC_BATCH_SERIES log processing. The integration normally rechecks the new associations each time interval by logging into the Rational ClearQuest user database and performing a restrictions query. The integration caches the most recent restrictions query results and reuses them for a maximum time before it rechecks them again. After the time is exceeded, a new Rational ClearQuest login and restrictions query are performed to ensure that the selected associations are still valid. To delay this login operation and query during batch processing, set the CQCC_RESTRICTIONS_TIMEOUT configuration parameter in the configuration file or the environment variable to an increased number of seconds. To use a timeout of 10 minutes, set the value to 600. For example:
&SetConfigParm("CQCC_RESTRICTIONS_TIMEOUT, 600);
CQCC_RESTRICTIONS_TIMEOUT is set to 300 seconds (5 minutes) by default. The minimum value is 0 (disabled) and the maximum is 1200 (20 minutes).
214
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
The value SAMPL1,2,3 identifies change request IDs 1, 2, and 3 in the SAMPL user database. v To disable the option, the developer uses . v To select no change requests, the developer specifies -. The values that they specify remain in effect until they disable the option. For example:
setenv CQCC_AUTO_ASSOCIATE ""
On checkin operations, the integration uses the values that they specify with this option to override associations that they made on checkouts. If an error occurs, the integration displays the related messages and starts the user interface for associating change requests.
This example uses double backslash characters to escape each backslash character. The developers make associations by entering a checkin or checkout comment that matches the pattern, as in the following example of a checkout comment:
"This fixes BUGS:[SAMPL1,2,3]"
The pattern that is supplied in the checkout comment matches the pattern that is defined in the CQCC_COMMENT_PATTERN configuration parameter. This method avoids starting the integration user interface for associating files with change requests. The change requests that developers enter on checkin commands override the change requests that they specify on checkout commands. If the CQCC_AUTO_ASSOCIATE configuration parameter and the CQCC_COMMENT_PATTERN configuration parameter are enabled at the same time, the integration uses CQCC_AUTO_ASSOCIATE when it makes associations.
215
On the Windows system: set CQCC_DEBUG=value For value, use one of the following numbers: 0 1 2 No debugging information Basic debugging information Verbose debugging information that includes Rational ClearQuest traffic tracing
This provides large-grain timing information for basic internal operations such as Rational ClearQuest login, queries, and associations; and Rational ClearCase information gathering and hyperlink maintenance. Set the value to zero (0) to disable timing information. The integration writes the information to standard output and can store it in a file (see Controlling logged output).
OVERWRITE Overwrites the log file for each trigger session. For example:
&SetConfigParm("CQCC_LOG_OUTPUT", "OVERWRITE");
The log file name is cqcc_output.log. On Linux and the UNIX system, the file is written to the users home directory. On the Windows system, the file is written to the profile directory.
Tip: The preceding commands use the default path for the configuration file. If you specified a path to a central location when you configured the
216
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
integration, use that path when invoking the cqcc_launch command (see Using a shared configuration file and triggers on page 198). The command displays output indicating whether it is able to connect to the target Rational ClearQuest user database. For more detailed output messages, set the CQCC_DEBUG environment variable to 2 (see Generating operational information on page 215).
Chapter 13. Setting up the base ClearCase integration with Rational ClearQuest
217
218
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
219
element: opt.c main Base contributor 4 r1_fix 5 0 6 1 7 Target contributor Merge output file 2 8 3
5 Contributor
Merging files and directories involves the following actions: 1. The base contributor is identified. 2. Each contributor is compared against the base contributor. (See Figure 54.) 3. Any line that is unchanged between the base contributor and any other contributor is copied to the merge output file. 4. Any line that has changed between the base contributor and one other contributor is accepted in the contributor. Depending on how you started the merge operation, the change may be copied to the merge output file. However, you can disable the automated merge capability for any given merge operation. If you disable this capability, you must approve each change to the merge output file. 5. For any line that has changed between the base contributor and more than one other contributor, you are required to resolve the conflicting difference.
B
(b, c1) (b, c2)
Base Contributor
C1
Destination version = B +
C2
(b, c1) + (b, c2)
Source Contributors
220
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
To merge versions, you can use the graphic user interface (GUI) tools (see Using the GUI to merge elements on page 221) or the command-line interface (see Using the command line to merge elements on page 222).
221
The merge can be recorded with a merge arrow, which is implemented as a hyperlink of type Merge.
Each scenario shows the version tree of an element that requires a merge and indicates the appropriate command to perform the merge.
222
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
4 r1_fix 5 0 6 1 7 2 8 3
4 merge 5
QA_APPROVED
6
Figure 55. Selective merge from a subbranch
In a view configured with the default config spec, enter the following commands to perform the selective merge:
cleartool checkout opt.c cleartool merge to opt.c insert version /main/r1_fix/4
You can also specify a range of consecutive versions to be merged. For example, this command merges only the changes in versions /main/r1_fix/2 through /main/r1_fix/4:
cleartool merge to opt.c insert version /main/r1_fix/2 /main/r1_fix/4
223
The merge graphical syntax causes the merge to take place automatically whenever possible, and to start the graphical merge utility if an element merge
224
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
requires user interaction. If the project has made changes in several VOBs, you can perform all the merges at once by specifying several paths, or by using the avobs option to findmerge.
Tip: Working in a single shared view is not recommended because doing so can degrade system performance.
The version trees in Figure 57 show the following various likely cases: v An element that your team started changing at Release 1 (enhance branch created at the version labeled VEND_R1) v An element that your team started changing at Release 3 v An element that your team has never changed
225
main 0
main 0
VEND_R1 VEND_R2
1 enhance 0
VEND_R1 VEND_R2
VEND_R3
3 1 2
VEND_R3
3 enhance 0
previous merges
1 2
4 3
5
Figure 57. Merging a new release of an entire source tree
When Release 4 arrives, and you need to integrate this release with your teams changes. To prepare for the merge, add the new release to the main branch and label the versions VEND_R4. Merging the source trees involves merging from the version labeled VEND_R4 to the most recent version on the enhance branch; if an element has no enhance branch, nothing is merged. This procedure accomplishes the following integration: 1. Load the vendors Release 4 media into a standard directory tree:
cd /usr/tmp tar xv
The directory tree created is mathlib_4.0. 2. As the VOB owner, run clearfsimport in a view configured with the default config spec to create Release 4 versions on the main branches of elements (and create new elements as needed).
clearfsimport recurse /usr/tmp/mathlib_4.0 /vobs/proj/mathlib
4. Set to a view that is configured with your teams config spec and selects the versions on the enhance branch:
cleartool setview enh_vu
226
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
The merge graphical syntax instructs findmerge to merge automatically if possible, but if not, start the graphical merge tool. 6. Verify the merges, and check in the modified elements. You have now established Release 4 as the new baseline. Developers on your team can update their view configurations.
element * CHECKEDOUT element * .../enhance/LATEST element * VEND_R4 mkbranch enhance element * /main/LATEST mkbranch enhance
Elements that have been active continue to evolve on their enhance branches. When elements are revised for the first time, their enhance branches are created at the VEND_R4 version.
If you have changes to merge from both files and directories, it may be a good idea to run findmerge twice: first to merge directories, and again to merge files. Using the print option to a findmerge command does not report everything that is merged, because findmerge does not see new files or subdirectories in the merge-from version of a directory until after the directories are merged. To report
Chapter 14. Integrating changes
227
every merge that takes place, use findmerge to merge the directories only, and then use findmerge print to get information about the file merges that are needed. Afterward, you can cancel the directory merges by using the uncheckout command on the directories.
This form of the merge command does not change any file system data; it merely attaches a merge arrow (a hyperlink of type Merge) to the specified versions. After you make this annotation, your merge is indistinguishable from one performed with Rational ClearCase tools.
228
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
229
230
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
v This list is compared with the set of element types defined for the VOB that stores the element. The element is created by using the first element type in the list that matches an element type in the VOB. For example, a new element named monet_adm.1 is assigned an element type as follows: 1. A developer creates an element:
cleartool mkelem monet_adm.1
2. Because the developer did not specify an element type (eltype option), mkelem uses one or more magic files to determine the file types of the specified name. Tip: A search path facility uses the environment variable MAGIC_PATH. See the cc.magic reference page for details. If the magic file shown in Sample magic file on the UNIX system on page 230 is the first (or only) one to be used, rule (4) on page 230 is the first to match the name monet_adm.1, yielding this list of file types:
manpage src_file text_file file
3. This list is compared with the set of element types defined in the VOB for the new element. If text_file is the first file type that names an existing element type, monet_adm.1 is created as an element of type text_file. 4. Data storage and retrieval for versions of element monet_adm.1 are handled by the type manager associated with the text_file element type; its name is text_file_delta:
% cleartool describe eltype:text_file element type "text_file" ... type manager: text_file_delta supertype: file meta-type of element: file element
File-typing mechanisms are defined on a per-user or per-site basis; element types are defined on a per-VOB basis. (To ensure that element types are consistent across VOBs, the Rational ClearCase administrator can use global types.) In this case, a new element, monet_adm.1, is created as a text_file element; in a VOB with a different set of element types, the same magic file may have created it as a src_file element.
231
232
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
v Create your own program for the methods that you want to customize. See Writing a type manager program (the UNIX system). v On each Rational ClearCase or Rational ClearCase LT client host in the network, either make a copy of the new type manager directory or create symbolic link to it. The standard storage, performance, and reliability trade-offs apply. v If your organization uses Rational ClearCase MultiSite, at every site, either make a copy of the new type manager directory, or create a symbolic link to it. Tip: An element type belongs to a VOB, and thus is available on every host that mounts its VOB. But a type manager is host-specific; it is the ccasehomedir/lib/mgrs/manager-name directory on some host. See the type_manager reference page and the file ccasehomedir/lib/mgrs/mgr_info.h for additional information on type managers.
233
The basic strategy is to use most of the z_whole_copy type manager methods. The compare method uses nroff(1) to format the versions before displaying their differences.
Any methods that the new type manager does not support can be omitted from this list. The lack of a symbolic link causes an Unknown Manager Request error. The sections The create_version method and The construct_version method on page 235 describe two of these inherited methods, which can serve as models for user-defined methods. Both methods are implemented as scripts in the same file, ccasehomedir/lib/mgrs/z_whole_copy/Zmgr.
The only arguments that require special attention are new_container_pname (fifth argument), which specifies the path of the new data container, and data_pname (tenth argument), which specifies the path of the checked-out file.
234
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
The file ccasehomedir/lib/mgrs/mgr_info.sh lists the appropriate exit statuses and provides a symbolic name for the create_version method:
# Any unexpected value is treated as failure MGR_FAILED=1 # Return Values for store operations MGR_STORE_KEEP_NEITHER=101 MGR_STORE_KEEP_JUST_OLD=102 MGR_STORE_KEEP_JUST_NEW=103 MGR_STORE_KEEP_BOTH=104 . . MGR_OP_CREATE_VERSION="create_version"
The following example is the code that implements the create_version method: (1) shift 1 (2) if [ -s $4 ] ; then (3) echo $0: error: new file is not of length 0! (4) exit $MGR_FAILED (5) fi (6) if $gzip < $9 > $4 ; ret=$? ; then : ; fi (7) if [ "$ret" = "2" -o "$ret" = "0" ] ; then (8) exit $MGR_STORE_KEEP_BOTH (9) else (10) exit $MGR_FAILED (11) fi The Bourne shell allows only nine command-line arguments. The shift 1 in Line 1 discards the first argument (create_time), which is unneeded. Thus, the path of the checked-out version (data_pname), originally the tenth argument, becomes $9. In Line 6, the contents of data_pname are compressed, then appended to the new, empty data container: new_container_pname, originally the fifth argument, but shifted to become $4. (Lines 2 through 5 verify that the new data container is, indeed, empty.) Finally, the exit status of the gzip command is checked, and the appropriate value is returned (Lines 7 through 11). The exit status of the create_version method indicates that both the old data container (which contains the predecessor version) and the new data container (which contains the new version) are to be kept.
235
1. Uncompresses the contents of the data container 2. Returns to the calling process an exit status that indicates what to do with the new data container The file ccasehomedir/lib/mgrs/mgr_info.h lists the arguments passed to the method.
/********************************************************************** ****** * construct_version * Fetch the data for a version. * Extract the data for the requested version into the supplied path, or * return a value indicating that the source container can be used as the * cleartext data for the version. * * Command line: * construct_version source_container_pname data_pname version_oid
The file ccasehomedir/lib/mgrs/mgr_info.sh lists the appropriate exit statuses and provides a symbolic name for the construct_version method:
# Any unexpected value is treated as failure MGR_FAILED=1 # Return Values for construct operations MGR_CONSTRUCT_USE_SRC_CONTAINER=101 MGR_CONSTRUCT_USE_NEW_FILE=102 . . MGR_OP_CONSTRUCT_VERSION="construct_version"
This example code in The construct_version method source code implements the construct_version method. The construct_version method source code: (1) if $gzip -d < $1 > $2 ; then (2) exit $MGR_CONSTRUCT_USE_NEW_FILE (3) else (4) exit $MGR_FAILED (5) fi In Line 1, the contents of source_container_pname are uncompressed and stored in the cleartext container, data_pname. The remaining lines return the appropriate value to the calling process, depending on the success or failure of the gzip command.
236
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
* Command line: * compare [-tiny | -window] [-serial | -diff | -parallel] [-columns n] * [pass-through-options] pname pname ... ******/
This listing shows that a user-supplied implementation of the compare method must accept all the command-line options that the Rational ClearCase diff command supports. The strategy here is to pass the options to cleardiff and not attempt to interpret them. After all options are processed, the remaining arguments specify the files to be compared. The file ccasehomedir/lib/mgrs/mgr_info.sh lists the appropriate exit statuses and provides a symbolic name for the compare method.
# Return Values for COMPARE/MERGE Operations MGR_COMPARE_NODIFFS=0 MGR_COMPARE_DIFF_OR_ERROR=1 . . MGR_OP_COMPARE="compare"
The Bourne shell script listed in Script for compare method implements the compare method. (You can modify this script to implement the xcompare method as a slight variant of compare.)
237
Creating and Using a Test Element: These commands create a test element that uses the new type manager, and tests the various data-manipulation methods: cd directory-in-test-VOB cleartool checkout nc . (tests create_element method) cleartool mkelem eltype manpage_test nc nco test.1 (tests construct_version method) cleartool checkout nc test.1 vi test.1 (edit checked-out version) cleartool checkin c first test.1 (tests create_ version method) cleartool checkout nc test.1 (tests construct_ version method) vi test.1 (edit checked-out version) cleartool checkin c second test.1 (tests create_ version method) cleartool diff test.1@@/main/1 test.1@@/main/2 (tests compare method)
238
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
If the VOB is replicated, you must install the type manager at all sites. Custom type managers are not replicated. To install the type manager on a particular host, create a subdirectory in ccasehomedir/lib/mgrs, and populate it with the programs that implement the methods. You can create symbolic links across the network to a master copy on a server host. 2. Create element types. Create one or more element types that use the type manager, just as you did in Testing the type manager on page 238 (do not include test in the name of the element type). For example, you can name the element type manpage or nroff_src. 3. Convert existing elements. Have at least a few existing elements use the new type manager. The chtype command changes an element type:
% cleartool chtype force manpage path ...
Permission to change an element type is restricted to the element owner, the VOB owner, and the root user. 4. Revise magic files. If you want the new element types to be used automatically for certain newly created elements, create (or update) a local.magic file in each host ccasehomedir/config/magic directory:
manpage src_file text_file file: -name "*.[1-9]" ;
5. Inform the project team (and other teams, if appropriate). Advertise the new element types to all team members, describing the features and benefits of the new type manager. Be sure to provide directions on how to gain access to the new functionality automatically (through file names that match magic-file rules) and explicitly (with mkelem eltype).
When a match is found, the search ends. The token that follows icon names the file that contains the icon to be displayed. 3. The File Browser searches for the file, which must be in bitmap(1) format, in directory $HOME/.bitmaps, or ccasehomedir/config/ui/bitmaps, or the directories specified by the environment variable BITMAP_PATH. 4. If a valid bitmap file is found, the File Browser displays it; otherwise, the search for an icon continues with the next file type. The name of an icon file must include a numeric extension, which need not be specified in the icon file rule. The extension specifies how much screen space the File Browser must allocate for the icon. Each bitmap supplied with Rational ClearCase version control is stored in a file with a .40 suffix (for example, lib.40), which indicates a 40x40 icon.
Chapter 15. Using element types to customize file element processing
239
This procedure causes the File Browser to display manual page source files with a customized icon. All manual pages have file type manpage. 1. Add a rule to your personal magic file (in directory $HOME/.magic) that includes manpage among the file types assigned to all manual page source files:
manpage src_file text_file file: -name "*.[1-9]" ;
2. Add a rule to your personal icon file (in directory $HOME/.icon) that maps manpage to a user-defined bitmap file:
manpage : -icon manual_page_icon ;
3. Create a manpage icon in your personal bitmaps directory ($HOME/.bitmaps) by revising one of the standard icon bitmaps with the standard X bitmap utility:
% % % % mkdir $HOME/.bitmaps cd $HOME/.bitmaps cp $RATIONALHOME/config/ui/bitmaps/c.40 manual_page_icon.40 bitmap manual_page_icon.40
4. Test your work by having the File Browser display a manual page source file.
240
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
Project overview
Release 2.0 development of the monet project includes the following kinds of work: v Patches. Several high-priority bug fixes to Release 1.0 are needed. v Minor enhancements. Some commands need new options; some option names need to be shortened (for example, recursive becomes r); some algorithms need performance work. v Major new features. A graphic user interface is required, as are many new commands and internationalization support. These three development efforts can proceed largely in parallel (see Figure 58), but critical dependencies and milestones must be considered: v Several Release 1.0 patch releases will ship before Release 2.0 is complete. v New features take longer to complete than minor enhancements. v Some new features depend on the minor enhancements.
241
MAJ Team
1.0
MIN Team
2.0
The plan uses a baseline-plus-changes approach. Periodically, developers stop writing new code, and spend some time integrating their work, building, and testing. The result is a baseline: a stable, working version of the application. You can integrate product enhancements incrementally and frequently. The more frequent the baselines, the easier the tasks of merging work and testing the results. After a baseline is produced, active development resumes; any new efforts begin with the set of source versions that went into the baseline build. You define a baseline by assigning the same version label (for example, R2_BL1 for Release 2.0, Baseline 1) to all the versions that go into, or are produced by, the baseline build. The project team is divided into three smaller teams, each working on a different development effort: the MAJ team (new features), the MIN team (minor enhancements), and the FIX team (Release 1.0 bug fixes and patches). Some developers may belong to multiple teams. These developers work in multiple views, each configured for the respective team tasks. Product Note: In the examples that follow, arguments that show multicomponent VOB tags, such as /vobs/monet, do not apply to Rational ClearCase LT on the UNIX system, which recognizes only single-component VOB tags, such as /vobs_monet. The development area for the monet project is shown here.
/vobs/monet src/ include/ lib/ (project top-level directory) (sources) (include files) (shared libraries)
At the beginning of Release 2.0 development, the most recent versions on the main branch are labeled R1.0.
242
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
Development strategy
This section describes the Rational ClearCase issues to be resolved before development begins.
Use of branches
In general, different kinds of work are done on different branches. The Release 1.0 bug fixes, for example, are made on a separate branch to isolate this work from new development. The FIX team can then create patch releases that do not include any of the Release 2.0 enhancements or incompatibilities. Because the MIN team will produce the first baseline release on its own, the project manager gives the main branch to this team. The MAJ team will develop new features on a subbranch, and will not be ready to integrate for a while; the FIX team will fix Release 1.0 bugs on another subbranch and can integrate its changes at any time. Each new feature can be developed on its own subbranch, to better manage integration and testing work. For simplicity, this chapter assumes that work for new features is done on a single branch. The project manager has created the first baseline from versions on the main branches of their elements. But this is not a requirement; you can create a release that uses versions on any branch, or combination of branches. The evolution of a typical element during Release 2.0 development is shown in Figure 59.
243
main R1.0 0 r1_fix 0 2 1 3 (R1.0.1) R2_BL1 4 merge 3 5 4 6 5 7 (R1.0.2) 8 merge 4 merge 6 3 2 2 1 major 0
R2_BL2
R2.0
10 merge
The evolution of the element proceeds in the following steps: 1. Start minor and major enhancements, along with R1.0 bug fixing (all branches). 2. Freeze minor enhancements work (main branch). 3. Merge bug fixes from Release 1.0.1 into minor enhancements (main). 4. Create Baseline 1 release (main). 5. Freeze major enhancements work (major). 6. Merge Baseline 1 changes into major enhancements (major). 7. Freeze minor enhancements work (main). 8. 9. 10. 11. Merge additional bugfixes into minor enhancements (main). Freeze major enhancements work (major). Merge major enhancements work with minor enhancements work (main). Create Baseline 2 release (main).
244
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
Tip: Because each VOB has its own set of branch types, the branch types must be created separately in the monet VOB and the libpub VOB.
245
% mkdir $HOME/view_store % cleartool mkview tag arb_major $HOME/view_store/arb_major.vws Created view. Host-local path: phobos:export/home/arb/view_store/arb_major.vws Global path: /net/phobos/export/home/arb/view_store/arb_major.vws It has the following rights: User : arb : rwx Group: user : rwx Other: : r-x
A new view has the default config spec. Thus, developers on the MAJ and FIX teams must reconfigure their views, using the standard file for their team. Developer arb edits her config spec with the cleartool edcs command, deletes the existing lines, and adds the following line:
/public/config_specs/MAJ
If the project manager changes the standard file, arb must enter the command cleartool setcs current to pick up the changes.
Development begins
To begin the project, a developer sets a properly configured view, checks out one or more elements, and starts work. For example, developer david on the MAJ team enters these commands:
% cleartool setview david_major % cd /vobs/monet/src % cleartool checkout nc opt.c prs.c Created branch "major" from "opt.c" version "/main/6". Checked out "opt.c" from version "/main/major/0". Created branch "major" from "prs.c" version "/main/7". Checked out "prs.c" from version "/main/major/0".
The auto-make-branch facility causes each element to be checked out on the major branch (see Rule 4 on page 245 in the MAJ teams config spec in Creating project views on page 245). If a developer on the MIN team enters this command, the elements are checked out on the main branch, with no conflict. Rational ClearCase is fully compatible with standard development tools and practices. Thus, developers use the editing, compilation, and debugging tools that they prefer (including personal scripts and aliases) while working in their views. Developers check in work periodically to make their work available to other team members (that is, those whose views select the most recent version on the teams branch). This allows intra-team integration and testing to proceed throughout the development period.
246
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
v Viewing only their own revisions. Developers can use a Rational ClearCase query to configure a view that selects only their own revisions to the source tree.
Creating baseline 1
The MIN team has implemented and tested the first group of minor enhancements, and the FIX team has produced a patch release, whose versions are labeled R1.0.1. It is time to combine these efforts, to produce Baseline 1 of Release 2.0 (Figure 60).
Release 1.0
MIN Team
Freeze
Baseline 1
FIX Team
Release 1.0.1
The output from the findmerge command describes the versions that are merged.
Because all integration work takes place on the main branch, there is no need to change the configuration of the new view from the Rational ClearCase default. MIN developers set this view (cleartool setview base1_vu) and coordinate builds
Chapter 16. Using Rational ClearCase throughout the development cycle
247
and tests of the monet application. Because they are sharing a single view, the developers are careful not to overwrite each others view-private files. Any new versions that are created to fix inconsistencies (and other bugs) go onto the main branch.
Labeling sources
The monet application minor enhancements and bug fixes are now integrated, and a clean build has been performed in view base1_vu. To create the baseline, the project manager assigns the same version label, R2_BL1, to the /main/LATEST versions of all source elements. He begins by creating an appropriate label type:
% cleartool mklbtype c "Release, Baseline 1" R2_BL1@/vobs/monet R2_BL1@/vobs/libpub Created label type "R2_BL1". Created label type "R2_BL1".
He then locks the label type, preventing all developers (except himself) from using it:
% cleartool lock nusers meister lbtype:R2_BL1@/vobs/monet lbtype:R2_BL1@/vobs/libpub Locked label type "R2_BL1". Locked label type "R2_BL1".
Before applying labels, he verifies that all elements are checked in on the main branch (checkouts on other branches are still allowed):
% cleartool lscheckout all /vobs/monet /vobs/libpub
No output from this command indicates that all elements for the monet project are checked in. Now, the project manager attaches the R2_BL1 label to the currently selected version (/main/LATEST) of every element in the two VOBs:
% cleartool mklabel recurse R2_BL1 /vobs/monet /vobs/libpub Created label "R2_BL1" on "/vobs/monet" version "/main/1". Created label "R2_BL1" on "/vobs/monet/src" version "/main/3". <many more label messages>
248
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
MAJ Team
Freeze
Release 1.0
MIN Team
Freeze
Baseline 1
Accordingly, the project manager declares a freeze of major enhancements development. MAJ team members check in all elements and verify that the monet application builds and runs, making small source changes as necessary. When all such changes have been checked in, the team has a consistent set of /main/major/LATEST versions. Tip: Developers working on other major enhancements branches can merge at other times, using the same merge procedures described here.
Preparing to merge
1. The project manager makes sure that no element is checked out on the major branch:
% cleartool lscheckout all /vobs/monet /vobs/libpub
Tip: Any MAJ team members who want to continue with nonmerge work can create a subbranch at the frozen version (or work with a version that is checked out as unreserved). 2. The project manager performs any required directory merges:
% cleartool setview major_vu
The output log describes the findmerge actions. 3. After checking in the files, the project manager determines which elements need to be merged:
% cleartool findmerge /vobs/monet /vobs/libpub fversion /main/LATEST print . . . A findmerge log has been written to "findmerge.log.04-Feb-04.10:01:23"
249
The output log describes the findmerge actions. This last findmerge log file is in the form of a shell script: it contains a series of cleartool findmerge commands, each of which performs the required merge for one element:
% cat findmerge.log.04-Feb-04.10:01:23 cleartool findmerge /vobs/monet/src/opt.c@@/main/major/1 -fver /main/LATEST merge cleartool findmerge /vobs/monet/src/prs.c@@/main/major/3 -fver /main/LATEST merge . . cleartool findmerge /vobs/libpub/src/dcanon.c@@/main/major/3 -fver /main/LATEST -merge cleartool findmerge /vobs/libpub/src/getcwd.c@@/main/major/2 -fver /main/LATEST -merge cleartool findmerge /vobs/libpub/src/lineseq.c@@/main/major/10 -fver /main/LATEST -merge
4. The project manager locks the major branch, allowing it to be used only by the developers who are performing the merges:
cleartool lock nusers meister,arb,david,sakai brtype:major@/vobs/monet \ brtype:major@/vobs/libpub Locked branch type "major". Locked branch type "major".
Merging work
Because the MAJ team is not contributing to a baseline soon, it is not necessary to merge work (and test the results) in a shared view. MAJ developers can continue working in their own views. Periodically, the project manager sends an excerpt from the findmerge log to an individual developer, who executes the commands and monitors the results. (The developer can send the resulting log files back to the project manager, as confirmation of the merge activity.) A merged version of an element includes changes from three development efforts: Release 1.0 bug fixing, minor enhancements, and new features (see Figure 62).
250
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
main R1.0 0 r1_fix 0 2 1 3 (R1.0.1) R2_BL1 4 merge 3 5 4 Development freeze 2 2 Development when BL1 is complete 1 major 0
merge
Figure 62. Merging Baseline 1 changes into the major branch
The project manager verifies that no more merges are needed, by entering a findmerge command with the whynot option:
% cleartool findmerge /vobs/monet /vobs/libpub fversion /main/LATEST whynot print . . No merge "/vobs/monet/src" [/main/major/4 already merged from /main/3] No merge "/vobs/monet/src/opt.c" [/main/major/2 already merged from /main/12] . .
The merge period ends when the project manager removes the lock on the major branch:
% cleartool unlock brtype:major@/vobs/monet brtype:major@/vobs/libpub Unlocked branch type "major". Unlocked branch type "major".
Creating Baseline 2
The MIN team is ready to freeze for Baseline 2, and the MAJ team will be soon (see Figure 63).
251
Freeze
Freeze
Baseline 2
Release 1.0.2
Baseline 2 integrates all three development efforts, and thus requires two sets of merges: v Bug fix changes from the most recent patch release (versions labeled R1.0.2) must be merged to the main branch. v New features must be merged from the major branch to the main branch. (This is the opposite direction from the merges described in Merging ongoing development work on page 248.) Merges can be done from more than two directions, so both the bug fixes and the new features can be merged to the main branch at the same time. In general, though, it is easier to verify the results of two-way merges.
252
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
The project manager verifies that everything is checked in on both the main branch and major branches:
% cleartool lscheckout brtype main recurse /vobs/monet /vobs/libpub % cleartool lscheckout brtype major recurse /vobs/monet /vobs/libpub %
No output from these commands indicates that no element is checked out on either its main branch or its major branch. Next, the project manager determines which elements require merges:
% cleartool setview minor_vu
All development on the major branch will stop after this baseline. Thus, the project manager locks the major branch to all users, except those who are performing the merges. Locking allows the merges to be recorded with a hyperlink of type Merge:
% cleartool lock nusers arb,david brtype:major@/vobs/monet brtype:major@/vobs/libpub Locked branch type "major". Locked branch type "major".
Because the main branch will be used for Baseline 2 integration by a small group of developers, the project manager asked vobadm to lock the main branch to everyone else:
% cleartool lock nusers meister,arb,david,sakai \ brtype:main@/vobs/monet brtype:main@/vobs/libpub Locked branch type "main". Locked branch type "main".
To lock the branch, you must be the branch creator, element owner, VOB owner, or root user (on the UNIX system) or a member of the ClearCase administrators group (on the Windows system). See the lock reference page.
After checkin, the version tree of a typical merged element appears as in Figure 64.
253
main 0 major 0
R2_BL1
1 merge 2
4 merge
Figure 64. Element structure after the pre-Baseline-2 merge
254
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
Baseline 2
Minor bugfixes
Release 2.0
Before the monet application is shipped to customers, it goes through a validation phase: v All editing, building, and testing is restricted to a single, shared view. v All builds are performed from sources with a particular version label (R2.0). v Only the project manager has permission to make changes involving that label. v All labels must be moved by hand. v Only high-priority bugs are fixed, using this procedure: The project manager authorizes a particular developer to fix the bug, by granting her permission to create new versions (on the main branch). The developers checkin activity is tracked by a Rational ClearCase trigger. After the bug is fixed, the project manager moves the R2.0 version label to the fixed version and revokes the developers permission to create new versions.
Labeling sources
In a view with the default config spec, the project manager creates the R2.0 label type and locks it:
cleartool mklbtype c "Release 2.0" R2.0@/vobs/monet R2.0@/vobs/libpub Created label type "R2.0". Created label type "R2.0". cleartool lock nusers meister lbtype:R2.0@/vobs/monet lbtype:R2.0@/vobs/libpub Locked label type "R2.0". Locked label type "R2.0".
The project manager labels the /main/LATEST versions throughout the entire monet and libpub development trees:
cleartool mklabel recurse R2.0 /vobs/monet /vobs/libpub
Many label messages are displayed. During the final test phase, the project manager moves the label forward, using mklabel replace, if any new versions are created.
The main branch is opened only for last-minute bug fixes (see Fixing a final bug on page 256.)
255
% umask 2 % cleartool mkview tag r2_vu /public/integrate_r2.vws % cleartool edcs tag r2_vu
This config spec guarantees that only properly labeled versions are included in final validation builds.
Only the VOB owner or root user (on the UNIX system) or a member of the Rational ClearCase administrators group (on the Windows system) can create trigger types.
Developer arb fixes the bug in a view with the default config spec and tests the fix there. This involves creating two new versions of element prs.c and one new version of element opt.c. Each time arb uses the checkin command, the r2_checkin trigger sends mail to the project manager. For example:
Subject: Checkin /vobs/monet/src/opt.c by arb /vobs/monet/src/opt.c@@/main/9 Checked in by arb. Comments: fixed bug #459: made buffer larger
When regression tests verify that the bug has been fixed, the project manager revokes arbs permission to create new versions. Once again, the command is executed by vobadm:
% cleartool lock replace nusers meister brtype:main Locked branch type "main".
The project manager then moves the version labels to the new versions of prs.c and opt.c, as indicated in the mail messages. For example:
% cleartool mklabel replace R2.0 /vobs/monet/src/opt.c@@/main/9 Moved label "R2.0" on "prs.c" from version "/main/8" to "/main/9".
256
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
Wrapping up
When the final build in the r2_vu view passes the final test, Release 2.0 of monet is ready to ship. After the distribution medium has been created from derived objects in the r2_vu view, the project manager asks the Rational ClearCase administrator to clean up and prepare for the next release: v The Rational ClearCase administrator deletes the all-element trigger type to remove the checkin triggers from all elements:
cleartool rmtype trtype:r2_checkin@/vobs/monet trtype:r2_checkin@/vobs/libpub Removed trigger type "r2_checkin". Removed trigger type "r2_checkin".
257
258
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
Part 4. Appendixes
259
260
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
Feature comparison
The features of view profiles and UCM are similar in a few ways and different in many other ways.
261
262
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
263
Presentation
The form for a record type that uses both integrations includes two tabs to show the change set information associated with each integration. The Unified Change Management tab lists the change set for a UCM activity. The ClearCase tab shows the change set associated with a Rational ClearQuest record.
264
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
265
v The report parameters As with the Report Builder, you can customize the Report Viewer. Add, change, or remove information for the changeable areas as follows: v The position of a column heading can be moved, a column heading name can be added, modified, or deleted and a default sort order can be added or removed from any column heading. v The commands on the pop-up menu. For programming examples that demonstrate how you can make these customizations, see Report programming examples on page 276.
266
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
USER ACTIONS Phase 1 Report Builder Reports Folder 1 Folder 2 Description 1 Description 2 Parameter 1 Parameter 2
Phase 2 Report Builder Reports Folder 1 Folder 2 Report 1 Report 2 Parameter 1 Parameter 2 Report Builder application
Phase 3 Report Viewer Column 1 Column 2 Row 1 Row 2 Report Viewer application Procedure for Report 1
To execute these processing phases correctly, a report procedure must meet the following requirements: v The directory that contains the report procedure must be found at known location. The Report Builder reads the \reports\scripts directory to determine the report procedure file names. When a user clicks the associated directory folder, Report Builder calls the associated report procedure. v The report procedure must have a valid interface specification. If the expected format is not present, the report does not run. v The interface specification in the report procedure must use parameters and choosers supplied by Rational ClearCase Reports. See Table 9 on page 271. v The report procedure must support a command line interface that the Report Viewer can use to pass user-defined parameter values to the report procedure.
267
3. Create a dynamic or snapshot view for the reports data that is now under source control.
268
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
Attributes\ Branches\ Labels\ Triggers\ UCM_Projects\ UCM_Streams\ Views\ VOBs\ scripts_rightclick\ script_tools\
All other files are ignored. The file name extension of report procedures supplied with Rational ClearCase Reports is .prl, which the Report Builder associates with ccperl.exe. At run time, the Report Builder displays all folder names, substituting a space for the underscore and dropping the file name extension. There is one exception: the root directory is always named Reports. This convention cannot be changed. For example, you have the following on-disk directory tree:
scripts\ Admin_Reports view_aging.prl all_views.prl UCM_Reports\ lagging_streams.prl completed_acts.prl
The Report Builder displays text in the tree pane as the following folders:
\Reports Admin Reports\ UCM Reports\
269
If a serious parsing error occurs in processing the interface specification, the report does not appear in the reports pane. The helpfile specification is reserved for future use and is not supported in this release. For information on troubleshooting parsing errors, see Troubleshooting customization on page 292. The examples in Interface specification for All_Views.prl through Parameter choosers on page 274 show how the interface specification is defined in specific report procedures.
The report interface attaches the Report Viewer to the View Tag and View Owner fields; the right-click event in the Report Viewer window calls Properties _of_View.prl, which is based on a data stream from the View Tag field.
Description specification
The description is the only required part of an interface specification. When only description is defined, a report procedure can run other graphical user interfaces (for example, clearprompt) or otherwise interact with the user. The reports in the \ClearCase_Tools folder define description only. Descriptions can contain anything other than the delimiter, a double quote ("). There is no maximum length for this definition, but long strings do not wrap in the reports pane.
270
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
Help files
Help files are supplied for the Report Builder user interface. The help files for Rational ClearCase Reports are in ccasehomedir\bin\cc_reports.hlp. You cannot add an ID for your own report.
Parameters specification
When specifying parameters, you can use only those supplied with Rational ClearCase Reports. Each parameter has an associated chooser control, parameter text, and a help ID (see Table 9).
Table 9. Parameters supplied with Rational ClearCase Reports Parameter PROJECTS STREAMS ACTIVITIES PROJECT STREAM ACTIVITY ISTREAM PVOB COMPONENT Default text displayed in the parameter pane Select projects in UCM Process VOB Select streams in UCM Process VOB Select activities in UCM Process VOB Select project in UCM Process VOB Select stream in UCM Process VOB Select activity in UCM Process VOB Select Integration Stream in UCM Process VOB Select one Process VOB Tag Type a single UCM component object selector (no verification performed) Help ID Chooser 1 2 3 4 5 6 7 8 9 Path (UCM) Path (UCM) Path (UCM) Path (UCM) Path (UCM) Path (UCM) Path (UCM) Path (file selection) Text Selection Multiple Multiple Multiple Single Single Single Single Single Single
BASELEVEL
Type a single UCM baseline object 10 selector (no verification performed) Select Integration Streams in UCM 11 Process VOB Select Process VOBs Tags Type a list of UCM components object selectors (no verification performed) Type a list of UCM baselines object selectors (no verification performed) Select paths in view to report on Associated with user (values are non-domain-qualified) 12 13
Text
Single
BASELEVELS
14
Text
Multiple
15 17
Associated with group (values are 18 non-domain-qualified) With label With attribute 19 20
271
Table 9. Parameters supplied with Rational ClearCase Reports (continued) Parameter ATTRIBUTE_VALUE TRIGGER BRANCH ELTYPE HLTYPE CCTIME BRANCHLEVELS FILE_NAME PATH STRING INTEGER REGULAR_ EXPRESSION Default text displayed in the parameter pane With value for attribute With trigger With branch With element type With hyperlink type Since date/time With integer levels of branching With filename Enter path With string Enter integer Enter regular expression Help ID Chooser 21 22 23 24 25 26 27 28 29 30 31 32 Text Type Type Text Type Date/time Text Text Text Text Text Text Selection Single Single Single Single Single Single Single Single Single Single Single Single
When you use one of the parameters that is listed in Table 9, naming it is all that is required. For example, this is the parameters specification for the Elements Changed Between Two Labels report:
parameters : LOOKIN LABEL LABEL
The order of parameters is important. They are displayed in the parameter pane in the order of the specification. (Each parameter appears as a link. When users click the link, they are prompted to enter a parameter value.) At run time, the Report Viewer calls the report procedure, which must handle the parameter values in the same order as defined in the specification. The parameters in Table 9 that are associated with the Type Chooser must also include the LOOKIN parameter in the interface specification. The LOOKIN parameter must have a value before any values for other parameters that use the Type Chooser can be specified. The paths that are the values for the LOOKIN parameter are used to build the set of VOBs that types can be read from. At run time, if a user attempts to set a type parameter in reverse order, the Report Builder displays this error message:
Before this parameter can be set, you must first set a value for the Select pathnames in view to report on parameter.
Rightclick specification
The rightclick specification is a list of commands available on the pop-up menu in the Report Viewer. All right-click events are supported by a list of scripts in the \scripts_rightclick directory. This specification allows you to control the text on the pop-up menu. At run time, underscores in these text strings are replaced by spaces.
rightclick : properties_of_view delete_view
By default, the commands are valid for both single and multiple selections of result records in the Report Viewer. This behavior can be controlled by using the single modifier:
rightclick : properties_of_view(single) delete_view(single)
272
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
A special string, sep, allows visual separators to group commands. At run time, these commands appear on the pop-up menu in the order specified.
Fields specification
The fields specification defines the names of the field headings and a number of modifiers to describe the results a report procedure returns to the Report Viewer. Table 10 describes the supported modifiers.
Table 10. Fields modifiers Modifier sort N Description Optional. Specifies the sort order for returned records. If specified, this modifier must be a sequence of integers that begin with 1. If no sort specification is made, the records remain in the same order as returned from the report procedure. Optional. Overrides the default width for the field. Required. Optional. Prevents display of values for this field in the Report Viewer. If this modifier is used, there is usually an associated sort N modifier for the field. Optional. The field value stream that is sent where any right-click action occurs in the Report Viewer. Only one field can be designated as the rightclick field.
rightclick
For example, the following fields specification describes a single field with the minimum specification allowed. The field_type modifier is required.
fields: "view tag"(view_tag)
In this example, the fields specification defines two fields, view tag and last mod time, with all the allowable modifiers:
fields: "view tag"(view_tag, rightclick, initial_width 10) "last mod time"(time_t, hidden, sort 1)
field_type conventions
Table 11 lists the names for field_types and the kind of data represented. Use these definitions in your own report procedures wherever possible; but you can use your own definitions.
Table 11. Field type supplied with Rational ClearCase Reports Field name project project_objsel stream stream_objsel activity activity_objsel Data description UCM Project headline name UCM project object selector UCM Stream headline name UCM Stream object selector UCM Activity headline name UCM Activity object selector Example V4.1 Project:v4.1@\projects George_v4.1 George_v4.1@\projects My activity Activity:my_act@\projects
273
Table 11. Field type supplied with Rational ClearCase Reports (continued) Field name view_tag time_t cctime User User_dq string Host Hpath View_sttrs Element_xpn Element_pn Version_pn label Integer Yes_no Branch_xpn version_xpn branch Attribute Objsel Trigger Eltype Vob_tag Data description Example
View-tag such as returned main_latest_view by lsview Integer ticks since 1/1/1970 Readable time, format is %dfmt_ccase User name Domain-qualified user name Random text Host name Local machine path to view/VOB directory View attributes Full path to element ending in @@ Full path to element without @@ 946934277 20-Dec-99.16:01:12 georgem rational\georgem hello world georgemnt D:\ClearCase_Storage\views\jet snapshot, ucmview S:\frontpage\accts\web\photo.htm@@ S:\frontpage\accts\web\photo.htm
Version specifier, after @@ \main\v4.0.bl5_main\2 Label instance name Integer number yes or no enumerated string Full path to branch Full path to version Branch name Attribute name Object selector Trigger name Element type VOB Tag V4.0 5 Yes S:\frontpage\accts\web\photo.htm@@\main S:\frontpage\accts\web\photo.htm@@\main\3 main normalize_html VOB:\my_vob post_ci text_file \projects
Depending on the column width that is required to display for a user-defined field_type, the fields specification in a report procedure may need to adjust the display column size with the Inital_width N modifier.
Parameter choosers
When a user opens a folder in the Report Builder tree pane, the reports pane is populated with the list of descriptions that the Report Builder discovered in the interface specification. When the user selects a report, the associated parameters are loaded in the Report Builder. Each parameter in the interface specification has associated parameter text, a help ID, and a chooser. All parameters have an associated chooser (Table 9). These choosers are supplied with Rational ClearCase Reports:
274
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
v v v v v
Path Chooser UCM Targets Chooser Types Chooser Date/Time Chooser Text Chooser
Path chooser
The Path Chooser is associated with the LOOKIN parameter. It presents a list of view paths for users to select, and then sends the selected paths to the report procedure. It is also used for the PVOB and PVOBS parameters to choose the VOB tag of a UCM project VOB.
Type chooser
The Type Chooser presents values for the BRANCH, ATTRIBUTE, LABEL, HYPERLINK, and TRIGGER parameters. All parameters that the Type Chooser supports require an initial value LOOKIN parameter.
Date/time chooser
The Date/Time Chooser is used to select date/time values for the CCTIME parameter.
Text chooser
The Text Chooser presents values for these parameters: COMPONENT, COMPONENTS, BASELINE, BASELINES, USER, GROUP, ATTRIBUTE_VALUE, ELTYPE, BRANCHLEVELS, FILE_NAME, PATH, STRING, INTEGER, and REGULAR_EXPRESSION. Data typed into the Text Chooser is not validated or parsed in any way by the Report Builder or Report Viewer. The report procedure that accepts the parameter value must perform any validation required. For most parameters, the text above the field is Enter value for user. For parameters that require the name of a baseline, a component, or an element type, the text changes to reflect the parameter. For example: Enter value for baseline. BASELINE COMPONENT component:<comp>@\<pvob> ELTYPE <text_file> baseline:<bl>@ \<pvob>
275
The Report Viewer creates a process to run the report procedure using ccperl.exe for .prl, perl for .pl, cscript.exe for .js and .vbs, and default activation for .exe. The report procedure returns results to STDOUT. The results are separated by semicolons, in the same order, number, and type specified in the fields definition in the interface specification. When the report procedure has collected all its data, it exits. The report procedure must return records to STDOUT in the most efficient manner possible; the Report Viewer sorts the results and formats them for display. At run time, users can change the default sorting order by clicking the column headings in the Report Viewer. Simple text sorting is used for all fields except those whose field_type is time_t, integer, or cctime. For these three fields only, Report Viewer uses numeric sorting.
Saving the file is performed by the save_results.prl script in \script_tools. This script supports two switches, -html and -csv, and the header, followed by semicolon-separated data rows. This script also needs a path value for the -out option, where path is the value that the Report Viewer passes from the Path Chooser. XML output is supported directly by the Report Viewer. You can re-implement the .CSV and .HTML output by modifying save_result.prl. You can also define additional XSL style sheets that can be referred to in XML output. Start with the style sheet supplied with Rational ClearCase Reports (\script_tools\table.xsl) to create customized XSL files.
276
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
v Example 5: Adding a user-defined command to the pop-up menu for Element_with_Branches.prl. In the source code listings that accompany each example, the string ### customization change marks the changes to the original report that accomplish the task.
Processing logic
The processing logic of Versions_by_Date.prl is as follows: 1. The LOOKIN parameter, which is the sole parameter for this function, is received in a string of this form:
LOOKIN = "<path1> [<path2> ...]"
This parameter specifies the list of paths with which the cleartool find command is to be invoked. 2. When the routine is invoked, it extracts the paths from the LOOKIN string and passes them to the check_lookin() routine (located in common_script.prl). 3. The routine check_lookin() then puts the paths into the global variable $ctfind_paths and encloses each path in double quotes; it also performs simple validations on the paths received. 4. The report procedure calls cleartool lshistory, passing $ctfind_paths as the paths parameter, and with a -fmt parameter to return the necessary information. 5. The report procedure executes a print statement with parameters (that is, the items to print) of the same number and order as the list passed during interface specification processing. The Report Builder has the information required to set up the column headings; the report procedure must conform to this specification to print its output.
Interface specification
This is the existing interface specification for Versions_by_Date.prl:
if (/^-i/) { print "description : Versions by Date\n"; print "id : 2018\n"; print "helpfile :\n"; print "parameters : "; print "LOOKIN "; print "\n"; print_version_rightclick(); print "fields : "; print "\"Version Path\(version_xpn, rightclick, sort 2) "; print "\"Version Creation Time\"(cctime) "; print "\"Version Creation Time\"(time_t, sort 1, hidden) "; print "\n"; exit(0); }
277
Changes required
To add an additional column of report output: 1. Add a properly coded print statement to the interface specification that the Report Builder can pass to the Report Viewer. 2. Add a %Fu; to the -fmt parameter in the cleartool lshist call to get this information from the Rational ClearCase configuration. 3. Properly extract the user information into some variable after the cleartool lshist call returns its output, so that it can be printed. 4. Print the user variable in the same order as it appeared in the interface specification so that it appears under the correct column heading.
278
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
print "helpfile :\n"; print "parameters : "; print "LOOKIN "; print "\n"; print_version_rightclick(); print "fields : "; print "\"Version Path\"(version_xpn, rightclick, sort 2) "; print "\"Version Creation Time\"(cctime) "; print "\"Version Creation Time\"(time_t, sort 1, hidden) "; ### customization change *** added following line print "\"User(user) "; print "\n"; exit(0); } if (/^LOOKIN[ ]*=[ ]*(.*)/) { check_lookin($1); $required_args++; next; } print STDERR "unrecognized argument: $_\n"; print STDERR " ccperl $0 -i\n"; print STDERR " for scripts interface.\n"; do_exit("\n"); } if ($required_args != 1) { print STDERR "usage: not all required arguments specified.\n"; print STDERR " ccperl $0 -i\n"; print STDERR " for scripts interface.\n"; do_exit("\n"); } $ENV{"d;"} = "d;"; open(CTHIST, "cleartool lshist -fmt %d;%e;%n\\n -recurse -nco $ctfind_paths |"); while(<CTHIST>) { chomp; if (/create directory version/ || /create version/) { ($date, $event, $xpn) = split /;/, $_, 3; if ($date) {;} if ($event) {;} if ($xpn) {;} $timet = time_to_ticks($date); ### customization change *** added following line $user = cleartool desc -fmt %Fu $xpn; ### customization change *** added ";$user" to following line print "$xpn;$date;$timet;$user\n"; } } do_exit();
279
v Display a new report description: Types of Elements with New Versions Since Date. v Display the version path information in the version_xpn field in a different format. v Add a column in the report output to display a new column for Element Type. The report procedure is located in:
ccasehomedir\Reports\Scripts\Elements\Elements_with_New_Versions_Since_Date.pr
Processing logic
The processing logic of Elements_with_New_Versions_Since_Date.prl is as follows: 1. When the Report Builder processes the interface specification, the report procedure yields two parameters:
LOOKIN CCTIME
The mechanics of the LOOKIN parameter are described in Example 1: Adding a column to report output on page 277. When the report procedure receives CCTIME, it is a string of this form:
CCTIME = "time"
This parameter specifies the times that the cleartool find command uses. 2. When the report procedure is invoked by the Report Viewer using a fully qualified command line, it extracts the values from the CCTIME string and passes them to the chooser_time_to_cctime() subroutine (located in common.prl). This routine converts the string to the correct format (for passing to cleartool) and returns it. 3. The report procedure opens a pipe from a cleartool find -print command, with the converted cctime value passed in as a created_since(<cctime>) string. The value created_since is a query_language(1) predicate, which is frequently used in conjunction with the find command. 4. As the values from the cleartool find command are returned, the report procedure calls cleartool describe on the output to get the version-creation time. The routine calls the time_to_ticks() routine (in common.prl) to get the time equivalent in ticks. 5. The report procedure gets the path and version ID from the cleartool find output, splitting it on the value of the $CLEARCASE_XN_SFX extended naming symbol for the host. Finally, the report procedure prints the information in the same order as defined in the interface specification.
Interface specification
This is the existing interface specification for Elements_with_New_Versions_Since_Date.prl:
if (/^-i/) { print "description : Elements with New Versions Since Date\n"; print "id : 2017\n"; print "helpfile :\n"; print "parameters : "; print "LOOKIN CCTIME"; print "\n"; print_element_rightclick(); print "fields : "; print "\"Element Path\"(element_pn, sort 2, rightclick) "; print "\"Version Path\"(version_pn) "; print "\"Version Creation Time\"(cctime) ";
280
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
print "\"Version Creation Time\"(time_t, hidden, sort 1) "; print "\n"; exit(0); }
Changes required
To change the directory organization and report description, to modify the version path to use a different field name, and to add an element type column to the report output: 1. Create a new folder, New_Versions, and move the report procedure there. 2. Add a properly coded print statement to the interface specification that does the following: v Specifies how to display the report description information in the Report Builder v Specifies how to display the report in the Report Viewer 3. Add additional processing to the cleartool find output as required to get the desired information for element type. 4. Properly extract the new information for element type into a variable. 5. Print the new information in the proper position so that it appears under the correct column heading.
281
$args =~ s/%/ /g; @args = split(";", $args); my $cctime = ""; $required_args = 0; foreach(@args) { s/^[ ]+//; s/[ ]+$//; validate_arg_length($_); if (/^-i/) { ### customization change *** changed following line print "description : Types of Elements with New Versions Since Date\n"; print "id : 2017\n"; print "helpfile :\n"; print "parameters : "; print "LOOKIN CCTIME"; print "\n"; print_element_rightclick(); print "fields : "; print "\"Element Path\"(element_pn, sort 2, rightclick) "; ### customization change *** changed following line print "\"Version Path\"(version_xpn) "; print "\"Version Creation Time\"(cctime) "; print "\"Version Creation Time\"(time_t, hidden, sort 1) "; ### customization change *** added following line print "\"Element Type\"(eltype) "; print "\n"; exit(0); } if (/^LOOKIN[ ]*=[ ]*(.*)/) { check_lookin($1); $required_args++; next; } if (/^CCTIME[ ]*=[ ]**([^]*)*/) { $cctime = chooser_time_to_cctime($1); $required_args++; next; } print STDERR "unrecognized argument: $_\n"; print STDERR " ccperl $0 -i\n"; print STDERR " for scripts interface.\n"; do_exit("\n"); } if ($required_args != 2) { print STDERR "usage: not all required arguments specified.\n"; print STDERR " ccperl $0 -i\n"; print STDERR " for scripts interface.\n"; do_exit("\n"); } open(CTFIND, "cleartool find $ctfind_paths -version created_since($cctime) -print |"); while(<CTFIND>) { chomp; if (/CHECKEDOUT/) {next;} $vertime = cleartool desc -fmt %d $_; ### customization change *** added following line $eltype = cleartool desc -fmt %[type]p $_; $vertime_t = time_to_ticks($vertime); ($path, $verid) = split $CLEARCASE_XN_SFX, $_, 2; ### customization change *** changed following line print "$_;$verid;$vertime;$vertime_t;$eltype\n"; #print "$path;$verid;$vertime;$vertime_t\n"; } do_exit();
282
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
Processing logic
The processing logic of Elements_Created_by_User.prl is as follows: 1. When the Report Builder processes the interface specification, the report procedure yields two parameters:
LOOKIN USER
The mechanics of the LOOKIN parameter are described in Example 1: Adding a column to report output on page 277. The report procedure receives USER as a string of this form:
USER= "user-name"
This parameter specifies the user name that the cleartool subcommand uses. 2. The USER string is extracted and stored as $ccuser. It is then passed to the created_by($ccuser). 3. The created_by ($ccuser) query language primitive filters the paths specified to cleartool find and returns only those that match the predicate, in this case, those created by the user by setting a parameter value for USER. 4. The user variable is printed in the same order specified in the interface specification so that it appears under the correct column heading.
Interface specification
This is the existing interface specification for Elements_Created_by_User.prl:
if (/^-i/) { print "description : Elements Created by User\n"; print "id : 2016\n"; print "helpfile :\n"; print "parameters : "; print "LOOKIN USER"; print "\n"; print_element_rightclick(); print "fields : "; print "\"Element Path\"(element_xpn, sort 2, rightclick) "; print "\"Creating User\"(user, sort 1) "; print "\n"; exit(0); }
283
Changes required
To remove the user parameter, to add parameters for group and date/time, and to adjust the report output for group and date/time information: 1. Change the interface specification of the report procedure to correspond to required interface changes. 2. Change the logic in the report procedure to handle data requests for group information; add a %Gu; to the -fmt parameter in thecleartool describe call to get group information from the Rational ClearCase configuration. 3. Properly extract the group information into a variable after the cleartool describe call returns its output, so that it can be printed. 4. Determine whether the element group is the same group parameter value entered by the user and print the result of this comparison as a column heading. 5. Print the group variables in the order specified in the interface specification so that they appear under the correct column heading.
284
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
s/^[ ]+//; s/[ ]+$//; validate_arg_length($_); if (/^-i/) { ### customization change *** changed following line print "description : Elements With Group\n"; print "id : 2016\n"; print "helpfile :\n"; print "parameters : "; ### customization change *** changed following line print "LOOKIN GROUP"; print "\n"; print_element_rightclick(); print "fields : "; print "\"Element Path\"(element_xpn, sort 2, rightclick) "; ### customization change *** added following 2 lines print "\"Elements Group\"(group, sort 1) "; print "\"Same\"(yes_no) "; ### customization change *** deleted following line #print "\"Creating User\"(user, sort 1) "; print "\n"; exit(0); } if (/^LOOKIN[ ]*=[ ]*(.*)/) { check_lookin($1); $required_args++; next; } ### customization change *** deleted following 2 lines #if (/^USER[ ]*=[\t ]*\"*([^\"]*)\"*/) { #$ccuser = $1; ### customization change *** added following 2 lines if (/^GROUP[ ]*=[\t ]*\"*([^\"]*)\"*/) { $ccgroup = $1; $required_args++; ### customization change *** deleted following line #validate_user($ccuser); next; } print STDERR "unrecognized argument: $_\n"; print STDERR " ccperl $0 -i\n"; print STDERR " for scripts interface.\n"; do_exit("\n"); } if ($required_args != 2) { print STDERR "usage: not all required arguments specified.\n"; print STDERR " ccperl $0 -i\n"; print STDERR " for scripts interface.\n"; do_exit("\n"); } ### customization change *** deleted following 3 lines #if ($ccuser =~ /[ ]+/) { # do_clearprompt("cleartool find does not allow spaces in user names; # cannot proceed."); #} ### customization change *** changed following line open(CTFIND, "cleartool find $ctfind_paths -nxname -print |"); while(<CTFIND>) { chomp; ### customization change *** added following 6 lines $grp = cleartool desc -fmt %Gu $_; if ($grp eq $ccgroup) { $same = "yes"; } else { $same = "no";
Appendix C. Customizing Rational ClearCase Reports
285
} ### customization change *** changed following line print "$_;$grp;$same\n"; #print "$_;$ccuser;\n"; } do_exit();
Interface specification
This is the existing interface specification for Elements_with_Labels.prl:
if (/^-i/) { print "description : "; print "Elements with Labels"; print "\n"; print "id : 2003\n"; print "helpfile :\n"; print "parameters : "; print "LOOKIN "; print "LABEL "; print "\n"; print_element_rightclick(); print "fields : "; print "\"Element Path\"(element_pn, rightclick, sort 1)"; print "\n"; exit(0); }
Note the call to print_element_rightclick() in the middle of the interface specification. The code for this routine is located in \script_tools\common.prl:
sub print_element_rightclick { print "rightclick : "; print "Properties_of_Element(single) "; print "sep "; print "Version_Tree(single) "; print "History(single) "; print "\n"; }
Changes required
A convention used in the report procedures is to put the same commands on pop-up menus for all reports that use the same primary sort field. For example, all the reports whose primary sort key is element or element_xpn display the same set of commands.
286
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
To make an additional command available for all reports whose primary sort key is element or element_xpn, modify the routines stored in \script_rightclick and then edit the associated routine in \script_tools\common.prl. To change the report procedure, copy the contents of sub print_element_rightclick (located in \script_tools\common.prl) and paste it into the appropriate part of the interface specification. Then, add a declaration to display the new command.
287
print "\n"; ### customization change *** deleted following line #print_element_rightclick(); ### customization change *** added following 7 lines print "rightclick : "; print "Properties_of_Element(single) "; print "sep "; print "Compare_with_Previous_Version(single) "; print "Version_Tree(single) "; print "History(single) "; print "\n"; print "fields : "; print "\"Element Path\"(element_pn, rightclick, sort 1)"; print "\n"; exit(0); } if (/^LOOKIN[ ]*=[ ]*(.*)/) { #print "paths are $1\n"; check_lookin($1); $required_args++; next; } if (/^LABEL[ ]*=[ ]**([^]*)*/) { $cclabel = $1; #print "label is $cclabel\n"; $required_args++; next; } print STDERR "unrecognized argument: $_\n"; print STDERR " ccperl $0 -i\n"; print STDERR " for scripts interface.\n"; do_exit("\n"); } if ($required_args != 2) { print STDERR "usage: not all required arguments specified.\n"; print STDERR " ccperl $0 -i\n"; print STDERR " for scripts interface.\n"; do_exit("\n"); } open(CTFIND, "cleartool find $ctfind_paths -element lbtype_sub($cclabel) -print |"); while(<CTFIND>) { chomp; ($path, $rest) = split $CLEARCASE_XN_SFX, $_, 2; if ($rest) {;} print "$path;\n"; } do_exit();
288
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
required to included it is different from that described in Example 4: changing the pop-up menu for right-click handling on page 286. These commands currently appear on the pop-up menu: v Properties of Element v Version Tree v History
Interface specification
This is the existing interface specification for Elements_with_Branches.prl:
if (/^-i/) { print "description : Elements with Branches\n"; print "id : 2013\n"; print "helpfile :\n"; print "parameters : "; print "LOOKIN BRANCH"; print "\n"; print_element_rightclick(); print "fields : "; print "\"Element Path\"(element_xpn, sort 1, rightclick) "; print "\"Branch\"(branch) "; print "\n"; exit(0); }
Changes required
Making this modification requires a new script for the new command functions. You must place this script in the \scripts_rightclick directory. (The script can be written in any of the supported programming languages.) The script must be coded to receive a stream on input from STDIN from a field that is designated by a rightclick modifier in the interface specification of the report procedure. For example, to create my_rc.prl, which starts clearmrgman.exe (Merge Manager), you must place my_rc.prl in \scripts_rightclick.
289
exit(0); } } open(INCLUDE, "<$common_dir\\common_script.prl") or do_exit("error opening include file $common_dir\\common.prl"); $buf = ""; while(<INCLUDE>) { $buf = $buf . $_; } close(INCLUDE); eval $buf || do_exit("error on eval of include file $common_dir\\common.prl"); my $args = $ARGV[0]; $args =~ s/%/ /g; @args = split(";", $args); my $ccbranch = ""; $required_args = 0; foreach(@args) { s/^[ ]+//; s/[ ]+$//; validate_arg_length($_); if (/^-i/) { print "description : Elements with Branches\n"; print "id : 2013\n"; print "helpfile :\n"; print "parameters : "; print "LOOKIN BRANCH"; print "\n"; ### customization change *** deleted following line #print_element_rightclick(); ### customization change *** added following 8 lines print "rightclick : "; print "my_rc(single) "; print "Properties_of_Element(single) "; print "sep "; print "Compare_with_Previous_Version(single) "; print "Version_Tree(single) "; print "History(single) "; print "\n"; print "fields : "; print "\"Element Path\"(element_xpn, sort 1, rightclick) "; print "\"Branch\"(branch) "; print "\n"; exit(0); } if (/^LOOKIN[ ]*=[ ]*(.*)/) { #print "paths are $1\n"; check_lookin($1); $required_args++; next; } if (/^BRANCH[ ]*=[ ]**([^]*)*/) { $ccbranch = $1; $required_args++; next; } print STDERR "unrecognized argument: $_\n"; print STDERR " ccperl $0 -i\n"; print STDERR " for scripts interface.\n"; do_exit("\n"); } if ($required_args != 2) { print STDERR "usage: not all required arguments specified.\n"; print STDERR " ccperl $0 -i\n"; print STDERR " for scripts interface.\n";
290
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
do_exit("\n"); } open(CTFIND, "cleartool find $ctfind_paths -nxname -branch brtype($ccbranch) -print |"); while(<CTFIND>) { chomp; print "$_;$ccbranch;\n"; } do_exit();
Here is the new command of my_rc.prl that has been created to support a new pop-up menu command for starting Merge Manager. This report procedure is available in the T0046 package, which is available at IBM Rational Support (see Obtaining the T0046 package on page 293).
# these are all set by set_record_vars in common_rightclick.prl # $CLEARCASE_PN = "", $CLEARCASE_XN_SFX = "", $CLEARCASE_ID_STR = "", $CLEARCASE_XPN = ""; $CLEARCASE_BRANCH_PATH = "", $CLEARCASE_VERSION_NUMBER = ""; $ELEMENT_RESULTS = "", $BRANCH_RESULTS = "", $VERSION_RESULTS = ""; $results = ""; $debug = "no"; $start_dir = $0; $start_dir =~ s/\\scripts_rightclick\\.*/\\scripts_rightclick/; $common_dir = $start_dir; $common_dir =~ s/(.*)\\scripts_rightclick/$1\\script_tools/; open(INCLUDE, "<$common_dir\\common_rightclick.prl") or do_exit("error opening include file $common_dir\\common_rightclick.prl"); $buf = ""; while(<INCLUDE>) { $buf = $buf . $_; } close(INCLUDE); eval $buf || do_exit("error on eval of include file $common_dir\\common_rightclick.prl"); if if if if if if if if if if ($CLEARCASE_PN) {;} ($CLEARCASE_XN_SFX) {;} ($CLEARCASE_ID_STR) {;} ($CLEARCASE_XPN) {;} ($CLEARCASE_BRANCH_PATH) {;} ($CLEARCASE_VERSION_NUMBER) {;} ($ELEMENT_RESULTS) {;} ($BRANCH_RESULTS) {;} ($VERSION_RESULTS) {;} ($debug) {;}
$first = "yes"; while(<STDIN>) { chomp; set_record_vars($_); ######################################################################## # things to be done a record at a time are done here if ($first eq "yes") { $first = "no"; open(COMMAND, "clearmrgman |"); while(<COMMAND>) {;} close(COMMAND); } ######################################################################## } # things to be done with the result set as a whole go here
Appendix C. Customizing Rational ClearCase Reports
291
Troubleshooting customization
There are two primary areas that you may need to troubleshoot: v Errors in the interface specification v Coding high-level languages other than ccperl
Test your report procedures before you check them in to the shared directory tree that you have configured. If you do not run the testing script before using your report in Report Builder and a parsing error occurs in processing the interface specification, the new report is not displayed in the list of reports in the reports pane. There is no feedback; you see the report description in the reports pane or you see nothing. If you do not see a description, the parsing error is serious. If you do see a description, the interface specification is somewhat correct, but you may still be using an invalid parameter, referring to a nonexistent right-click routine, or sending output in the wrong order to STDOUT. The Report Builder does not check for valid parameters. For example, consider the interface specification for a new report procedure, my_custom_report.prl, with the following interface specification:
description : "This test report asks for a three known parameters and two unknown parameters" id : 2500 parameters : LOOKIN UNKNOWN_1 STREAMS FOO PROJECT rightclick : fields : "field 1"(string)
292
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
The second and fourth parameters of this interface specification are invalid. At run time, the description for this report appears in the Report Builder reports pane, but the second and fourth parameters are displayed as blank lines in the parameter pane. However, the testing script detects these errors because these parameter names are not supplied with ClearCase Reports (see Table 9):
my_custom_report.prl: desc: this test report asks for a three known parameter and two unknown parameters id: 2500 parm: LOOKIN *********************** ERROR: illegal parameter: UNKNOWN_1 *********************** continue? (y/n) > y UNKNOWN_1 STREAMS *********************** ERROR: illegal parameter: FOOBAR *********************** continue? (y/n) > y
293
294
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
Appendix D. Notices
This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the users responsibility to evaluate and verify the operation of any non-IBM product, program, or service. IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not grant you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing IBM Corporation North Castle Drive Armonk, NY 10504-1785 U.S.A. For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to: IBM World Trade Asia Corporation Licensing 2-31 Roppongi 3-chome, Minato-ku Tokyo 106, Japan The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice. Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk. IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you. Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created
Copyright IBM Corp. 1992, 2006
295
programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact: IBM Corporation Department BCFB 20 Maguire Road Lexington, MA 02421 U.S.A. Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee. The licensed program described in this document and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any equivalent agreement between us. Any performance data contained herein was determined in a controlled environment. Therefore, the results obtained in other operating environments may vary significantly. Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some measurement may have been estimated through extrapolation. Actual results may vary. Users of this document should verify the applicable data for their specific environment. Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products. COPYRIGHT LICENSE: This information contains sample application programs in source language, which illustrates programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. You may copy, modify, and distribute these sample programs in any form without payment to IBM for the purposes of developing, using, marketing, or distributing application programs conforming to IBMs application programming interfaces. Each copy or any portion of these sample programs or any derivative work, must include a copyright notice as follows: (c) (your company name) (year). Portions of this code are derived from IBM Corp. Sample Programs. (c) Copyright IBM Corp. _enter the year or years_. All rights reserved. Additional legal notices are described in the legal_information.html file that is included in your Rational software installation. Trademarks
296
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
AIX, ClearCase, ClearQuest, DB2, IBM, Rational, RequisitePro, and XDE are trademarks of International Business Machines Corporation in the United States, other countries, or both. Java and all Java-based trademarks and logos are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both. UNIX is a registered trademark of The Open Group in the United States and other countries. Linux is a trademark of Linus Torvalds in the United States, other countries, or both. Other company, product or service names may be trademarks or service marks of others.
Appendix D. Notices
297
298
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
Index A
about 12 activities about 9 assign 102 create and assign in Rational ClearQuest (procedure) 102 creating and setting in new project (procedure) 94 decomposing in Rational ClearQuest 81 fixing Rational ClearQuest links 103 linked to Rational ClearQuest records 105 migrating to integration with Rational ClearQuest (UCM) 101 state transition after delivery 70 verifying owner of 70 when to delete unused 126 administrative VOBs and PVOBs 54 assignments verifying 28 attributes about 160 change request policy 184 use in config specs 170 use in monitoring project status 180 baselines in UCM (continued) strategy for 45 test planning 52 when to create 51 when to delete unused 126 bootstrap projects 146 branch types example 245 branches about 158 bug-fix policy 181 config spec rules for 166, 167, 168 controlling creation of 159 example of project strategy 243 in Rational ClearCase MultiSite 159 mastership transfer models 187 merge policies 161 merging elements from UCM projects 152 merging to main 224 multiple levels, config specs for 168 naming conventions 159 sharing for merges 224 stopping development on 254 building software, view configurations 174
B
base ClearCase and UCM, compared 3 baseline-plus-changes model 181 baselines in base ClearCase 242 creating, extended example 247, 251 labeling policy 181 baselines in UCM 5 about 13 benefits of frequent 51 comparing (procedure) 123 composite 14 conflicts in composite 120 creating 19 creating composite 96 creating for imported files (procedure) 98 creating new (procedure) 114 creating streams for testing (procedure) 106 dependency relationships in composite of ordinary component 48 dependency relationships in pure composite 47 descendant 14 fixing problems (procedure) 118 foundation 14, 91 making descendant 49 making descendant of composite 50 naming convention 52 naming template, setting 92 overrides 121 promoting and demoting (procedure) 119 promotion levels 24 pure composite 47 recommend 119 recommended 25 recommended promotion policy 64 sharing between projects 151 Copyright IBM Corp. 1992, 2006
C
ccase-home-dir directory xiii change requests tracking in base ClearCase 184 tracking states 28 change set 9, 191 cmregister command 59 code page conversion 207 Component Tree Browser 122 components about 11 adding to integration stream (procedure) 110 ancillary 32 candidates for read-only 33 conversion of VOBs (procedure) 97 crating for element storage 88 crating multiple-component VOB 88, 89 creating one in VOB 91 creating one per VOB 89, 90 creating without a VOB root directory 87 design considerations 29 importing files for (procedure) 95 mapping to projects 30 modifiability 63 organizing for project 31 recommended directory structure 33 visibility 63 when to delete unused 126 without a VOB root directory 50 composite baselines (UCM) 14 create (procedure) 96 pure 47 config specs about 159, 163 default, standard rules in 163
299
config specs (continued) examples for builds 174 examples for development tasks 166 examples for one project 245 examples of time rules 167, 168, 172, 173 examples to monitor project 170 include file facility 164 project environment for samples 165 restricting changes to one directory 169 selecting library versions 174 sharing across platforms 177 use of element types in 231 config.pl file 194, 201 configTemplate.pl file 201 conventions, typographical xiii cquest-home-dir directory xiii credentials Rational ClearQuest user database 82 customer support xvi
F
feature levels 56 feature-specific streams 107 foundation baselines choosing 91 definition 14
G
global types 54, 161
H
Help, accessing xiv hyperlinks about 160 requirements tracking mechanism 185
D
deliver operations backward 40 checkouts policy 65 element types and merging 56 finding posted work (procedure) 113 forward 40 from integration stream 151 MultiSite 113 Rational ClearCsse MultiSite and 18 rebase before policy 65 remote 113 remote, completing (procedure) 113 state transition policy 70 undoing 113 development streams 12 configuration 36 creating feature-specific (procedure) 107 creating for testing (procedure) 106 feature-specific 35, 107 making read-only 106 read-only 45 rebase (procedure) 118 when to delete unused 126 directories, merging 227 directory structure creating new (procedure) 94 recommended, for UCM components 33 documentation Help description xiv
I
IBM Rational Unified Process 29 importing files and directories 95 include file facility 164 integration streams about 12 adding components (procedure) 110 configuration 36 delivery from 151 locking considerations 52 merging to base ClearCase branch 152 updating development view load rules 111 when to delete unused 126 integration views creating for UCM project (procedure) 93 recommended view type 64 integration with Rational ClearQuest (base ClearCase) association batch feature 211 associations 209 automatic associations 214 automatic associations tuning 213 batch confirmation 213 batch definition 213 change set 191 checklist 195 comment patterns 215 configuration file 194 configuration file editing 200 configuration parameter summary 201 configuration test 208 connectivity 203 CQSchema 205 customization policy 194 customizing 217 debugging 215 enabling VOBs 192 forcing checkin success 211 GUI use 211 installing triggers 197 logging output 216 overview 191 package 194 performance 211 planning 196 policy choices 197, 209 query filter 210
191
E
element relocation in UCM 111 element types how assigned 230 predefined and user-defined 232 element types in UCM 56 define scope 57 manage merge behavior 56 environment variables for Rational ClearQuest event records 161
83
300
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
integration with Rational ClearQuest (base ClearCase) (continued) query support 192 query usage 210 Query Wizard 217 Rational ClearCase MultiSite support 207 Rational ClearQuest user database definition 204 Rational ClearQuest user database setup 196 request set 191 SAMPL user database 200 sharing configuration file 198 start configuration tool 199 testing 216 timing information 216 trigger installation 199 trigger versions 193 troubleshooting connections 209 use with UCM integration 263 Web interface 203 integration with Rational ClearQuest (UCM) about 16, 26 credentials 82 customizing policies 81 database, setting up 75 decomposing activities 81 disabling links to project 102 enabling custom schema (procedure) 76 enabling projects to use (procedure) 100 environment variables 83 mastership when enabling 104 planning issues 57 policies for 69 Rational ClearQuest MultiSite requirements 104 replica and naming requirements 104 setting up 16 setting up UCM schemas (procedure) 75 use with base ClearCase 263
merging in base ClearCase (continued) how it works 219 other tools 228 removing merged changes 223 selective merge 222 to main branch 224 mkelem_cpver.pl script 111 MultiSite remote deliver operations 113
N
naming conventions branches 159 Rational ClearQuest schema 58 UCM baselines 52 views in base ClearCase 159 naming template, baselines in UCM setting 92
92
O
obsolete objects overrides 121 161
P
package obtaining T0046 293 parallel development base ClearCase mechanisms 158 extended example in base ClearCase 241 UCM scenarios 147 parent/child controls in Rational ClearQuest 81 patch release in UCM project 150 Perl usage 132 planning projects in UCM 29 policies in base ClearCase access to project files 182 bug-fixing on branches 181 change requests 184 coding standards 184 documenting changes 179 enforcement mechanisms 160, 179 integration with Rational ClearQuest choices 197 labeling baselines 181 monitoring state of sources 180 notification of new work 183 on merging 161 requirements tracking 185 restricting changes visible 182 restricting use of commands 187 transfer of branch mastership 187 policies in UCM about 16 action after activity change 72 activity change transition 73 allowed record types for activities 70 approval before activity change 72 approval before delivery 70 baseline modification 65 changing with integration and MultiSite 105 customizing Rational ClearQuest 81 default view types 64 Index
L
labels about 160 baselines in base ClearCase 181 use in config specs 173, 174 load rules 164 updating for new component in parent stream 111 locks about 161 examples 182
M
magic files 230 main branch 158 makefiles and config specs 175 mastership about 18 models of transfer 187 mergetypes 56 merging in base ClearCase about 161 commands for 222 directory versions 227 entire source tree 225 extended example 248, 252 GUI tools for 221
301
policies in UCM (continued) delivery between projects 73 delivery from other projects 69 delivery transfer of mastership (after) 72 delivery transfer of mastership (before) 71 delivery transition 71 delivery transition state 70 delivery with changes of non-visible components 69 delivery with checkouts 65 delivery with foundation baseline changes 67 delivery with missing component changes 68 delivery with non-modifiable component changes 68 disallow record submission from Rational ClearCase client 69 modifiable components 63 modifiable components and visibility 63 project modification 65 promotion levels 24 rebase before deliver 65 recommended baselines 64 setting Rational ClearQuest (procedure) 101 stream modification 65 verify activity owner before checkout 70 policy choices integration with Rational ClearQuest (base ClearCase) 209 Project Explorer start 88 projects in base ClearCase branching strategy 158 config specs 159 development policies 160 extended example of lifecycle 241 generating reports 161 merging policies 161 planning and setup 157 views to monitor progress 170 projects in UCM about 9 bootstrap 146 changing name of 105 cleanup tasks 125 component-oriented 143 composite baselines in component-oriented 145 composite baselines in release-oriented 143 concurrent, managing 147 create from existing projects 99 creating 11 creating from existing configuration 97 creating new (procedure) 91 delete unused 125 deliver from integration stream 151 disabling links to Rational ClearQuest database 102 factors in gauging scope 30 fixing Rational ClearQuest activity links 103 importing components 95 incorporating patch release 150 lock and hide 127 mainline 142 maintenance tasks 109 managing multiple 147 mapping components to 30 merging to base ClearCase branches 152 migrating unfinished work 149 multiple-stream 34 parallel 30 planning issues 29 policies 63
projects in UCM (continued) release-oriented 141 set up new 85 setting baseline naming template 92 single-stream 44 tools to monitor progress 122 promotion levels about 24 changing (procedure) 119 default 52 defining in new project (procedure) 93 policy for recommended baselines 64 pure composite baselines (UCM) 47 PVOBs about 11 administrative VOB and multiple 55 as administrative VOBs 54 creating from existing configuration 97 creating new (procedure) 86 feature levels and multiple 56 links and Rational ClearQuest MultiSite 103 mapping to Rational ClearQuest user database multiple 54 planning 53
57
Q
Query Wizard integration with Rational ClearQuest (base ClearCase) querying Rational ClearQuest user database 28, 124 217
R
Rational ClearCase MultiSite branches and 159 establish for integration with Rational ClearQuest (base ClearCase) 207 mastership transfer models 187 use in UCM 18 Rational ClearCase Reports customizable features 265 customization examples 276 how it works 265 interface specification in report procedures 270 parameter choosers 274 run-time processing 266 setting up shared directories 268 Rational ClearQuest querying user database 124 recommended use of Rational ClearCase integrations 263 scripts instead of triggers (UCM) 130 start client 101 Rational ClearQuest MultiSite links in PVOBs 103 UCM integration affect 104 Rational ClearQuest user database setup for integration with Rational ClearQuest (base ClearCase) 196 ratlperl 132, 189 read-only streams 45 rebase operations advance 21 between projects (procedure) 148 directions 20 element types and merging 56 lateral 23
302
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
rebase operations (continued) policy for deliver operations 65 revert 22 rules summary 23 recommended baselines policy for promotion level 64 record types for schemas, custom 78 remote deliver operations 113 reports for base ClearCase projects 161 Rational ClearQuest queries 124 request set 191
S
schemas (Rational ClearQuest) about UCM-enabled 28 adding Rational ClearCase definitions to 197 adding Rational ClearCase definitions to (procedure) 197 enabling custom for UCM 60 enabling custom for UCM (procedure) 76 predefined, using 75 queries 28 requirements for UCM 59 storage issues 59 selective merge 222 serial development environment 44 smoke tests 52 state types about 28 default transition requirements 79 setting for custom schemas 78 streams 4, 12 alternate targets 39 alternate targets in same project 39 coordinating in same project 41 creating feature-specific 107 default targets 38 development configuration 36 hierarchies 35 integration configuration 36 lock and hide 127 locking (procedure) 113 projects with single 44 read-only 45 relationships 36 sharing by delivery 42 sharing by rebase 41 strategy 34 unlocking (procedure) 116 subtractive merge 223 Suite 105 supertypes 232 system architecture 29
triggers (continued) policy scripts instead of 130 preoperation and postoperation 130 sharing in interop environments (base ClearCase) sharing in interop environments (UCM) 131 to disallow checkins 184 to notify team of new work 183 to restrict use of commands 187 UCM use 129 type managers about 230 creating directory for 234 how they work 233 implementing compare method 236 inheriting methods 234 predefined 232 testing 238 user defined 232 typographical conventions xiii
188
U
UCM and base ClearCase, compared 3 UCMPolicyScripts package 59 UnifiedChangeManagement package 59, 60 user accounts creating Rational ClearQuest profiles (procedure) 82
V
version control, candidates for 30 view profiles moving to UCM 261 views config specs 163 configuring for builds 174 configuring for development tasks 166 configuring historical 173 configuring to monitor project 170 naming conventions in base ClearCase 159 policy for default types in UCM 64 restricting changes visible in 182 sharing for merges 225 VOB Creation Wizard 86 VOBs converting to UCM components (procedure) 97 creating and populating in base ClearCase 157 enabling for integration with Rational ClearQuest (base ClearCase) 192 how many in project (UCM) 31 list triggers installed in 199
W
Web interface integration with Rational ClearQuest (base ClearCase) work areas 12 203
T
T0046 package 293 time rules in config specs 167, 168, 172, 173 triggers about 160 attach 184 checkin command example 179 installing for integration with Rational ClearQuest (base ClearCase) 192 list installed in VOBs 199
Index
303
304
IBM Rational ClearCase and Rational ClearCase LT: Guide to Managing Software Projects
How satisfied are you that the information in this book is: Very Satisfied Accurate Complete Easy to find Easy to understand Well organized Applicable to your tasks h h h h h h Satisfied h h h h h h Neutral h h h h h h Dissatisfied h h h h h h Very Dissatisfied h h h h h h
h Yes
h No
When you send comments to IBM, you grant IBM a nonexclusive right to use or distribute your comments in any way it believes appropriate without incurring any obligation to you.
Address
___________________________________________________________________________________________________
Tape do not Fold and _ _ _ _ _ _ _Fold _ _ _and ___ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _Please _____ __ _ _ staple _____________________________ ___ _ _ Tape ______ NO POSTAGE NECESSARY IF MAILED IN THE UNITED STATES
_________________________________________________________________________________________ Please do not staple Fold and Tape Fold and Tape
GI11-6712-00
Printed in USA
GI11-6712-00