Last Modified: February 18, 2008

The HTMLDOC configuration management plan defines how releases are done, how bugs and feature requests are handled, and how the HTMLDOC code is formatted and documented. This plan is based upon the policies we have developed over the years for our other software projects and has been tailored to HTMLDOC.

This document is organized into the following sections:

• File Management
• Bug & Feature Request Processing
• Software Releases
• Coding Requirements
• Secure Programming

File Management

Directory Structure

Each source file shall be placed a sub-directory corresponding to the software sub-system it belongs to ("doc", "htmldoc", etc.) To remain compatible with older UNIX filesystems, directory names shall not exceed 16 characters in length.

Source Files

Source files shall be documented and formatted as described in Coding Requirements. To remain compatible with older UNIX filesystems, source file names shall not exceed 16 characters in length, including extension.

Configuration Management

Source files shall be placed under the control of the Subversion ("SVN") software. Source files shall be "checked in" with each change so that modifications can be tracked.

Documentation on the SVN software is available in the on-line and hardcopy book, "Version Control with Subversion".

The SVN repository URLs are:

    http://svn.easysw.com/public/htmldoc/

    https://svn.easysw.com/public/htmldoc/

HTMLDOC developers must use the https URL and authenticate using their corresponding username and password.

The SVN repository is organized as follows:

/public/htmldoc/trunk

The current version of HTMLDOC

/public/htmldoc/branches/branch-major.minor

Branches of previous versions of HTMLDOC, used when generating patch releases

/public/htmldoc/tags/release-major.minor.patch

Copies of each released version of HTMLDOC

Bug & Feature Request Processing

A Software Trouble Report ("STR") shall be filed every time a user or vendor experiences a problem with or wants a new feature in the HTMLDOC software. Trouble reports are maintained in a database with one of the following states:

1. STR is closed with complete resolution
2. STR is closed without resolution
3. STR is active
4. STR is pending
5. STR is new

Trouble reports shall be processed using the following steps:

1. Classification
2. Identification
3. Correction
4. Notification

1. Classification

When a trouble report is received it must be classified at one of the following priority levels:

1. Request for enhancement, e.g. asking for a feature
2. Low, e.g. a documentation error or undocumented side-effect
3. Moderate, e.g. unable to convert a file or unable to compile the software
4. High, e.g. key functionality not working
5. Critical, e.g. software crashes with all inputs or contains a security vulnerability that leads to unauthorized remote access

Level 4 and 5 trouble reports must be resolved in the next software release. Level 1 to 3 trouble reports are scheduled for resolution in a specific release at the discretion of the release coordinator.

The scope of the problem must also be determined as:

1. Specific to a machine
2. Specific to an operating system
3. Applies to all machines and operating systems

2. Identification

Once the level and scope of the trouble report is determined the software sub-system(s) involved with the problem are determined. This may involve additional communication with the user or vendor to isolate the problem to a specific cause.

When the sub-system(s) involved have been identified, an engineer will then determine the change(s) needed and estimate the time required for the change(s).

3. Correction

Corrections are scheduled based upon the severity and complexity of the problem. Once all changes have been made, documented, and tested successfully a new software release snapshot is generated. Additional tests are added as necessary for proper testing of the changes.

4. Notification

The user or vendor is notified when the fix is available or if the problem was caused by user error.

Software Releases

There are two types of software releases: feature releases and patch releases. Feature releases implement new features as defined in priority 1 (request for enhancement) STRs. Patch releases implement bug fixes as defined in priority 2-5 STRs.

Version Numbering

HTMLDOC uses a three-part version number separated by periods to represent the major, minor, and patch release numbers; patch release number 0 denotes a feature release:

    MAJOR.MINOR.PATCH
    1.8.24 (patch release)
    1.9.0 (minor feature release)
    1.9.1 (patch release)
    1.10.0 (minor feature release)
    2.0.0 (major feature release)

Beta-test releases may be created before feature releases and are indentified by appending the letter B followed by the build number:

    MAJOR.MINOR.PATCHbBUILD
    1.9.0b1
    1.9.0b2
    2.0.0b1

