doc/cmp.shtml

   1 <HTML>
   2 <HEAD>
   3         <META NAME="DOCNUMBER" CONTENT="CUPS-CMP-1.1">
   4         <META NAME="COPYRIGHT" CONTENT="Copyright 1997-2001, All Rights Reserved">
   5         <META NAME="Author" CONTENT="Easy Software Products">
   6         <TITLE>CUPS Configuration Management Plan</TITLE>
   7 </HEAD>
   8 <BODY>
   9
  10 <H1>Scope</H1>
  11
  12 <H2>Identification</H2>
  13
  14 This configuration management plan document provides the guidelines for
  15 development and maintenance of the Common UNIX Printing System ("CUPS")
  16 Version 1.1 software.
  17
  18 <EMBED SRC="system-overview.shtml">
  19
  20 <H2>Document Overview</H2>
  21
  22 This configuration management document is organized into the following
  23 sections:
  24
  25 <UL>
  26         <LI>1 - Scope</LI>
  27         <LI>2 - References</LI>
  28         <LI>3 - File Management</LI>
  29         <LI>4 - Trouble Report Processing</LI>
  30         <LI>5 - Software Releases</LI>
  31         <LI>A - Glossary</LI>
  32         <LI>B - Coding Requirements</LI>
  33 </UL>
  34
  35 <EMBED SRC="references.shtml">
  36
  37 <H1>File Management</H1>
  38
  39 <H2>Directory Structure</H2>
  40
  41 Each source file shall be placed a sub-directory corresponding to the software
  42 sub-system it belongs to ("scheduler", "cups", etc.) To remain compatible
  43 with older UNIX filesystems, directory names shall not exceed 16 characters
  44 in length.
  45
  46 <H2>Source Files</H2>
  47
  48 Source files shall be documented and formatted as described in Appendix
  49 B, Coding Requirements.
  50
  51 <H2>Configuration Management</H2>
  52
  53 Source files shall be placed under the control of the Concurrent Versions
  54 System ("CVS") software. Source files shall be "checked in" with each change
  55 so that modifications can be tracked.
  56
  57 <P>Documentation on the CVS software is included with the whitepaper, "CVS
  58 II: Parallelizing Software Development".
  59
  60 <H1>Trouble Report Processing</H1>
  61
  62 A Software Trouble Report ("STR") shall be submitted every time a user
  63 or vendor experiences a problem with the CUPS software. Trouble reports
  64 are maintained in a database with one of the following states:
  65
  66 <OL>
  67         <LI>STR is closed with complete resolution</LI>
  68         <LI>STR is closed without resolution</LI>
  69         <LI>STR is active</LI>
  70         <LI>STR is pending (new STR or additional information available)</LI>
  71 </OL>
  72
  73 Trouble reports shall be processed using the following steps.
  74
  75 <H2>Classification</H2>
  76
  77 When a trouble report is received it must be classified at one of the following
  78 levels:
  79
  80 <OL>
  81         <LI>Request for enhancement</LI>
  82         <LI>Documentation error</LI>
  83         <LI>Unable to print a file</LI>
  84         <LI>Unable to print to a printer</LI>
  85         <LI>Unable to print at all</LI>
  86 </OL>
  87
  88 The scope of the problem should also be determined as:
  89
  90 <OL>
  91         <LI>Specific to a machine</LI>
  92         <LI>Specific to an operating system</LI>
  93         <LI>Applies to all machines and operating systems</LI>
  94 </OL>
  95
  96 <H2>Identification</H2>
  97
  98 Once the level and scope of the trouble report is determined the software
  99 sub-system(s) involved with the problem are determined. This may involve
 100 additional communication with the user or vendor to isolate the problem
 101 to a specific cause.
 102
 103 <P>When the sub-system(s) involved have been identified, an engineer will
 104 then determine the change(s) needed and estimate the time required for
 105 the change(s).
 106
 107 <H2>Correction</H2>
 108
 109 Corrections are scheduled based upon the severity and complexity of the
 110 problem. Once all changes have been made, documented, and tested successfully
 111 a new software release snapshot is generated. Additional tests are added
 112 as necessary for proper testing of the changes.
 113
 114 <H2>Notification</H2>
 115
 116 The user or vendor is notified when the fix is available or if the problem
 117 was caused by user error.
 118
 119 <H1>Software Releases</H1>
 120
 121 <H2>Version Numbering</H2>
 122
 123 CUPS uses a three-part version number separated by periods to represent
 124 the major, minor, and patch release numbers:
 125
 126 <UL>
 127 <PRE>
 128 major.minor.patch
 129 1.1.0
 130 </PRE>
 131 </UL>
 132
 133 Beta-test releases are indentified by appending the letter B followed by
 134 the build number:
 135
 136 <UL>
 137 <PRE>
 138 major.minor.patchbbuild
 139 1.1.0b1
 140 </PRE>
 141 </UL>
 142
 143 A CVS snapshot is generated for every beta and final release and uses
 144 the version number preceded by the letter "v" and with the decimal
 145 points replaced by underscores:
 146
 147 <UL>
 148 <PRE>
 149 v1_0_0b1
 150 v1_0_0
 151 </PRE>
 152 </UL>
 153
 154 Each change that corrects a fault in a software sub-system increments the
 155 patch release number. If a change affects the software design of CUPS then
 156 the minor release number will be incremented and the patch release number
 157 reset to 0. If CUPS is completely redesigned the major release number will
 158 be incremented and the minor and patch release numbers reset to 0:
 159
 160 <UL>
 161 <PRE>
 162 1.1.0b1    First beta release
 163 1.1.0b2    Second beta release
 164 1.1.0      First production release
 165 1.1.1b1    First beta of 1.1.1
 166 1.1.1      Production release of 1.1.1
 167 1.1.1b1    First beta of 1.1.1
 168 1.1.1      Production release of 1.1.1
 169 2.0.0b1    First beta of 2.0.0
 170 2.0.0      Production release of 2.0.0
 171 </PRE>
 172 </UL>
 173
 174 <H2>Generation</H2>
 175
 176 Software releases shall be generated for each successfully completed software
 177 trouble report. All object and executable files shall be deleted prior
 178 to performing a full build to ensure that source files are recompiled.
 179
 180 <H2>Testing</H2>
 181
 182 Software testing shall be conducted according to the CUPS Software Test
 183 Plan, CUPS-STP-1.1. Failed tests cause STRs to be generated to correct
 184 the problems found.
 185
 186 <H2>Release</H2>
 187
 188 When testing has been completed successfully a new distribution image is
 189 created from the current CVS code "snapshot". No production release shall
 190 contain software that has not passed the appropriate software tests.
 191
 192 <EMBED SRC="glossary.shtml">
 193
 194 <H1>Coding Requirements</H1>
 195
 196 These coding requirements provide detailed information on source file
 197 formatting and documentation content. These guidelines shall be applied
 198 to all C and C++ source files provided with CUPS.
 199
 200 <H2>Source Files</H2>
 201
 202 <H3>Naming</H3>
 203
 204 All source files names shall be 16 characters or less in length to
 205 ensure compatibility with older UNIX filesystems. Source files
 206 containing functions shall have an extension of ".c" for ANSI C and
 207 ".cxx" for C++ source files. All other "include" files shall have an
 208 extension of ".h".
 209
 210 <H3>Documentation</H3>
 211
 212 The top of each source file shall contain a header giving the name of the
 213 file, the purpose or nature of the source file, the copyright and licensing
 214 notice, and the functions contained in the file.  The file name and revision
 215 information is provided by the CVS "&#36;Id$" tag:
 216
 217 <UL>
 218 <PRE>
 219 /*
 220  * "&#36;Id$"
 221  *
 222  *   Description of file contents.
 223  *
 224  *   Copyright 1997-2001 by Easy Software Products, all rights
 225  *   reserved.
 226  *
 227  *   These coded instructions, statements, and computer programs are
 228  *   the property of Easy Software Products and are protected by
 229  *   Federal copyright law.  Distribution and use rights are outlined
 230  *   in the file "LICENSE.txt" which should have been included with
 231  *   this file.  If this file is missing or damaged please contact
 232  *   Easy Software Products at:
 233  *
 234  *       Attn: CUPS Licensing Information
 235  *       Easy Software Products
 236  *       44141 Airport View Drive, Suite 204
 237  *       Hollywood, Maryland 20636-3111 USA
 238  *
 239  *       Voice: (301) 373-9600
 240  *       EMail: cups-info@cups.org
 241  *         WWW: http://www.cups.org
 242  *
 243  * Contents:
 244  *
 245  *   function1() - Description 1.
 246  *   function2() - Description 2.
 247  *   function3() - Description 3.
 248  */
 249 </PRE>
 250 </UL>
 251
 252 The bottom of each source file shall contain a trailer giving the name
 253 of the file using the CVS "&#36;Id$" tag. The primary purpose of this is to
 254 mark the end of a source file; if the trailer is missing it is possible
 255 that code has been lost near the end of the file:
 256
 257 <UL>
 258 <PRE>
 259 /*
 260  * End of "&#36;Id$".
 261  */
 262 </PRE>
 263 </UL>
 264
 265 <H2>Functions</H2>
 266
 267 <H3>Naming</H3>
 268
 269 Functions with a global scope shall be capitalized ("DoThis", "DoThat",
 270 "DoSomethingElse", etc.) The only exception to this rule shall be the
 271 CUPS interface library functions which may begin with a prefix word in
 272 lowercase ("cupsDoThis", "cupsDoThat", etc.)
 273
 274 <P>Functions with a local scope shall be declared "static" and be lowercase
 275 with underscores between words ("do_this", "do_that", "do_something_else",
 276 etc.)
 277
 278 <H3>Documentation</H3>
 279
 280 Each function shall begin with a comment header describing what the function
 281 does, the possible input limits (if any), and the possible output values
 282 (if any), and any special information needed:
 283
 284 <UL>
 285 <PRE>
 286 /*
 287  * 'do_this()' - Compute y = this(x).
 288  *
 289  * Notes: none.
 290  */
 291
 292 static float     /* O - Inverse power value, 0.0 &lt;= y &lt;= 1.1 */
 293 do_this(float x) /* I - Power value (0.0 &lt;= x &lt;= 1.1) */
 294 {
 295   ...
 296   return (y);
 297 }
 298 </PRE>
 299 </UL>
 300
 301 <H2>Methods</H2>
 302
 303 <H3>Naming</H3>
 304
 305 Methods shall be in lowercase with underscores between words ("do_this",
 306 "do_that", "do_something_else", etc.)
 307
 308 <H3>Documentation</H3>
 309
 310 Each method shall begin with a comment header describing what the method
 311 does, the possible input limits (if any), and the possible output values
 312 (if any), and any special information needed:
 313
 314 <UL>
 315 <PRE>
 316 /*
 317  * 'class::do_this()' - Compute y = this(x).
 318  *
 319  * Notes: none.
 320  */
 321
 322 float                   /* O - Inverse power value, 0.0 &lt;= y &lt;= 1.0 */
 323 class::do_this(float x) /* I - Power value (0.0 &lt;= x &lt;= 1.0) */
 324 {
 325   ...
 326   return (y);
 327 }
 328 </PRE>
 329 </UL>
 330
 331 <H2>Variables</H2>
 332
 333 <H3>Naming</H3>
 334
 335 Variables with a global scope shall be capitalized ("ThisVariable",
 336 "ThatVariable", "ThisStateVariable", etc.) The only exception to this
 337 rule shall be the CUPS interface library global variables which must
 338 begin with the prefix "cups" ("cupsThisVariable", "cupsThatVariable",
 339 etc.) Global variables shall be replaced by function arguments whenever
 340 possible.
 341
 342 <P>Variables with a local scope shall be lowercase with underscores between
 343 words ("this_variable", "that_variable", etc.) Any local variables shared
 344 by functions within a source file shall be declared "static".
 345
 346 <H3>Documentation</H3>
 347
 348 Each variable shall be declared on a separate line and shall be immediately
 349 followed by a comment block describing the variable:
 350
 351 <UL><PRE>
 352 int this_variable;   /* The current state of this */
 353 int that_variable;   /* The current state of that */
 354 </PRE></UL>
 355
 356 <H2>Types</H2>
 357
 358 <H3>Naming</H3>
 359
 360 All type names shall be lowercase with underscores between words and
 361 "_t" appended to the end of the name ("this_type_t", "that_type_t",
 362 etc.)
 363
 364 <H3>Documentation</H3>
 365
 366 Each type shall have a comment block immediately before the typedef:
 367
 368 <UL>
 369 <PRE>
 370 /*
 371  * This type is for CUPS foobar options.
 372  */
 373 typedef int cups_this_type_t;
 374 </PRE>
 375 </UL>
 376
 377 <H2>Structures</H2>
 378
 379 <H3>Naming</H3>
 380
 381 All structure names shall be lowercase with underscores between words and
 382 "_str" appended to the end of the name ("this_struct_str", "that_struct_str",
 383 etc.)
 384
 385 <H3>Documentation</H3>
 386
 387 Each structure shall have a comment block immediately before the struct
 388 and each member shall be documented in accordance with the variable naming
 389 policy above:
 390
 391 <UL>
 392 <PRE>
 393 /*
 394  * This structure is for CUPS foobar options.
 395  */
 396 struct cups_this_struct_str
 397 {
 398   int this_member;   /* Current state for this */
 399   int that_member;   /* Current state for that */
 400 };
 401 </PRE>
 402 </UL>
 403
 404 <H2>Classes</H2>
 405
 406 <H3>Naming</H3>
 407
 408 All class names shall be lowercase with underscores between words
 409 ("this_class", "that_class", etc.)
 410
 411 <H3>Documentation</H3>
 412
 413 Each class shall have a comment block immediately before the class
 414 and each member shall be documented in accordance with the variable naming
 415 policy above:
 416
 417 <UL>
 418 <PRE>
 419 /*
 420  * This class is for CUPS foobar options.
 421  */
 422 class cups_this_class
 423 {
 424   int this_member;   /* Current state for this */
 425   int that_member;   /* Current state for that */
 426 };
 427 </PRE>
 428 </UL>
 429
 430 <H2>Constants</H2>
 431
 432 <H3>Naming</H3>
 433
 434 All constant names shall be uppercase with underscored between words
 435 ("THIS_CONSTANT", "THAT_CONSTANT", etc.) Constants defined for the CUPS
 436 interface library must begin with an uppercase prefix
 437 ("CUPS_THIS_CONSTANT", "CUPS_THAT_CONSTANT", etc.)
 438
 439 <P>Typed enumerations shall be used whenever possible to allow for type
 440 checking by the compiler.
 441
 442 <H3>Documentation</H3>
 443
 444 Comment blocks shall immediately follow each constant:
 445
 446 <UL>
 447 <PRE>
 448 enum
 449 {
 450   CUPS_THIS_TRAY,   /* This tray */
 451   CUPS_THAT_TRAY    /* That tray */
 452 };
 453 </PRE>
 454 </UL>
 455
 456 <H2>Code</H2>
 457
 458 <H3>Documentation</H3>
 459
 460 All source code shall utilize block comments within functions to describe
 461 the operations being performed by a group of statements:
 462
 463 <UL>
 464 <PRE>
 465 /*
 466  * Clear the state array before we begin...
 467  */
 468
 469 for (i = 0; i &lt; (sizeof(array) / sizeof(sizeof(array[0])); i ++)
 470   array[i] = STATE_IDLE;
 471
 472 /*
 473  * Wait for state changes...
 474  */
 475
 476 do
 477 {
 478   for (i = 0; i &lt; (sizeof(array) / sizeof(sizeof(array[0])); i ++)
 479     if (array[i] != STATE_IDLE)
 480       break;
 481
 482   if (i == (sizeof(array) / sizeof(array[0])))
 483     sleep(1);
 484 } while (i == (sizeof(array) / sizeof(array[0])));
 485 </PRE>
 486 </UL>
 487
 488 <H3>Style</H3>
 489
 490 <H4 TYPE="a">Indentation</H4>
 491
 492 All code blocks enclosed by brackets shall begin with the opening brace
 493 on a new line. The code then follows starting on a new line after the brace
 494 and is indented 2 spaces. The closing brace is then placed on a new line
 495 following the code at the original indentation:
 496
 497 <UL>
 498 <PRE>
 499 {
 500   int i; /* Looping var */
 501
 502  /*
 503   * Process foobar values from 0 to 999...
 504   */
 505
 506   for (i = 0; i &lt; 1000; i ++)
 507   {
 508     do_this(i);
 509     do_that(i);
 510   }
 511 }
 512 </PRE>
 513 </UL>
 514
 515 Single-line statements following "do", "else", "for", "if", and "while"
 516 shall be indented 2 spaces as well. Blocks of code in a "switch" block
 517 shall be indented 4 spaces after each "case" and "default" case:
 518
 519 <UL>
 520 <PRE>
 521 switch (array[i])
 522 {
 523   case STATE_IDLE :
 524       do_this(i);
 525       do_that(i);
 526       break;
 527   default :
 528       do_nothing(i);
 529       break;
 530 }
 531 </PRE>
 532 </UL>
 533
 534 <H4>Spacing</H4>
 535
 536 A space shall follow each reserved word ("if", "while", etc.) Spaces shall
 537 not be inserted between a function name and the arguments in parenthesis.
 538
 539 <H4>Return Values</H4>
 540
 541 Parenthesis shall surround values returned from a function using "return":
 542
 543 <UL>
 544 <PRE>
 545 return (STATE_IDLE);
 546 </PRE>
 547 </UL>
 548
 549 <H4>Loops</H4>
 550
 551 Whenever convenient loops should count downward to zero to improve program
 552 performance:
 553
 554 <UL>
 555 <PRE>
 556 for (i = sizeof(array) / sizeof(array[0]) - 1; i >= 0; i --)
 557   array[i] = STATE_IDLE;
 558 </PRE>
 559 </UL>
 560
 561 <H1 ALIGN=RIGHT>Software Trouble Report Form</H1>
 562
 563 <CENTER><TABLE WIDTH="80%">
 564 <TR>
 565         <TH ALIGN=RIGHT>Summary of Problem:</TH>
 566         <TD ALIGN=LEFT>________________________________________</TD>
 567 </TR>
 568
 569 <TR>
 570         <TH ALIGN=RIGHT>Problem Severity:</TH>
 571         <TD ALIGN=LEFT>__1=RFE
 572         <BR>__2=Documentation-Error
 573         <BR>__3=Unable-to-Print-a-File
 574         <BR>__4=Unable-to-Print-to-a-Printer
 575         <BR>__5=Unable-to-Print-at-All</TD>
 576 </TR>
 577
 578 <TR>
 579         <TH ALIGN=RIGHT>Problem Scope:</TH>
 580         <TD ALIGN=LEFT>__1=Machine __2=Operating-System __3=All</TD>
 581 </TR>
 582
 583 <TR>
 584         <TH ALIGN=RIGHT VALIGN=TOP>Detailed Description of Problem:</TH>
 585         <TD ALIGN=LEFT>________________________________________
 586         <BR>________________________________________
 587         <BR>________________________________________
 588         <BR>________________________________________
 589         <BR>________________________________________
 590         <BR>________________________________________</TD>
 591 </TR>
 592 </TABLE></CENTER>
 593
 594 </BODY>
 595 </HTML>