doc/cmp.shtml

   1 <html>
   2 <HEAD>
   3         <META NAME="DOCNUMBER" CONTENT="CUPS-CMP-1.2">
   4         <META NAME="COPYRIGHT" CONTENT="Copyright 1997-2005, 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 <p>This configuration management plan document provides the
  15 guidelines for development and maintenance of the Common UNIX
  16 Printing System ("CUPS") Version 1.2 software.
  17
  18 <EMBED SRC="system-overview.shtml">
  19
  20 <h2>Document Overview</h2>
  21
  22 <p>This configuration management document is organized into the
  23 following 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 <p>Each source file shall be placed a sub-directory
  42 corresponding to the software sub-system it belongs to
  43 ("scheduler", "cups", etc.) To remain compatible with older UNIX
  44 filesystems, directory names shall not exceed 16 characters in
  45 length.
  46
  47 <h2>Source Files</h2>
  48
  49 <p>Source files shall be documented and formatted as described
  50 in Appendix B, Coding Requirements. To remain compatible with
  51 older UNIX filesystems, source file names shall not exceed 16
  52 characters in length.
  53
  54 <h2>Configuration Management</h2>
  55
  56 <p>Source files shall be placed under the control of the
  57 Concurrent Versions System ("CVS") software. Source files shall
  58 be "checked in" with each change so that modifications can be
  59 tracked.
  60
  61 <p>Documentation on the CVS software is included with the
  62 whitepaper, "CVS II: Parallelizing Software Development".
  63
  64 <h1>Trouble Report Processing</h1>
  65
  66 <p>A Software Trouble Report ("STR") shall be submitted every
  67 time a user or vendor experiences a problem with the CUPS
  68 software. Trouble reports are maintained in a database with one
  69 of the following states:
  70
  71 <ol>
  72         <li>STR is closed with complete resolution</li>
  73         <li>STR is closed without resolution</li>
  74         <li>STR is active, waiting on information from submitter</li>
  75         <li>STR is pending with additional information from submitter</li>
  76         <li>STR is newly submitted</li>
  77 </ol>
  78
  79 <p>Trouble reports shall be processed using the following steps.
  80
  81 <h2>Classification</h2>
  82
  83 <p>When a trouble report is received it must be classified at
  84 one of the following priority levels:
  85
  86 <ol>
  87
  88         <li>Request for enhancement, e.g. asking for a
  89         feature</li>
  90
  91         <li>Low, e.g. a documentation error or undocumented
  92         side-effect</li>
  93
  94         <li>Moderate, e.g. unable to print a file or unable to
  95         compile the software</li>
  96
  97         <li>High, e.g. unable to print to a printer or key
  98         functionality not working</li>
  99
 100         <li>Critical, e.g. unable to print at all</li>
 101
 102 </ol>
 103
 104 <p>Level 4 and 5 trouble reports must be resolved in the next
 105 software release. Level 1 to 3 trouble reports are scheduled for
 106 resolution in a specific release at the discretion of the
 107 release coordinator.
 108
 109 <p>The scope of the problem should also be determined as:
 110
 111 <ol>
 112         <li>Specific to a machine or printer</li>
 113         <li>Specific to an operating system</li>
 114         <li>Applies to all machines, printers, and operating systems</li>
 115 </ol>
 116
 117 <h2>Identification</h2>
 118
 119 <p>Once the level and scope of the trouble report is determined
 120 the software sub-system(s) involved with the problem are
 121 determined. This may involve additional communication with the
 122 user or vendor to isolate the problem to a specific cause.
 123
 124 <p>When the sub-system(s) involved have been identified, an
 125 engineer will then determine the change(s) needed and estimate
 126 the time required for the change(s).
 127
 128 <h2>Correction</h2>
 129
 130 <p>Corrections are scheduled based upon the severity and
 131 complexity of the problem. Once all changes have been made,
 132 documented, and tested successfully a new software release
 133 snapshot is generated. Additional tests are added as necessary
 134 for proper testing of the changes.
 135
 136 <h2>Notification</h2>
 137
 138 <p>The user or vendor is notified when the fix is available or
 139 if the problem was caused by user error.
 140
 141 <h1>Software Releases</h1>
 142
 143 <h2>Version Numbering</h2>
 144
 145 <p>CUPS uses a three-part version number separated by periods to
 146 represent the major, minor, and patch release numbers:
 147
 148 <pre>
 149     MAJOR.MINOR.PATCH
 150     1.1.0
 151 </pre>
 152
 153 <p>Beta-test releases are indentified by appending the letter B
 154 followed by the build number:
 155
 156 <pre>
 157     MAJOR.MINOR.PATCHbBUILD
 158     1.1.0b1
 159 </pre>
 160
 161 <p>Release candidates are indentified by appending the letters
 162 RC followed by the build number:
 163
 164 <pre>
 165     MAJOR.MINOR.PATCHrcBUILD
 166     1.1.0rc1
 167 </pre>
 168
 169 <p>A CVS snapshot is generated for every beta and final release
 170 and uses the version number preceded by the letter "v" and with
 171 the decimal points replaced by underscores:
 172
 173 <pre>
 174     v1_1_0b1
 175     v1_1_0rc1
 176     v1_1_0
 177 </pre>
 178
 179 <p>Each change that corrects a fault in a software sub-system
 180 increments the patch release number. If a change affects the
 181 overall software design of CUPS then the minor release number
 182 will be incremented and the patch release number reset to 0. If
 183 CUPS is completely redesigned the major release number will be
 184 incremented and the minor and patch release numbers reset to 0:
 185
 186 <pre>
 187     1.1.0b1    First beta release
 188     1.1.0b2    Second beta release
 189     1.1.0rc1   First release candidate
 190     1.1.0rc2   Second release candidate
 191     1.1.0      First production release
 192     1.1.1b1    First beta of 1.1.1
 193     1.1.1rc1   First release candidate of 1.1.1
 194     1.1.1      Production release of 1.1.1
 195     1.1.2b1    First beta of 1.1.2
 196     1.1.2rc1   First release candidate of 1.1.2
 197     1.1.2      Production release of 1.1.2
 198     2.0.0b1    First beta of 2.0.0
 199     2.0.0rc1   First release candidate of 2.0.0
 200     2.0.0      Production release of 2.0.0
 201 </pre>
 202
 203 <h2>Generation</h2>
 204
 205 <p>Software releases shall be generated for each successfully
 206 completed software trouble report. All object and executable
 207 files shall be deleted prior to performing a full build to
 208 ensure that source files are recompiled.</p>
 209
 210 <h2>Testing</h2>
 211
 212 <p>Software testing shall be conducted according to the CUPS
 213 Software Test Plan, CUPS-STP-1.1. Failed tests cause STRs to be
 214 generated to correct the problems found.</p>
 215
 216 <h2>Releases</h2>
 217
 218 <p>When testing has been completed successfully a new
 219 distribution image is created from the current CVS code
 220 "snapshot". No release shall contain software that has not
 221 passed the appropriate software tests. Three types of releases
 222 are used, beta, release candidate, and production, and are
 223 released using the following basic schedule:
 224
 225 <center><TABLE BORDER="1">
 226 <tr>
 227         <th>Week</th>
 228         <th>Version</th>
 229         <th>Description</th>
 230 </tr>
 231 <tr>
 232         <td>T-6 weeks</td>
 233         <td>1.1.0b1</td>
 234         <td>First beta</td>
 235 </tr>
 236 <tr>
 237         <td>T-5 weeks</td>
 238         <td>1.1.0b2</td>
 239         <td>Second beta</td>
 240 </tr>
 241 <tr>
 242         <td>T-4 weeks</td>
 243         <td>1.1.0b3</td>
 244         <td>Third beta</td>
 245 </tr>
 246 <tr>
 247         <td>T-3 weeks</td>
 248         <td>1.1.0rc1</td>
 249         <td>First release candidate</td>
 250 </tr>
 251 <tr>
 252         <td>T-2 weeks</td>
 253         <td>1.1.0rc2</td>
 254         <td>Second release candidate</td>
 255 </tr>
 256 <tr>
 257         <td>T-0 weeks</td>
 258         <td>1.1.0</td>
 259         <td>Production</td>
 260 </tr>
 261 </table></center>
 262
 263 <p>Beta releases are typically used prior to new major and minor
 264 version releases. At least one release candidate is generated
 265 prior to each production release.</p>
 266
 267 <h3>Beta Releases</h3>
 268
 269 <p>Beta releases are generated when substantial changes have
 270 been made that may affect the reliability of the software. Beta
 271 releases may cause loss of data, functionality, or services and
 272 are provided for testing by qualified individuals.</p>
 273
 274 <p>Beta releases are an OPTIONAL part of the release process and
 275 are generated as deemed appropriate by the release coordinator.
 276 Functional changes may be included in subsequent beta releases
 277 until the first release candidate.</p>
 278
 279 <h3>Release Candidates</h3>
 280
 281 <p>Release candidates are generated at least two weeks prior to
 282 a production release. Release candidates are targeted for
 283 end-users that wish to test new functionality or bug fixes prior
 284 to the production release. While release candidates are intended
 285 to be substantially bug-free, they may still contain defects
 286 and/or not compile on specific platforms.
 287
 288 <p>At least one release candidate is REQUIRED prior to any
 289 production release. The distribution of a release candidate
 290 marks the end of any functional improvements. Release candidates
 291 are generated at weekly intervals until all level 4/5 trouble
 292 reports are resolved.
 293
 294 <h3>Production Releases</h3>
 295
 296 <p>Production releases are generated after a successful release
 297 candidate and represent a stable release of the software
 298 suitable for all users.
 299
 300 <EMBED SRC="glossary.shtml">
 301
 302 <h1>Coding Requirements</h1>
 303
 304 <p>These coding requirements provide detailed information on
 305 source file formatting and documentation content. These
 306 guidelines shall be applied to all C and C++ source files
 307 provided with CUPS. Source code for other languages should
 308 conform to these requirements as allowed by the language.
 309
 310 <h2>Source Files</h2>
 311
 312 <h3>Naming</h3>
 313
 314 <p>All source files names shall be 16 characters or less in
 315 length to ensure compatibility with older UNIX filesystems.
 316 Source files containing functions shall have an extension of
 317 ".c" for ANSI C and ".cxx" for C++ source files. All other
 318 "include" files shall have an extension of ".h".
 319
 320 <h3>Documentation</h3>
 321
 322 <p>The top of each source file shall contain a header giving the
 323 name of the file, the purpose or nature of the source file, the
 324 copyright and licensing notice, and the functions contained in
 325 the file.  The file name and revision information is provided by
 326 the CVS "&#36;Id$" tag:
 327
 328 <pre>
 329     /*
 330      * "&#36;Id$"
 331      *
 332      *   Description of file contents.
 333      *
 334      *   Copyright 1997-2005 by Easy Software Products, all rights
 335      *   reserved.
 336      *
 337      *   These coded instructions, statements, and computer programs are
 338      *   the property of Easy Software Products and are protected by
 339      *   Federal copyright law.  Distribution and use rights are outlined
 340      *   in the file "LICENSE.txt" which should have been included with
 341      *   this file.  If this file is missing or damaged please contact
 342      *   Easy Software Products at:
 343      *
 344      *       Attn: CUPS Licensing Information
 345      *       Easy Software Products
 346      *       44141 Airport View Drive, Suite 204
 347      *       Hollywood, Maryland 20636 USA
 348      *
 349      *       Voice: (301) 373-9600
 350      *       EMail: cups-info@cups.org
 351      *         WWW: http://www.cups.org
 352      *
 353      * Contents:
 354      *
 355      *   function1() - Description 1.
 356      *   function2() - Description 2.
 357      *   function3() - Description 3.
 358      */
 359 </pre>
 360
 361 <!-- NEED 1in -->
 362 <p>For source files that are subject to the Apple OS-Developed Software
 363 exception, the following additional comment should appear after the
 364 contact information:
 365
 366 <pre>
 367      *   This file is subject to the Apple OS-Developed Software exception.
 368 </pre>
 369
 370 <p>The bottom of each source file shall contain a trailer giving
 371 the name of the file using the CVS "&#36;Id$" tag. The primary
 372 purpose of this is to mark the end of a source file; if the
 373 trailer is missing it is possible that code has been lost near
 374 the end of the file:
 375
 376 <pre>
 377     /*
 378      * End of "&#36;Id$".
 379      */
 380 </pre>
 381
 382 <h2>Functions</h2>
 383
 384 <h3>Naming</h3>
 385
 386 <p>Functions with a global scope shall be capitalized ("DoThis",
 387 "DoThat", "DoSomethingElse", etc.) The only exception to this
 388 rule shall be the CUPS interface library functions which may
 389 begin with a prefix word in lowercase ("cupsDoThis",
 390 "cupsDoThat", etc.)
 391
 392 <p>Functions with a local scope shall be declared "static" and
 393 be lowercase with underscores between words ("do_this",
 394 "do_that", "do_something_else", etc.)
 395
 396 <h3>Documentation</h3>
 397
 398 <p>Each function shall begin with a comment header describing
 399 what the function does, the possible input limits (if any), and
 400 the possible output values (if any), and any special information
 401 needed:
 402
 403 <pre>
 404     /*
 405      * 'do_this()' - Compute y = this(x).
 406      *
 407      * Notes: none.
 408      */
 409
 410     static float     /* O - Inverse power value, 0.0 &lt;= y &lt;= 1.1 */
 411     do_this(float x) /* I - Power value (0.0 &lt;= x &lt;= 1.1) */
 412     {
 413       ...
 414       return (y);
 415     }
 416 </pre>
 417
 418 <p>Return/output values are indicated using an "O" prefix, input
 419 values are indicated using the "I" prefix, and values that are
 420 both input and output use the "IO" prefix for the corresponding
 421 in-line comment.
 422
 423 <h2>Methods</h2>
 424
 425 <h3>Naming</h3>
 426
 427 <p>Methods shall be in lowercase with underscores between words
 428 ("do_this", "do_that", "do_something_else", etc.)
 429
 430 <h3>Documentation</h3>
 431
 432 <p>Each method shall begin with a comment header describing what
 433 the method does, the possible input limits (if any), and the
 434 possible output values (if any), and any special information
 435 needed:
 436
 437 <pre>
 438     /*
 439      * 'class::do_this()' - Compute y = this(x).
 440      *
 441      * Notes: none.
 442      */
 443
 444     float                   /* O - Inverse power value, 0.0 &lt;= y &lt;= 1.0 */
 445     class::do_this(float x) /* I - Power value (0.0 &lt;= x &lt;= 1.0) */
 446     {
 447       ...
 448       return (y);
 449     }
 450 </pre>
 451
 452 <p>Return/output values are indicated using an "O" prefix, input
 453 values are indicated using the "I" prefix, and values that are
 454 both input and output use the "IO" prefix for the corresponding
 455 in-line comment.
 456
 457 <h2>Variables</h2>
 458
 459 <h3>Naming</h3>
 460
 461 <p>Variables with a global scope shall be capitalized
 462 ("ThisVariable", "ThatVariable", "ThisStateVariable", etc.) The
 463 only exception to this rule shall be the CUPS interface library
 464 global variables which must begin with the prefix "cups"
 465 ("cupsThisVariable", "cupsThatVariable", etc.) Global variables
 466 shall be replaced by function arguments whenever possible.
 467
 468 <p>Variables with a local scope shall be lowercase with
 469 underscores between words ("this_variable", "that_variable",
 470 etc.) Any local variables shared by functions within a source
 471 file shall be declared "static".
 472
 473 <h3>Documentation</h3>
 474
 475 <p>Each variable shall be declared on a separate line and shall
 476 be immediately followed by a comment block describing the
 477 variable:
 478
 479 <pre>
 480     int this_variable;   /* The current state of this */
 481     int that_variable;   /* The current state of that */
 482 </pre>
 483
 484 <h2>Types</h2>
 485
 486 <h3>Naming</h3>
 487
 488 <p>All type names shall be lowercase with underscores between
 489 words and "_t" appended to the end of the name ("this_type_t",
 490 "that_type_t", etc.)
 491
 492 <h3>Documentation</h3>
 493
 494 <p>Each type shall have a comment block immediately before the
 495 typedef:
 496
 497 <pre>
 498     /*
 499      * This type is for CUPS foobar options.
 500      */
 501     typedef int cups_this_type_t;
 502 </pre>
 503
 504 <h2>Structures</h2>
 505
 506 <h3>Naming</h3>
 507
 508 <p>All structure names shall be lowercase with underscores
 509 between words and "_str" appended to the end of the name
 510 ("this_struct_str", "that_struct_str", etc.)
 511
 512 <h3>Documentation</h3>
 513
 514 <p>Each structure shall have a comment block immediately before
 515 the struct and each member shall be documented in accordance
 516 with the variable naming policy above:
 517
 518 <pre>
 519     /*
 520      * This structure is for CUPS foobar options.
 521      */
 522     struct cups_this_struct_str
 523     {
 524       int this_member;   /* Current state for this */
 525       int that_member;   /* Current state for that */
 526     };
 527 </pre>
 528
 529 <h2>Classes</h2>
 530
 531 <h3>Naming</h3>
 532
 533 <p>All class names shall be lowercase with underscores between
 534 words ("this_class", "that_class", etc.)
 535
 536 <h3>Documentation</h3>
 537
 538 <p>Each class shall have a comment block immediately before the
 539 class and each member shall be documented in accordance with the
 540 variable naming policy above:
 541
 542 <pre>
 543     /*
 544      * This class is for CUPS foobar options.
 545      */
 546     class cups_this_class
 547     {
 548       int this_member;   /* Current state for this */
 549       int that_member;   /* Current state for that */
 550     };
 551 </pre>
 552
 553 <h2>Constants</h2>
 554
 555 <h3>Naming</h3>
 556
 557 <p>All constant names shall be uppercase with underscored
 558 between words ("THIS_CONSTANT", "THAT_CONSTANT", etc.) Constants
 559 defined for the CUPS interface library must begin with an
 560 uppercase prefix ("CUPS_THIS_CONSTANT", "CUPS_THAT_CONSTANT",
 561 etc.)
 562
 563 <p>Typed enumerations shall be used whenever possible to allow
 564 for type checking by the compiler.
 565
 566 <h3>Documentation</h3>
 567
 568 <p>Comment blocks shall immediately follow each constant:
 569
 570 <pre>
 571     enum
 572     {
 573       CUPS_THIS_TRAY,   /* This tray */
 574       CUPS_THAT_TRAY    /* That tray */
 575     };
 576 </pre>
 577
 578 <h2>Code</h2>
 579
 580 <h3>Documentation</h3>
 581
 582 <p>All source code shall utilize block comments within functions
 583 to describe the operations being performed by a group of
 584 statements:
 585
 586 <pre>
 587     /*
 588      * Clear the state array before we begin...
 589      */
 590
 591     for (i = 0; i &lt; (sizeof(array) / sizeof(sizeof(array[0])); i ++)
 592       array[i] = STATE_IDLE;
 593
 594     /*
 595      * Wait for state changes...
 596      */
 597
 598     do
 599     {
 600       for (i = 0; i &lt; (sizeof(array) / sizeof(sizeof(array[0])); i ++)
 601         if (array[i] != STATE_IDLE)
 602           break;
 603
 604       if (i == (sizeof(array) / sizeof(array[0])))
 605         sleep(1);
 606     } while (i == (sizeof(array) / sizeof(array[0])));
 607 </pre>
 608
 609 <h3>Style</h3>
 610
 611 <h4 type='a'>Indentation</h4>
 612
 613 <p>All code blocks enclosed by brackets shall begin with the
 614 opening brace on a new line. The code then follows starting on a
 615 new line after the brace and is indented 2 spaces. The closing
 616 brace is then placed on a new line following the code at the
 617 original indentation:
 618
 619 <pre>
 620     {
 621       int i; /* Looping var */
 622
 623      /*
 624       * Process foobar values from 0 to 999...
 625       */
 626
 627       for (i = 0; i &lt; 1000; i ++)
 628       {
 629         do_this(i);
 630         do_that(i);
 631       }
 632     }
 633 </pre>
 634
 635 <p>Single-line statements following "do", "else", "for", "if",
 636 and "while" shall be indented 2 spaces as well. Blocks of code
 637 in a "switch" block shall be indented 4 spaces after each "case"
 638 and "default" case:
 639
 640 <pre>
 641     switch (array[i])
 642     {
 643       case STATE_IDLE :
 644           do_this(i);
 645           do_that(i);
 646           break;
 647       default :
 648           do_nothing(i);
 649           break;
 650     }
 651 </pre>
 652
 653 <h4>Spacing</h4>
 654
 655 <p>A space shall follow each reserved word ("if", "while", etc.)
 656 Spaces shall not be inserted between a function name and the
 657 arguments in parenthesis.
 658
 659 <h4>Return Values</h4>
 660
 661 <p>Parenthesis shall surround values returned from a function
 662 using "return":
 663
 664 <pre>
 665     return (STATE_IDLE);
 666 </pre>
 667
 668 <h4>Loops</h4>
 669
 670 <p>Whenever convenient loops should count downward to zero to
 671 improve program performance:
 672
 673 <pre>
 674     for (i = sizeof(array) / sizeof(array[0]) - 1; i >= 0; i --)
 675       array[i] = STATE_IDLE;
 676 </pre>
 677
 678 <h1 align='right'>Software Trouble Report Form</h1>
 679
 680 <center><table width="80%">
 681 <tr>
 682         <th align='right'>Summary of Problem:</th>
 683         <td colspan='2'>_____________________________________________</td>
 684 </tr>
 685 <tr><td colspan='3'>&nbsp;</td></tr>
 686 <tr>
 687         <th align='right' ROWSPAN="5" valign='top'>Problem Severity:</th>
 688         <td>__1</td>
 689         <td>Request for enhancement, e.g. asking for a
 690         feature</td>
 691 </tr>
 692 <tr>
 693         <td>__2</td>
 694         <td>Low, e.g. a documentation error or undocumented
 695         side-effect</td>
 696 </tr>
 697 <tr>
 698         <td>__3</td>
 699         <td>Moderate, e.g. unable to print a file or unable to
 700         compile the software</td>
 701 </tr>
 702 <tr>
 703         <td>__4</td>
 704         <td>High, e.g. unable to print to a printer or key
 705         functionality not working</td>
 706 </tr>
 707 <tr>
 708         <td>__5</td>
 709         <td>Critical, e.g. unable to print at all</td>
 710 </tr>
 711 <tr><td colspan='3'>&nbsp;</td></tr>
 712 <tr>
 713         <th align='right' rowspan='3' valign='top'>Problem Scope:</th>
 714         <td>__1</td>
 715         <td>Machine or printer</td>
 716 </tr>
 717 <tr>
 718         <td>__2</td>
 719         <td>Operating System</td>
 720 </tr>
 721 <tr>
 722         <td>__3</td>
 723         <td>All machines, printers, or operating systems</td>
 724 </tr>
 725 <tr><td colspan='3'>&nbsp;</td></tr>
 726 <tr>
 727         <th align='right' valign='top'>Detailed Description of Problem:</th>
 728         <td colspan='2'>_____________________________________________
 729         <br />_____________________________________________
 730         <br />_____________________________________________
 731         <br />_____________________________________________
 732         <br />_____________________________________________</td>
 733 </tr>
 734 </table></center>
 735
 736 </body>
 737 </html>