=head1 TITLE

Perl Design Documents

=head1 VERSION

=head2 CURRENT

    Maintainer: Bryan C. Warnock <bwarnock@capita.com>
    Class: Meta
    PDD Number: 0 
    Version: 2
    Status: Developing
    Last Modified:  4 March 2001
    PDD Format: 0
    Language: English

=head2 HISTORY

    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.

=head1 CHANGES

CURRENT and HISTORY updated for standardization.

=head1 ABSTRACT

This document defines the standard format for documenting Perl
development decisions - the how and why of Perl internals and the detailed
expected behavior of new language constructs, as well as
the surrounding ethos and culture of the development community.  This
document identifies Perl Design Document Standard 6.0.

=head1 DESCRIPTION

One of the shortcomings of most long-term development and maintenance
efforts - and Perl has been no exception - is the lack of readily
available documentation describing the rationale behind many of the
implementation decisions.  News archives and mailing archives are
becoming increasingly difficult to find random information in,
particularly with the myriad lists that Perl 6 begot.

Although there will always be decisions which are obvious due to a lack
of alternatives, many design decisions may have multiple technically
feasible solutions.  Why X instead of Y?  Why this instead of that?  Is
the decision based on an obscure bit of technical arcana?  Is the
decision based on Perl culture, which itself is a product of many of
the undocumented decisions made before?  Or is the decision truly a
toss-up, with a solution picked pseudo-randomly?

A Perl Design Document (PDD) is a readily available record of the Perl
community's thought process in regards to a specific structure related
to Perl development.  As such, it serves three major purposes.

=over 4

=item 1

A clear indication of the direction of current development.  A PDD
provides a road map from abstraction to implementation of an idea. 

=item 2

An historical record of the rationale behind the decision.  A PDD
provides context to future developers, who may not have been familiar
with the original discussion, but are currently involved with the
resultant implementation.

=item 3

An 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

It is not a vehicle for brainstorming or creating a wish-list.  PDDs
are reserved for a concrete snapshot of what B<is>, and what B<will>
be.

=head1 IMPLEMENTATION

All newly created PDDs will adhere to the PDD standard current as of
the time of proposal.  In the absence of an accepted standard, the PDD
will be written in the last generally accepted format, and will
indicate the S<I<PDD Format>> as 0.  (See L<VERSION|"VERSION:">.) 

All existing PDDs will adhere to the PDD standard current as of the
time of re-submission.  Existing PDDs need not be modified and
resubmitted B<solely> for the purpose of adhering to a PDD format
change.

=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 within the Perl community, POD is still the traditional
documentation language for All Things Perl, and PDDs have yet to reach
the level of complexity that requires some of XML's more powerful
capabilities, particularly at a trade-off to the legibility of POD's
simplicity.

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 area within Perl.  For
instance, "Sorting" vice "Sorting with a Heap Sort".  

PDDs should be limited to a specific area of Perl - in the above case,
sorting - but should be broad enough to include the reasons for and
against any specific implementation that may be discussed.  Historical
perspectives can be contrasted and compared through archived versions
of a PDD, vice multiple searches through archived versions of I<n>
number of PDDs.

=item VERSION:

Contains current and selected historical metadata on the PDD itself.

=over 4

=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 POC of the PDD. 
This is to whom questions, comments, and patches are generally
addressed.  This need not be the author of the document.

=item Class

Required.  The area of Perl the PDD covers.  This allows related PDDs
to be logically grouped.  The current list of valid classes roughly
mirror the Perl 6 mailing lists, and are:

    Documentation - on perl documentation.
	Internals - on the internals of perl components.
	Language - on Perl linguistic constructs.
	Meta - on Perl as an entity.
	Testing - on the testing of perl.

It is expected that PDDs will be sufficiently detailed to cover but one of
these areas.  However, as the situation requires, a PDD may belong to more than
one class.  The classes should then be common separated.  Peripheral
excursions into the scope of another class does not warrant an actual
classification.

=item PDD Number

