web/clearquest/cqd/index.php

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
   2    "http://www.w3.org/TR/html4/strict.dtd">
   3 <html>
   4 <head>
   5   <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
   6   <meta name="GENERATOR" content="Mozilla/4.61 [en] (Win98; U) [Netscape]">
   7
   8    <title>ClearSCM: Clearquest: Daemon</title>
   9
  10   <link rel="stylesheet" type="text/css" media="screen" href="/css/Article.css">
  11   <link rel="stylesheet" type="text/css" media="screen" href="/css/Code.css">
  12   <link rel="stylesheet" type="text/css" media="print"  href="/css/Print.css">
  13   <link rel="SHORTCUT ICON" href="http://clearscm.com/favicon.ico" type="image/png">
  14
  15   <!-- Google Analytics
  16   <script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
  17   </script>
  18   <script type="text/javascript">
  19     _uacct = "UA-89317-1";
  20     urchinTracker ();
  21   </script>
  22   Google Analytics -->
  23
  24   <?php
  25   include "clearscm.php";
  26   menu_css ();
  27   ?>
  28 </head>
  29
  30 <body id="homepage">
  31 <?php heading ();?>
  32
  33 <div id="page">
  34   <div id="content">
  35     <?php start_box ("cs3");?>
  36       <h2>Clearquest Daemon</h2>
  37     <?php end_box ();?>
  38
  39   <h3>Overview</h3>
  40
  41   <p>At a previous company I was asked to provide a mechanism for
  42   <i>controlled checkins</i> of code into release branches. It was
  43   decided not to use <font class="standout">Rational's UCM
  44   Model</font> since the company was small and it's needs were
  45   simple. Additionally the company wanted to be able to produce
  46   <i>Release Notes</i> depicting which bugs were fixed in the release
  47   in an automated fashion. They did not want to incur significant
  48   overhead when checking in code and wanted to tightly control which
  49   bugs went into which release branch.</p>
  50
  51   <?php start_box ("cs2");?>
  52     <b>Problem Statement:</b> Provide a mechanism for <u>controlled
  53     checkins</u> and a way to automate Release Notes for releases.
  54   <?php end_box ();?>
  55
  56   <h3>Environment</h3>
  57
  58   <p>The environment of this company was as follows:</p>
  59
  60   <ul>
  61     <li>Small company - ~30 Engineers in Santa Clara, USA and ~20 in
  62     Shanghai, China</li>
  63
  64     <li>All Windows shop</li>
  65
  66     <li>Rational Clearcase LT</li>
  67
  68     <li>Rational Clearquest</li>
  69
  70     <li>Rational Multisite</li>
  71
  72     <li>One main server serving both Clearcase and Clearquest</li>
  73
  74     <li>Slow VPN WAN to Shanghai</li>
  75   </ul>
  76
  77   <p>Multisite and the Shanhai office were not initially rolled out
  78   but the design considered them nonetheless. Unfortunately
  79   Multisiting of the Clearquest database was ruled out as too
  80   expensive for our little startup company.</p>
  81
  82   <h3>Requirements</h3>
  83
  84   <p>The requirements for this Clearcase/Clearquest integration were as follows:
  85
  86   <ul>
  87     <li>Verify that all elements checked into a release branch were associated with
  88     a Clearquest defect intended for that release.</li>
  89
  90     <li>Verify the defect was:
  91
  92     <ul>
  93       <li>Owned</li>
  94
  95       <li>Only in certain states (Must be in <font class="standout">Assigned</font>
  96       or <font class="standout">Resolved</font>).</li>
  97
  98       <li>On <i>the list</i> of defects for this release.</li>
  99
 100       <li>Different release branches will have different <i>lists</i>.</li>
 101     </ul>
 102
 103     <li>Allow for some branches to not require a defect number while
 104     those releases were in a state of "development".</li>
 105
 106     <li>Defect numbers will be entered by the engineers as part of the
 107     comment. This process should allow multiple defect numbers per
 108     checkin.</li>
 109
 110     <li>Provide a way to lock out checkins of defects for building.</li>
 111
 112     <li>Provide a way to generate Release Notes for a release based on
 113     the defects fixed.</li>
 114
 115   </ul>
 116
 117   <h3>Assumptions</h3>
 118
 119   <p>There were certain assumptions and other processes already put into place
 120   that assisted in the solution.</p>
 121
 122   <ul>
 123     <li>All checkins that required a bug ID would have a label applied to them
 124     that consisted of the bug ID.</li>
 125
 126     <li>When engineers were done checking in these labels would be locked so
 127     that further checkins for this bug were stopped.</li>
 128
 129     <li>Engineers would be allowed to continue to work on the release branch
 130     while the release was building</li>
 131   </ul>
 132
 133   <h3>Check In Trigger</h3>
 134
 135   <ul>
 136     <li><i>Controlled checkins</i> would be done through a check in
 137     trigger that would make sure that the conditions were right to
 138     allow checkin to proceed.</li>
 139
 140     <li>In order to retrieve data from Clearquest CQPerl was used.</li>
 141
 142     <li>Initial testing of this trigger showed that it took a very
 143     long time to connect to the Clearquest database only to retrieve a
 144     bit of information. If many elements were to be checked in the
 145     opening and closing of the database made the checkins take
 146     a long time!
 147
 148     <li>Our sister lab in Shanghai, China would also participate in
 149     this process therefore the trigger must also must minimize wait
 150     time over the WAN.</li>
 151
 152   </ul>
 153
 154   <p>A better method was needed<blink>...</blink></p>
 155
 156   <img src="BeforeCQD.jpg" border=0>
 157
 158   <h3>Daemon</h3>
 159
 160   <ul>
 161     <li>In order to minimize database open/close times a daemon was
 162     developed that would hold the Clearquest database open and respond
 163     to requests for information through a socket.</li>
 164
 165     <li>The daemon would return information about a bug ID to the
 166     caller. This drastically sped up the process for the Checkin
 167     Trigger.</li>
 168
 169     <li>Additionally this general purpose daemon could be used in
 170     other ways (e.g. Web Page Based Release Notes).</li>
 171   </ul>
 172
 173   <img src="CQD.jpg" border=0>
 174
 175   <h3>CQPerl Problems</h3>
 176
 177   <p>A good daemon process:</p>
 178
 179   <ul>
 180     <li>Puts itself into <i>Daemon mode</i></li>
 181
 182     <li>Is <font class="standout">Multithreaded</font>. This means
 183     that it responds to a request and forks a child process off to
 184     handle the request so that the parent process can accept the next
 185     client.</li>
 186   </ul>
 187
 188   <p>Since, at the time, CQPerl was the only supported way to
 189   interface with Clearquest it had to be used. Because CQPerl is based
 190   off of ActiveState Perl a number of problems arose:</p>
 191
 192   <ol>
 193     <li>ActiveState Perl does <b>not</b> support calling <font
 194     class="standout">setsid</font> which is required to enter
 195     <i>Daemon mode</i>.</li>
 196
 197     <li>ActiveState Perl does not reliably handle signals. This mean
 198     that the parent process could not reliably catch <font
 199     class="standout">SIGCLD</font> deaths</li>
 200   </ol>
 201
 202   <p>As a result the Clearquest Daemon Process is <font
 203   class="standout">not</font> multithreaded. Since the company
 204   is small and requests relatively infrequent this was an acceptable
 205   limitation. Still when processing large lists of Release Notes and
 206   over the WAN the service would, at times, be unavailable.</p>
 207
 208   <h3>SetSID</h3>
 209
 210   <p>The question remained then, <b>How does one go into daemon mode?</b></p>
 211
 212   <p>Here I resorted to using something that the company was already
 213   using - <a href="http://cygwin.com">Cygwin</a>.</p>
 214
 215   <p>Cygwin is a Linux emulation running under Windows. It is one of
 216   the most complete emulations I have found. We used it to build
 217   (gnumake) as well as many other things.</p>
 218
 219   <p>Cygwin has a program called cygrunsrv which allows you to
 220   daemonize any other process.</p>
 221
 222   <h3>Multithreading</h3>
 223
 224   <p>The problem with making the server multithreaded was harder to
 225   resolve. Code was written to perform multithreading but the
 226   unreliability of signal handling proved to be a problem that could
 227   not be easily overcome.</p>
 228
 229   <p>Options for a multithreading included:</p>
 230
 231   <ul>
 232     <li>Figure out how to handle signals properly under ActiveState
 233     Perl. Research was done on ActiveState's forums and eventually the
 234     engineer for ActiveState Perl said that signals just can't be
 235     reliably done under Windows.</li>
 236
 237     <li>Rewrite code into another language. The client/server could
 238     have been rewritten into another language that supported
 239     multithreading however much work had already been done on the
 240     daemon and a few clients, also written in Perl, would need to also
 241     be rewritten or interfaced to this other language</li>
 242   </ul>
 243
 244
 245   <p>In the end it was decided since the demand on the server would not
 246   be that great, that a single threaded server would suffice.</p>
 247
 248   <h3>Client/Server</h3>
 249
 250   <?php start_box ("cs3");?>
 251     <b>In depth:</b> Code listings for <a href="cqd.php">CQD
 252     Daemon</a>, <a href="cqc.php">CQC Client</a> and <a
 253     href="cqc.pm.php">cqc.pm</a>
 254   <?php end_box ();?>
 255
 256   <p>Since this is a client server application the <a href="cqd.php">CQD Daemon</a>
 257    was written as well as a <a href="cqc.php">CQC Client</a>. A Perl module named
 258    <a href="cqc.pm.php">cqc.pm</a> was made to define the API for CDQ.</p>
 259
 260   <p>The test client, CQC, ended up being a useful command line tool
 261   to get information about a bug from Clearquest. A user could, for
 262   example, obtain the owner of a bug by simply doing:</p>
 263
 264   <div class="code"><pre>
 265     $ cqc 1234 owner
 266     swang
 267     $ cqc 1322 owner headline
 268     owner: jliu
 269     headline: Unable to modify ACLS that are created (observed during ACL tests)
 270     $
 271   </pre></div>
 272
 273   <h3>Trigger</h3>
 274
 275   <?php start_box ("cs3");?>
 276     <b>In depth:</b> Code listing for <a href="CheckinPreop.php">Check
 277     in Trigger</a>.
 278   <?php end_box ();?>
 279
 280   <p>A preop <i>Checkin Trigger</i> was created to:</p>
 281
 282   <ul>
 283     <li>Make sure that a comment was specified</li>
 284
 285     <li>Extract all bug IDs from the comment</li>
 286
 287     <li>If the check in was on a release branch requiring bug ID checkin then
 288     the trigger would make sure:</li>
 289
 290       <ul>
 291         <li>The bug ID existed in Clearquest, was owned and in the
 292         proper state.</li>
 293
 294         <li>The bug ID label was not locked.</li>
 295
 296         <li>The bug ID was listed in a file for that release branch
 297         (i.e. &lt;release branch&gt;.lst)</li>
 298       </ul>
 299     </ul>
 300
 301   <p>A postop <i>Checkin Trigger</i> would then create labels for the
 302   bug IDs and apply those labels to the checked in elements.</p>
 303
 304   <h3>Release Notes</h3>
 305
 306   <?php start_box ("cs3");?>
 307     <b>In depth:</b> Code listing for <a href="rn.php">Releasenote CGI
 308     Script</a>.
 309   <?php end_box ();?>
 310
 311   <p>With the Clearquest Daemon satisifying requests and with the
 312   Checkin Trigger already relying on a flat file of bug IDs for a
 313   release, generating a web page of release notes merely involved some
 314   ordinary formatting of a web page and a calling of the daemon to
 315   supply Clearquest information in a tabular format.</p>
 316
 317   <p>Additionally web pages were created to allow addition of bug IDs
 318   to the release list</p>
 319
 320   <p>Since CQD returns all fields in the defect record a web page
 321   showing all details of a defect was also developed</p>
 322
 323   <p>And example of Release notes is shown <a
 324   href="Releasenotes.html">here</a>.</p>
 325
 326 </div>
 327
 328   <?php copyright ();?>
 329 </div>
 330
 331 <script language="JavaScript" src="/JavaScript/Menus.js" type="text/javascript"></script>
 332
 333 </body>
 334 </html>