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>
12 <h2>Identification</h2>
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.
18 <EMBED SRC="system-overview.shtml">
20 <h2>Document Overview</h2>
22 <p>This configuration management document is organized into the
27 <li>2 - References</li>
28 <li>3 - File Management</li>
29 <li>4 - Trouble Report Processing</li>
30 <li>5 - Software Releases</li>
32 <li>B - Coding Requirements</li>
35 <EMBED SRC="references.shtml">
37 <h1>File Management</h1>
39 <h2>Directory Structure</h2>
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
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
54 <h2>Configuration Management</h2>
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
61 <p>Documentation on the CVS software is included with the
62 whitepaper, "CVS II: Parallelizing Software Development".
64 <h1>Trouble Report Processing</h1>
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:
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>
79 <p>Trouble reports shall be processed using the following steps.
81 <h2>Classification</h2>
83 <p>When a trouble report is received it must be classified at
84 one of the following priority levels:
88 <li>Request for enhancement, e.g. asking for a
91 <li>Low, e.g. a documentation error or undocumented
94 <li>Moderate, e.g. unable to print a file or unable to
95 compile the software</li>
97 <li>High, e.g. unable to print to a printer or key
98 functionality not working</li>
100 <li>Critical, e.g. unable to print at all</li>
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
109 <p>The scope of the problem should also be determined as:
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>
117 <h2>Identification</h2>
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.
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).
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.
136 <h2>Notification</h2>
138 <p>The user or vendor is notified when the fix is available or
139 if the problem was caused by user error.
141 <h1>Software Releases</h1>
143 <h2>Version Numbering</h2>
145 <p>CUPS uses a three-part version number separated by periods to
146 represent the major, minor, and patch release numbers:
153 <p>Beta-test releases are indentified by appending the letter B
154 followed by the build number:
157 MAJOR.MINOR.PATCHbBUILD
161 <p>Release candidates are indentified by appending the letters
162 RC followed by the build number:
165 MAJOR.MINOR.PATCHrcBUILD
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:
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:
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
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>
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>
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:
225 <center><TABLE BORDER="1">
249 <td>First release candidate</td>
254 <td>Second release candidate</td>
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>
267 <h3>Beta Releases</h3>
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>
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>
279 <h3>Release Candidates</h3>
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.
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.
294 <h3>Production Releases</h3>
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.
300 <EMBED SRC="glossary.shtml">
302 <h1>Coding Requirements</h1>
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.
310 <h2>Source Files</h2>
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".
320 <h3>Documentation</h3>
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 "$Id$" tag:
332 * Description of file contents.
334 * Copyright 1997-2005 by Easy Software Products, all rights
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:
344 * Attn: CUPS Licensing Information
345 * Easy Software Products
346 * 44141 Airport View Drive, Suite 204
347 * Hollywood, Maryland 20636 USA
349 * Voice: (301) 373-9600
350 * EMail: cups-info@cups.org
351 * WWW: http://www.cups.org
355 * function1() - Description 1.
356 * function2() - Description 2.
357 * function3() - Description 3.
362 <p>For source files that are subject to the Apple OS-Developed Software
363 exception, the following additional comment should appear after the
367 * This file is subject to the Apple OS-Developed Software exception.
370 <p>The bottom of each source file shall contain a trailer giving
371 the name of the file using the CVS "$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
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",
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.)
396 <h3>Documentation</h3>
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
405 * 'do_this()' - Compute y = this(x).
410 static float /* O - Inverse power value, 0.0 <= y <= 1.1 */
411 do_this(float x) /* I - Power value (0.0 <= x <= 1.1) */
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
427 <p>Methods shall be in lowercase with underscores between words
428 ("do_this", "do_that", "do_something_else", etc.)
430 <h3>Documentation</h3>
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
439 * 'class::do_this()' - Compute y = this(x).
444 float /* O - Inverse power value, 0.0 <= y <= 1.0 */
445 class::do_this(float x) /* I - Power value (0.0 <= x <= 1.0) */
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
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.
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".
473 <h3>Documentation</h3>
475 <p>Each variable shall be declared on a separate line and shall
476 be immediately followed by a comment block describing the
480 int this_variable; /* The current state of this */
481 int that_variable; /* The current state of that */
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",
492 <h3>Documentation</h3>
494 <p>Each type shall have a comment block immediately before the
499 * This type is for CUPS foobar options.
501 typedef int cups_this_type_t;
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.)
512 <h3>Documentation</h3>
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:
520 * This structure is for CUPS foobar options.
522 struct cups_this_struct_str
524 int this_member; /* Current state for this */
525 int that_member; /* Current state for that */
533 <p>All class names shall be lowercase with underscores between
534 words ("this_class", "that_class", etc.)
536 <h3>Documentation</h3>
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:
544 * This class is for CUPS foobar options.
546 class cups_this_class
548 int this_member; /* Current state for this */
549 int that_member; /* Current state for that */
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",
563 <p>Typed enumerations shall be used whenever possible to allow
564 for type checking by the compiler.
566 <h3>Documentation</h3>
568 <p>Comment blocks shall immediately follow each constant:
573 CUPS_THIS_TRAY, /* This tray */
574 CUPS_THAT_TRAY /* That tray */
580 <h3>Documentation</h3>
582 <p>All source code shall utilize block comments within functions
583 to describe the operations being performed by a group of
588 * Clear the state array before we begin...
591 for (i = 0; i < (sizeof(array) / sizeof(sizeof(array[0])); i ++)
592 array[i] = STATE_IDLE;
595 * Wait for state changes...
600 for (i = 0; i < (sizeof(array) / sizeof(sizeof(array[0])); i ++)
601 if (array[i] != STATE_IDLE)
604 if (i == (sizeof(array) / sizeof(array[0])))
606 } while (i == (sizeof(array) / sizeof(array[0])));
611 <h4 type='a'>Indentation</h4>
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:
621 int i; /* Looping var */
624 * Process foobar values from 0 to 999...
627 for (i = 0; i < 1000; i ++)
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"
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.
659 <h4>Return Values</h4>
661 <p>Parenthesis shall surround values returned from a function
670 <p>Whenever convenient loops should count downward to zero to
671 improve program performance:
674 for (i = sizeof(array) / sizeof(array[0]) - 1; i >= 0; i --)
675 array[i] = STATE_IDLE;
678 <h1 align='right'>Software Trouble Report Form</h1>
680 <center><table width="80%">
682 <th align='right'>Summary of Problem:</th>
683 <td colspan='2'>_____________________________________________</td>
685 <tr><td colspan='3'> </td></tr>
687 <th align='right' ROWSPAN="5" valign='top'>Problem Severity:</th>
689 <td>Request for enhancement, e.g. asking for a
694 <td>Low, e.g. a documentation error or undocumented
699 <td>Moderate, e.g. unable to print a file or unable to
700 compile the software</td>
704 <td>High, e.g. unable to print to a printer or key
705 functionality not working</td>
709 <td>Critical, e.g. unable to print at all</td>
711 <tr><td colspan='3'> </td></tr>
713 <th align='right' rowspan='3' valign='top'>Problem Scope:</th>
715 <td>Machine or printer</td>
719 <td>Operating System</td>
723 <td>All machines, printers, or operating systems</td>
725 <tr><td colspan='3'> </td></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>