Parrot Design Documents

Version

$Revision: 36833 $

Abstract

This document defines the content and format of Parrot Design Documents (PDDs).

Synopsis

Not applicable.

Description

PDDs are living documents, which should be maintained to reflect the current and contemplated design of Parrot.

The key aspects of Parrot's design are its interface to the outside world -- its feature set -- and its internal structure, both in code and in the broader project. Thus, PDDs describe Parrot's:

Codable interfaces: headers, functions, macros, file formats, etc.
Structural requirements that the implementation must obey: resource usage, portability, modularity, interdependency, etc.
Abstract models that the implementation expresses or conforms to. These models are in some sense meta-designs, because they provide guidance for the evolution of the current design.
More? - FIXME

PDDs don't generally discuss the implementation details. Low-level implementation documentation, the maintainer's guides, should go in the relevant docs/dev/*.pod file.

PDDs may document design trade-offs, i.e. the paths not chosen. In many cases they don't, just to keep the PDDs relatively short and readable. The history of Parrot's design is retrievable from the source repository.

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 5. 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 master version must be POD.

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

PDDs should be word-wrapped at column 78. For Emacs variants, this can be arranged by putting these lines at the end of the file, after "=cut":

Local Variables:
  fill-column:78
End:

See pdd_template.pod for the basic structure of a PDD. Notes on the sections:

name:

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:

Document version. Since Parrot is currently kept in a Subversion repository, the $$-delimited keyword "Revision" will do nicely.

Maintainer (optional):

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. By default, all PDDs are maintained by the Parrot Architect.

Abstract:

A quick blurb explaining the purpose of the PDD.

Synopsis (optional):

Code snippets showing the semantics of the PDD (if applicable).

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 parrot-dev mailing list (located at parrot-dev@lists.parrot.org) for discussion, criticism and general kibitzing. Acceptance of a particular PDD is ultimately up to the Parrot Architect.

PDD Translations

Translations of PDDs into other languages should meet these guidelines:

The Maintainer section should record who made the translation.
The Version section should include an additional note of the translation version.

Attachments

(none)

References