Process documentation
Writing description documents
A description document captures a requirement for an enhancement for TPTP. None of the information is of the design/architecture type; it is simply a sufficiently detailed explanation of the requirement. Description documents are used to gauge the idea behind the requirement, to weigh requirements against each other for balancing resources, and to act as input for the "What's new in TPTP" document that is released with every TPTP version.

Contents of a Description Document
The description document follows the format set out in the enhancement template. The description document must provide the following:
  1. The file must be named hf_bugID.html, e.g. hf_54312.html. Note that the extension must be "html", not "htm" because if it's .htm then the link to the bugzilla on the generated enhancement page will be broken.
  2. A brief but complete description. As a rule of thumb, when the PMC goes to create the "What's new in this release" document, would the description be enough to explain the enhancement? Most descriptions are at least a paragraph long, and the description must be more than a duplicate of the bugzilla's summary.
  3. A sizing describing, in person days or person weeks, the amount of work involved in implementing the enhancement. Even if some of the work will be done in parallel, this sizing must reflect the total amount of work, not the amount of weeks that it will take under parallel development. Assume the worst-case scenario: something unexpected may happen and one person may end up doing all of the work for the feature.
  4. A complete sizing that takes into account all of the work required, from design, to code, test, doc, and ship. Note that the sizing includes EVERYTHING that's needed, for example, include the time
    • for all testing, not just unit test; the testing done during the test pass should be included in this sizing.
    • to externalize strings for translation.
    • needed for documentation to be reviewed.
    • for learning
    • ... and so on ...
    Read the Checklist for enhancements for suggestions of work items that should be factored into the sizing.

Link the description document to the bugzilla
In bugzilla there is a URL tag as shown in this example: https://bugs.eclipse.org/bugs/show_bug.cgi?id=109892
Fill in the bugzilla with the URL to the description document:
  1. Copy and paste this URL into the URL field.
    http://eclipse.org/tptp/groups/Architecture/documents/features/hf_109892.html
    
  2. Adjust the name of the file to match the name of your description document.

CVS Repository Commit Information
host: dev.eclipse.org
repository path: /cvsroot/org.eclipse

Use extssh to expand the www folder and check out the tptp/groups/Architecture/documents/features folder.
Description docs should be checked into the features directory.

If you're unfamiliar with the Eclipse CVS interface, read the Check out the TPTP web site from CVS document for an explanation of how to check out the folder.