Release candidates are created before feature releases and are indentified by appending the letters RC followed by the build number:

    MAJOR.MINOR.PATCHrcBUILD
    1.9.0rc1
    2.0.0rc1
    2.0.0rc2

Patch releases are only issued to correct priority 2-5 STRs. Minor feature releases are created when a priority 1 STR requires only minor changes to the software. Major feature releases are created when a priority 1 STR requires a redesign.

Generation

Software patch releases shall be generated for each successfully completed priority 2-5 STR. All object and executable files shall be deleted prior to performing a full build to ensure that source files can be recompiled successfully.

Testing

Software testing shall be conducted according to the HTMLDOC Software Test Plan (TBD). Failed tests cause STRs to be generated to correct the problems found.

Releases

When testing has been completed successfully a new distribution image is created from the current SVN code "snapshot". No release shall contain software that has not passed the appropriate software tests. Patch releases are distributed immediately upon successful completion of the software tests.

Feature releases are distributed only after a period of public testing. Public testing optionally begins with one or more beta distributions followed by at least one release candidate, distributed using the following basic schedule:

A SVN copy to the /tags directory is generated for every release and uses the version number, for example:

    svn copy https://svn.easysw.com/public/htmldoc/branches/1.8 \
        https://svn.easysw.com/public/htmldoc/tags/release-1.8.24 \
        -m "1.8.24 release by Developer Name" ENTER

    svn copy https://svn.easysw.com/public/htmldoc/trunk \
        https://svn.easysw.com/public/htmldoc/tags/release-1.9.0b1 \
        -m "1.9.0b1 release by Developer Name" ENTER

Beta Distributions

Beta distributions are generated when substantial changes have been made that may affect the reliability of the software. Beta distributions may cause loss of data, functionality, or services and are provided for testing by qualified individuals.

Beta distributions are an OPTIONAL part of the release process and are generated as deemed appropriate by the release coordinator. Functional and design changes may be included in subsequent beta releases until the first release candidate.

Release Candidates

Release candidates are generated at least two weeks prior to a feature release. Release candidates are targeted for end-users that wish to test new functionality or bug fixes prior to the feature release. While release candidates are intended to be substantially bug-free, they may still contain defects and/or not compile on specific platforms. No functional or design changes can be introduced in a release candidate.

At least one release candidate is REQUIRED prior to any feature release. The distribution of a release candidate marks the end of any functional improvements. Release candidates are generated at weekly intervals until all level 4/5 trouble reports are resolved. The last release candidate must be available for at least two weeks before the production feature release.

Feature Releases

Feature releases are generated after a successful release candidate and represent a stable release of the software suitable for all users.

Patch Releases

Patch releases are generated as needed to resolve STRs against a feature release and represent the latest stable release of the software suitable for all users. No functional or design changes can be introduced in a patch release.

Coding Requirements

These coding requirements provide detailed information on source file formatting and documentation content. These guidelines shall be applied to all C and C++ source files provided with HTMLDOC. Source code for other languages should conform to these requirements as allowed by the language.

Source Files

Naming

All source files names shall be 16 characters or less in length to ensure compatibility with older UNIX filesystems. Source files containing functions shall have an extension of ".c" for ANSI C and ".cxx" for C++ source files. All other "include" files shall have an extension of ".h".

Documentation

The top of each source file shall contain a header giving the name of the file, the purpose or nature of the source file, the copyright and licensing notice, and the functions contained in the file. The file name and revision information is provided by the SVN "$Id$" tag:

    /*
     * "$Id$"
     *
     *   Description of file contents.
     *
     *   Copyright 1997-2008 by Easy Software Products.
     *
     *   These coded instructions, statements, and computer programs are
     *   the property of Easy Software Products and are protected by
     *   Federal copyright law.  Distribution and use rights are outlined
     *   in the file "COPYING.txt" which should have been included with
     *   this file.  If this file is missing or damaged please contact
     *   Easy Software Products at:
     *
     *       Attn: HTMLDOC Licensing Information
     *       Easy Software Products
     *       516 Rio Grand Ct
     *       Morgan Hill, CA 95037 USA
     *
     *       http://www.htmldoc.org/
     *
     * Contents:
     *
     *   function1() - Description 1.
     *   function2() - Description 2.
     *   function3() - Description 3.
     */

