/ 
parrot-0_0_7
/ pdds::pdd00_pdd

TITLE

Perl Design Documents

VERSION

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

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.

CHANGES

CURRENT and HISTORY updated for standardization.

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.

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.

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

  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.

  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.

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

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 PDD Format as 0. (See 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 solely for the purpose of adhering to a PDD format change.

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 "PDD TRANSLATIONS".)

All PDDs will contain the following information:

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 n number of PDDs.

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

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.

PDD Number

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

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

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

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

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

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

INFORMATIONAL TRACK
Informational

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

Replaced in whole by another PDD.

Obsolete

Naturally obsolete.

EXPERIMENTAL TRACK
Experimental

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

Superseded by PDD #

Replaced in whole by another PDD.

Obsolete

Naturally obsolete.

STANDARDS TRACK
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.

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.

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 Standard 6.0, Standard 6.0a, Standard 6.0.1, and Standard 6.0.1a.

Superseded by PDD #

Replaced in whole by another PDD.

Obsolete

Naturally obsolete.

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

Last Modified

Required. The date of the last submission.

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.

Language

Optional. The language 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 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.

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

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

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

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

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

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

AVAILABILITY

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

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

ATTACHMENTS

A. pddtempl.pod

REFERENCES

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