Author: chip
Date: Wed Oct 12 09:59:20 2005
New Revision: 9468
Added:
trunk/docs/pdds/pdd00_pdd.pod
- copied, changed from r9421, trunk/docs/pdds/clip/pdd00_pdd.pod
Log:
New PDD: PDD guidelines.
Copied: trunk/docs/pdds/pdd00_pdd.pod (from r9421,
trunk/docs/pdds/clip/pdd00_pdd.pod)
==============================================================================
--- trunk/docs/pdds/clip/pdd00_pdd.pod (original)
+++ trunk/docs/pdds/pdd00_pdd.pod Wed Oct 12 09:59:20 2005
@@ -5,47 +5,56 @@
docs/pdds/pdd00_pdd.pod - Parrot Design Documents
+=head1 VERSION
+
+$Revision$
+
=head1 ABSTRACT
-This document defines the standard format for the Parrot Design Documents
-(PDDs) - the basic descriptions/plans for the design of Parrot.
+This document defines the content and format of Parrot Design
+Documents (PDDs).
=head1 DESCRIPTION
-The original intent of the Parrot Design Documents (which themselves were
-initially Perl Design Documents) was threefold:
+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 descirbe Parrot's:
=over 4
-=item 1
+=item *
+
+I<Codable interfaces>: headers, functions, macros, file formats, etc.
+
+=item *
-To provide a clear indication of the direction of current development
-(essentially, a road map from an abstract idea to a concrete implementation).
+I<Structural requirements> that the implementation must obey:
+resource usage, portability, modularity, interdependency, etc.
-=item 2
+=item *
-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.
+I<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.
-=item 3
+=item *
-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.
+More? - FIXME
=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.
+PDDS B<should not> discuss the implementation details or trade-offs,
+unless they absolutely have to. Such implementation documentation
+should go in the relevant F<*.dev> file. On the other hand, PDDs
+B<should design trade-offs, i.e. the paths not chosen.
+
+These guidelines may seem fuzzy. The line between "design" and
+"implementation" is a murky one. Still, please try to adhere to this
+design for Parrot design documentation. How you implement it is up to
+you. :-)
=head1 IMPLEMENTATION
@@ -56,22 +65,23 @@ 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 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 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 S<L<"PDD TRANSLATIONS">>.)
-All PDDs will contain the following information:
+See L<pdd_template.pod> for the basic structure of a PDD. Notes on
+the sections:
=over 4
-=item TITLE:
+=item 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
@@ -79,109 +89,16 @@ 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>.
+Document version. Since Parrot is currently kept in a Subversion
+repository, the $$-delimited keyword "Revision" will do nicely.
-=item Developing
+=item MAINTAINER I<(optional)>:
-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.
+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.
=item ABSTRACT:
@@ -220,8 +137,7 @@ The PDD author may add any additional se
Proposed PDDs should be submitted to the perl6-internals mailing list (located
at [email protected]) 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).
+Acceptance of a particular PDD is ultimately up to the Parrot Architect.
=head2 PDD TRANSLATIONS
@@ -232,63 +148,19 @@ should be met.
=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.
+The C<MAINTAINER> section should record who made the translation.
=item *
-Attributions in the C<HISTORY> section should be left alone.
+The C<VERSION> section should include an additional note of the
+translation version.
=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.
+(none)
=head1 REFERENCES
-Dan Sugalski's original PDD guidelines at
-L<http://www.mail-archive.com/[email protected]/msg01766.html>
-
-=head1 VERSION
-
-=head2 CURRENT
-
- Maintainer: Simon Glover <[EMAIL PROTECTED]>
- 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 <[EMAIL PROTECTED]>
- 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).
-
+(none)