The bottom of each source file shall contain a trailer giving the name of the file using the SVN "$Id$" tag. The primary purpose of this is to mark the end of a source file; if the trailer is missing it is possible that code has been lost near the end of the file:

    /*
     * End of "$Id$".
     */

Functions

Naming

Functions with a global scope shall be capitalized ("DoThis", "DoThat", "DoSomethingElse", etc.) The only exception to this rule shall be the HTMLDOC interface library functions which may begin with a prefix word in lowercase ("hdDoThis", "hdDoThat", etc.)

Functions with a local scope shall be declared "static" and be lowercase with underscores between words ("do_this", "do_that", "do_something_else", etc.)

Documentation

Each function shall begin with a comment header describing what the function does, the possible input limits (if any), and the possible output values (if any), and any special information needed:

    /*
     * 'do_this()' - Compute y = this(x).
     *
     * Notes: none.
     */

    static float     /* O - Inverse power value, 0.0 <= y <= 1.1 */
    do_this(float x) /* I - Power value (0.0 <= x <= 1.1) */
    {
      ...
      return (y);
    }

Return/output values are indicated using an "O" prefix, input values are indicated using the "I" prefix, and values that are both input and output use the "IO" prefix for the corresponding in-line comment.

Methods

Naming

Methods shall be in lowercase with underscores between words ("do_this", "do_that", "do_something_else", etc.)

Documentation

Each method shall begin with a comment header describing what the method does, the possible input limits (if any), and the possible output values (if any), and any special information needed:

    /*
     * 'class::do_this()' - Compute y = this(x).
     *
     * Notes: none.
     */

    float                   /* O - Inverse power value, 0.0 <= y <= 1.0 */
    class::do_this(float x) /* I - Power value (0.0 <= x <= 1.0) */
    {
      ...
      return (y);
    }

Return/output values are indicated using an "O" prefix, input values are indicated using the "I" prefix, and values that are both input and output use the "IO" prefix for the corresponding in-line comment.

Variables

Naming

Variables with a global scope shall be capitalized, for example "ThisVariable", "ThatVariable", "ThisStateVariable", etc. The only exception to this rule shall be the HTMLDOC interface library global variables which must begin with the prefix "hd", for example "hdThisVariable", "hdThatVariable", etc. Global variables shall be replaced by function arguments whenever possible.

Variables with a local scope shall be lowercase with underscores between words, for example "this_variable", "that_variable", etc. Any local variables shared by functions within a source file shall be declared "static".

Documentation

Each variable shall be declared on a separate line and shall be immediately followed by a comment block describing the variable:

    int this_variable;   /* The current state of this */
    int that_variable;   /* The current state of that */

Types

Naming

All type names shall be lowercase with underscores between words, a prefix of "hd", and a suffix of "_t", for example "hd_this_type_t", "hd_that_type_t", etc.

Documentation

Each type shall have a comment block immediately before the typedef:

    /*
     * This type is for HTMLDOC foobar options.
     */

    typedef int hd_this_type_t;

Structures

Naming

All public structure names shall be capitalized with the prefix "hd", for example "hdThisStruct", "hdThatStruct", etc. All private structure names shall be lowercase with underscores between words, a prefix of "hd", and a suffix of "_s", for example "hd_this_struct_s", "hd_that_struct_s", etc.

Documentation

Each structure shall have a comment block immediately before the struct and each member shall be documented in accordance with the variable naming policy above:

    /*
     * This structure is for HTMLDOC foobar options.
     */

    struct hd_this_struct_s
    {
      int this_member;   /* Current state for this */
      int that_member;   /* Current state for that */
    };

Classes

Naming

All public class names shall be capitalized with the prefix "hd", for example "hdThisClass", "hdThatClass", etc. All private class names shall be lowercase with underscores between words, a prefix of "hd", and a suffix of "_c", for example "hd_this_struct_c", "hd_that_struct_c", etc.

Documentation

Each class shall have a comment block immediately before the class and each member shall be documented in accordance with the variable naming policy above:

    /*
     * This class is for HTMLDOC foobar options.
     */

    class hdThisClass
    {
      int this_member;   /* Current state for this */
      int that_member;   /* Current state for that */
    };