Required.  Newly created PDDs should have a PDD Number of I<TBD>.  PDD
Numbers will be assigned by the Perl Librarian, based on the following
scheme:

=over 4

=item *

C<Informational> PDDs are given a PDD Number of C<I#>, where C<#> is a
one-up integer based on order of release by the Perl Librarian.

=item *

C<Experimental> PDDs are given a PDD Number of C<X#>, where C<#> is a
one-up integer based on order of release by the Perl Librarian.

=item *

C<Proposed> PDDs are B<not> given a PDD Number.  They are given an
unprefixed one-up integer when promoted to C<Developing>.

=back

Since C<Informational> and C<Experimental> PDDs don't require the same
approval process as C<Standards>-track PDDs, their PDD Number should
readily reflect their purpose.  Since C<Proposed> PDDs may be delayed
or prevented from reaching an inclusive status, withholding a PDD
Number can prevent gaps in the PDD Number sequence.

=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, there are three
tracks of PDD, C<Informational>, C<Experimental>, and C<Standards>.
Each track has its own list of states, which are:

=over 4

=item INFORMATIONAL TRACK

=over 4

=item Informational

Informational PDDs are an objective record of 
=item Superseded by PDD #

Replaced in whole by another PDD.

=item Obsolete

Naturally obsolete.

=back

=item EXPERIMENTAL TRACK

=over 4

=item Experimental

Documentation on an experimental feature or use of Perl, such as
porting Perl to a PS2.

=item Superseded by PDD #

Replaced in whole by another PDD.

=item Obsolete

Naturally obsolete.

=back

=item STANDARDS TRACK

=over 4

=item Proposed

A rough draft submitted for consideration from the Perl development
community at large.  A snapshot of the general discussion
surrounding issue foo, but may not accurately reflect the true
direction the community wishes to go.

=item Developing

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

=item Standard (Version #)

A frozen snapshot of the issue, as it applies to Perl at the time of
acceptance.  The version number mirrors the version of perl the standard was
first applied to.  Should a standard be changed within a perl release cycle,
the version number will be suffixed with a lower-case letter.  Example
Standard references are C<Standard 6.0>, C<Standard 6.0a>, C<Standard
6.0.1>, and C<Standard 6.0.1a>.

=item Superseded by PDD #

Replaced in whole by another PDD.

=item Obsolete

Naturally obsolete.   		

=back

=back

PDDs that switch tracks will always begin at the first stage of the
track.

=item Last Modified

Required.  The date of the last submission.  

=item PDD Format

Required.  The specific PDD Standard the PDD adheres to.  This allows scripts
to better parse PDDs of multiple aging formats.  In the absence of a
standard, the PDD Format is 0.

=item Language

Optional.  The language 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 glimpse to the major metadata changes of a PDD.  This field is
not to be used for a comprehensive list of alterations to the document.

=back

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

=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

It is expected that all PDDs submitted as a Proposed will have
undergone an actual discussion within the applicable group(s). 
Following a general consensus of the need for a PDD (and, hopefully, a
general consensus on the particular slant of a PDD proposal), the PDD
can be submitted to the Perl Librarian.

The Perl Librarian should check the document for format, and either
return to the PDD to the maintainer for correction, or publish the PDD
- whatever that actually entails.  (Mailing lists, web site, etc.)

C<Informational> and C<Experimental> PDDs may be submitted on a whim,
but otherwise require the same submittal process as regular PDDs.

=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

Only Larry, a project leader, pumpking, or working group chair may set
C<Status> to anything other than C<Proposed>, C<Informational>, or
C<Experimental>.

=head2 AVAILABILITY

All C<Proposed>, C<Informational>, and C<Experimental> PDDs should be
readily available, in a centralized location, to at least the current
Perl development circles.  All C<Standards>-track PDDs should be
readily available, in a centralized location, to the general public.

All C<Superseded> PDDs should be available upon request.  All
historical versions of PDDs should be available upon request.

=head1 ATTACHMENTS

A. F<pddtempl.pod>

=head1 REFERENCES

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