To see what is currently happening visit http://www.perl6.org/
docs/pdds/pdd00_pdd.pod - Parrot Design Documents
This document defines the standard format for the Parrot Design Documents (PDDs) - the basic descriptions/plans for the design of Parrot.
The original intent of the Parrot Design Documents (which themselves were initially Perl Design Documents) was threefold:
To provide a clear indication of the direction of current development (essentially, a road map from an abstract idea to a concrete implementation).
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.
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.
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.
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:
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).
Contains current and selected historical metadata on the PDD itself.
Contains the following information, current as of the date of submission.
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).
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).
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.
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.
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:
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.
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.
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.
Required. The date of the last submission.
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.
Optional. The language that the PDD is written in.
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.
A summary of the changes since the last version. A comprehensive change log should be kept, but only within a supporting document.
A quick blurb explaining the purpose of the PDD.
A description of the general nature of the PDD and how it relates to Parrot.
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.
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 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.
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).
Should a PDD be translated into another language, the following guidelines should be met.
Maintainer field should reflect who did the translation.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.HISTORY section should be left alone.Any change to the status of a particular PDD should be approved by the current Pumpking and/or the internals chief.
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.
None.
Dan Sugalski's original PDD guidelines at www.mail-archive.com
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
v2 substantially rewritten on 20 Feb 2004 by Simon Glover
v1 created on 7 Dec 2000 by BCWarnock <bwarnock@raba.com>
v1 promoted to Developing as PDD 0 on 20 February 2001 by Dan Sugalski.
Substantially rewritten to reflect what the PDDs actually are (rather
than what we hoped they would be 3+ years ago).