Constants

Naming

All constant names shall be uppercase with underscores between words, for example "THIS_CONSTANT", "THAT_CONSTANT", etc. Constants defined for the HTMLDOC interface library must begin with an uppercase "HD" prefix, for example "HD_THIS_CONSTANT", "HD_THAT_CONSTANT", etc.

Typed enumerations shall be used whenever possible to allow for type checking by the compiler.

Documentation

Comment blocks shall immediately follow each constant:

    enum
    {
      HD_THIS_STYLE,   /* This style */
      HD_THAT_STYLE    /* That style */
    };

Code

Documentation

All source code shall utilize block comments within functions to describe the operations being performed by a group of statements:

    /*
     * Clear the state array before we begin...
     */

    for (i = (sizeof(array) / sizeof(sizeof(array[0])) - 1; i >= 0; i --)
      array[i] = STATE_IDLE;

    /*
     * Wait for state changes...
     */

    do
    {
      for (i = (sizeof(array) / sizeof(sizeof(array[0])) - 1; i >= 0; i --)
	if (array[i] != STATE_IDLE)
	  break;

      if (i >= 0)
	sleep(1);
    } while (i >= 0);

Style

Indentation

All code blocks enclosed by brackets shall begin with the opening brace on a new line. The code then follows starting on a new line after the brace and is indented two spaces. The closing brace is then placed on a new line following the code at the original indentation:

    {
      int i; /* Looping var */

     /*
      * Process foobar values from 0 to 999...
      */

      for (i = 0; i < 1000; i ++)
      {
	do_this(i);
	do_that(i);
      }
    }

Single-line statements following "do", "else", "for", "if", and "while" shall be indented two spaces as well. Blocks of code in a "switch" block shall be indented four spaces after each "case" and "default" case:

    switch (array[i])
    {
      case STATE_IDLE :
	  do_this(i);
	  do_that(i);
	  break;
      default :
	  do_nothing(i);
	  break;
    }

Spacing

A space shall follow each reserved word ("if", "while", etc.) Spaces shall not be inserted between a function name and the arguments in parenthesis.

Return Values

Parenthesis shall surround values returned from a function using "return":

    return (STATE_IDLE);

Loops

Whenever convenient loops should count downward to zero to improve program performance:

    for (i = sizeof(array) / sizeof(array[0]) - 1; i >= 0; i --)
      array[i] = STATE_IDLE;

Secure Programming

Secure programming practices shall be used at all times. The following basic guidelines shall be followed:

1. Write test code for all interfaces so that you can automate testing of the software and find errors sooner.
2. Use debugging tools such as Valgrind to find problems in your code.
3. Validate all input, including function parameters, data from files and sockets, and global variables. Most security errors are caused by a lack of input validation.
4. Test with invalid input whenever possible to ensure that invalid input is handled properly and consistently.
5. Define the behavior all interfaces so there is no undefined behavior or output for arbitrary, even erroneous, input. Programs and interfaces which have undefined behavior are broken and must be corrected.
6. Define interfaces for common tasks to isolate complexity, reduce code size, and promote testability.
7. Practice safe string manipulation using length-limited functions such as strlcat, strlcpy, and snprintf. Avoid using strcat, strcpy, strncat, and strncpy, and specify maximum string sizes in scanf formats.
8. Never use unsafe functions such as gets().
9. Allocate variable-size buffers instead of using fixed-size buffers whenever appropriate. Considerable memory savings and buffer overflow safety can be realized by allocating variable-length arrays and strings instead of storing them in large, fixed-size arrays.
10. Prefer reentrant functions over non-reentrant functions to ensure thread-safety and consistent behavior.
11. Initialize freed pointers to NULL to avoid references to freed memory.
12. Use memmove instead of memcpy when moving overlapping areas of memory.
13. Never use strcpy to remove characters from a string, as overlapping copies have undefined behavior.

The following secure programming sites offer valuable information as well:

• Secure Programming for Linux and Unix HOWTO; an interesting and in-depth book (free)
• SecureProgramming.com; An on-line resource for books and articles from O'Reilly Publishing