NAME

docs/pdds/pdd00_pdd.pod - Parrot Design Documents

ABSTRACT

This document defines the standard format for the Parrot Design Documents (PDDs) - the basic descriptions/plans for the design of Parrot.

DESCRIPTION

The original intent of the Parrot Design Documents (which themselves were initially Perl Design Documents) was threefold:

1. To provide a clear indication of the direction of current development (essentially, a road map from an abstract idea to a concrete implementation).
2. To act as a historical record of the rationale behind the decision, in order to provide context to future developers, who may not have been familiar with the original discussion.
3. To provide a historical, technical and cultural perspective for future development work. Re-implementation or even tangential tasks need only address what has changed since the original PDD.

Needless to say, things didn't work out this way. Some of the context discussed above is now documented in the *.dev documents (see the /docs/dev directory); much of it remains undocumented. The portions that have wound up being documented as PDDs are the basic design of the Parrot interpreter. In other words, the PDDs describe the features that the interpreter should implement. They should not discuss the details of the actual implementation (unless they absolutely have to) or the choices leading to that particular implementation; these are details that should go in the relevant *.dev file. On the other hand, they should detail the trade-offs made in the actual design.

IMPLEMENTATION

All newly created PDDs will adhere to the PDD standard current as of the time of proposal. An example of the currently accepted layout is given in docs/pdds/pdd_template.pod, which should be used as a template for any future PDDs.

FORMAT

All PDDs will be written in POD parseable by the current stable release of Perl. Although XML is a viable solution and has its vocal supporters, and although Parrot is intended to be used by many groups outside of the Perl community, we have chosen POD for its simplicity and ease of reading in plaintext form. Conversion to other formats (e.g. HTML) is encouraged, but the POD version should remain the master copy.

All PDDs will be written in English. British, American, or Other is the choice of the author. Translation to other languages, like all Perl documentation, is encouraged. (See "PDD TRANSLATIONS".)

All PDDs will contain the following information:

TITLE:

A short, general description of a specific part of the Parrot design. This may be a particular subsystem (e.g. the garbage collector), or a more general topic (e.g. basic Parrot datatypes).

VERSION:

Contains current and selected historical metadata on the PDD itself.

CURRENT:

Contains the following information, current as of the date of submission.

Maintainer

Required. The name and current email address for the point of contact for the PDD. This is the person to whom questions, comments, and patches should generally be addressed. This need not be the author of the document.

(In practice, non-trivial changes to the PDDs should probably be discussed on the perl6-internals mailing list before they take place).

Class

Required. The area of Parrot the PDD covers. This allows related PDDs to be logically grouped. The current list of valid classes is:

    Internals     - on the design of the Parrot interpreter
    Documentation - on Parrot documentation
    Meta          - on the Parrot project as an entity
    Testing       - on the testing of Parrot

It is expected that most PDDs will fit into a single class, but in principle a may belong to more than one class. However, peripheral excursions into the scope of another class should not warrant an actual classification (i.e. you shouldn't classify something as Testing simply because you happen to mention potential tests at one or two points in the text).

PDD Number

Required. No two PDDs should have the same number. PDD numbers are assigned by whoever commits the PDDs to the repository, subject to the approval of the Pumpking.

Version

Required. A one-up integer reflecting each public revision of a PDD. This reflects the version of the document itself, and not version of the standard the document may provide.

Status

Required. The current state of the PDD. Currently, the only classifications in use are Informational and Developing. We hope to eventually add Standard. All three are detailed below:

Informational

A PDD discussing possible design choices for a particular area of Parrot. This is non-prescriptive -- the final design may look nothing like the suggested one -- but provides a useful way to document detailed design concepts for later reference. For a good example, see /docs/pdds/pdd14_bignum.pod.

Developing

An acceptable (at least, in theory) PDD that needs further fleshing out and fine tuning. The PDD, as well as the implementation it describes, are both under official development by the Parrot development community.

Standard (Version #)

A frozen snapshot of the design as it applies to Parrot at a particular moment in time. The version number should reflect that version number of Parrot that the standard was first applied to. Developing PDDs are expected to eventually become standard.

Last Modified

Required. The date of the last submission.

PDD Format

Required. The specific PDD Standard that the PDD adheres to. This allows scripts to better parse PDDs of multiple aging formats. The format currently in use is PDD format 1.

Language

Optional. The language that the PDD is written in.

HISTORY:

A list of free-flow descriptions of significant metadata changes, such as status changes, or change of maintainers. Each entry should include the version, date, and nature of the change. This provides a quick historical overview of the major metadata changes of a PDD. This field is not to be used for a comprehensive list of alterations to the document.

CHANGES:

A summary of the changes since the last version. A comprehensive change log should be kept, but only within a supporting document.

ABSTRACT:

A quick blurb explaining the purpose of the PDD.

DESCRIPTION:

A description of the general nature of the PDD and how it relates to Parrot.

IMPLEMENTATION:

A major section of the PDD that encapsulates a free-form discussion of any and all applicable information related to the final observations, conclusions, and what-have-you that required writing the document in the first place.

ATTACHMENTS:

References to supporting files that should be considered part of the PDD. Text files and image files may be in any widely accepted format, which is rather subjective. Violators may be prosecuted.

Text files and image files should only provide supplemental information; no fair hiding all the info in an attachment just to not have to write an implementation section.

REFERENCES:

References to additional sources of information, but not those necessary for the PDD itself.

The PDD author may add any additional sections he or she wishes.

SUBMISSION CRITERIA

Proposed PDDs should be submitted to the perl6-internals mailing list (located at perl6-internals@perl.org) for discussion, criticism and general kibitzing. Acceptance of a particular PDD is ultimately up to the current Pumpking and/or the internals chief (a.k.a. Dan).

PDD TRANSLATIONS

Should a PDD be translated into another language, the following guidelines should be met.

• The Maintainer field should reflect who did the translation.
• The Version number should match the original document's Version number. Should multiple translated versions of a single original PDD be done (to correct spellings, etc.), the revision specific to that document version should be included in parentheses following the version number.
• Attributions in the HISTORY section should be left alone.

PDD STATUS CHANGES

Any change to the status of a particular PDD should be approved by the current Pumpking and/or the internals chief.

AVAILABILITY

All Informational, and Developing PDDs should be readily available, in a centralized location, to at least the current Parrot development circles. All Standard PDDs should be readily available, in a centralized location, to the general public.

ATTACHMENTS

None.

REFERENCES

Dan Sugalski's original PDD guidelines at http://www.mail-archive.com/perl6-internals@perl.org/msg01766.html

VERSION

CURRENT

    Maintainer: Simon Glover <scog@amnh.org>
    Class: Meta
    PDD Number: 0 
    Version: 2
    Status: Developing
    Last Modified:  20 February 2004
    PDD Format: 1
    Language: English

HISTORY

    v2 substantially rewritten on 20 Feb 2004 by Simon Glover
    v1 created on 7 Dec 2000 by BCWarnock <bwarnock@capita.com>
    v1 promoted to Developing as PDD 0 on 20 February 2001 by Dan Sugalski.

CHANGES

    Substantially rewritten to reflect what the PDDs actually are (rather
    than what we hoped they would be 3+ years ago).