# Copyright: 2001-2004 The Perl Foundation.  All Rights Reserved.
# $Id: pdd00_pdd.pod 7418 2005-01-05 05:08:47Z coke $

=head1 NAME

docs/pdds/pdd00_pdd.pod - Parrot Design Documents

=head1 ABSTRACT

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

=head1 DESCRIPTION

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

=over 4

=item 1

To provide a clear indication of the direction of current development
(essentially, a road map from an abstract idea to a concrete implementation).

=item 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.

=item 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.

=back

Needless to say, things didn't work out this way. Some of the context 
discussed above is now documented in the F<*.dev> documents (see the
F</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 B<features
that the interpreter should implement>. They B<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 F<*.dev> file. On the other
hand, they B<should> detail the trade-offs made in the actual design.

=head1 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 F<docs/pdds/pdd_template.pod>, which should be used as a 
template for any future PDDs.

=head2 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 S<L<"PDD TRANSLATIONS">>.)

All PDDs will contain the following information:

=over 4

=item 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).

=item VERSION:

Contains current and selected historical metadata on the PDD itself.

=item CURRENT:

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

=over 4

=item 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).

=item 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 
C<Testing> simply because you happen to mention potential tests at
one or two points in the text).

=item 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.

=item 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.

=item Status

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

=over 4

=item 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 
F</docs/pdds/pdd14_bignum.pod>.

=item 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.

=item 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. C<Developing> PDDs 
are expected to eventually become C<standard>.

=back

=item Last Modified

Required.  The date of the last submission.  

=item 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.

=item Language

Optional.  The language that the PDD is written in.  

=back

=item 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.

=item CHANGES:

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

=item ABSTRACT:

A quick blurb explaining the purpose of the PDD.

=item DESCRIPTION:

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

=item 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.  

=item 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.

=item REFERENCES:

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

=back

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

=head2 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).

=head2 PDD TRANSLATIONS

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

=over 4

=item *

The C<Maintainer> field should reflect who did the translation.

=item *

The C<Version> number should match the original document's C<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.

=item *

Attributions in the C<HISTORY> section should be left alone.

=back

=head2 PDD STATUS CHANGES

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

=head2 AVAILABILITY

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

=head1 ATTACHMENTS

None.

=head1 REFERENCES

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

=head1 VERSION

=head2 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

=head2 HISTORY

    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.

=head1 CHANGES

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

