Re: PDD status

[Simon Glover]

On Sat, 21 Feb 2004, Michael Scott wrote:

 All that metadata up front in the PDDs is a bit off-putting. I'm
 thinking of going through all of them and putting it at the end. Any
 objections?

 Well, I've just committed the version I posted pretty much as-is, but
 feel free to make any changes to the layout you think are appropriate.

 Simon

 PS Bryan: I've put my name on this as maintainer for now; I hope that's
OK.

Re: PDD status

[Michael Scott]

  - 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
CTesting 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 CInformational and CDeveloping.
We hope to eventually add CStandard. 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. CDeveloping PDDs
are expected to eventually become Cstandard.
=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 [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).
=head2 PDD TRANSLATIONS

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

=item *

The CMaintainer field should reflect who did the translation.

=item *

The CVersion number should match the original document's CVersion
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 CHISTORY 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 CInformational, and CDeveloping PDDs should be readily 
available,
in a centralized location, to at least the current Parrot development
circles.  All CStandard PDDs should be readily available, in a
centralized location, to the general public.

=head1

Re: PDD status

[Tim Bunce]

Did you forget to add Volunteers wanted for each of these ?

Tim.

On Thu, Feb 19, 2004 at 08:17:50PM -0500, Simon Glover wrote:
 
  PDD 0 (intro. to PDDs):
 
Very, very out of date; I think it actually pre-dates Parrot
 
  PDD 1 (overview of Parrot):
 
Not obviously out-of-date, but could use some text on IMCC and on the JIT
 
  PDD 2 (vtable functions):
 
Needs documentation on freeze, thaw and share from somebody who
actually understands what they do. We also need to figure out which
of the functions described in it are simply waiting to be implemented
and which are never going to be implemented
 
  PDD 4 (datatypes):
 
The bigint/bignum stuff is completely out-of-date. We also need to
figure out if there are any other internal datatypes that we should
be documenting.
 
  PDD 5 (opfuncs):
 
Very, very out-of-date. Needs a significant rewrite.
 
  PDD 6 (PASM):
 
Missing a lot of ops. Also includes some ops that don't exist.
(An easy task for the interested would be to put together a list of
 each).
 
  PDD 7 (coding standards):
 
OK, as far as I know.
 
  PDD 8 (keys):
 
   This is quite old, so we need to check if it accurately describes the
   current system.
 
  PDD 9 (GC):
 
   Doesn't discuss any of the recent changes, such as the early DOD stuff
 
  PDD 10 (embedding):
 
   Empty. (Although we do have embed.pod)
 
  PDD 11 (extending):
 
   Empty. (But see extend.pod)
 
  PDD 12 (assembly):
 
   Empty and obsolete.
 
  PDD 13 (bytecode):
 
   Empty. (But see parrotbyte.pod)
 
  PDD 14 (bignums):
 
   Bignums are unimplemented, so all of this may change in the future.
 
 
  PDD 3 (calling conventions):
 
  PDD 15 (objects):
 
   Dan's handling these.
 
  PDD 16 (NCI):
 
   Needs looking over by somebody who understands the NCI system.
 
 
 

Re: PDD status

[Simon Glover]

On Fri, 20 Feb 2004, Tim Bunce wrote:

 Did you forget to add Volunteers wanted for each of these ?


 Well, I'm going to try to tackle some of it, but since I have minimal
 CFT at the moment, any volunteers would be very welcome.

 Simon

Re: PDD status

[Simon Glover]

 OK, here's a rewritten version of PDD 0, which reflects my view of
 the role that the PDDs currently play in Parrot development.
 Comments welcome.

 Simon

Re: PDD status

[Simon Glover]

 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 CInformational and CDeveloping.
We hope to eventually add CStandard. 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. CDeveloping PDDs
are expected to eventually become Cstandard.

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

=head2 PDD TRANSLATIONS

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

=over 4

=item *

The CMaintainer field should reflect who did the translation.

=item *

The CVersion number should match the original document's CVersion
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 CHISTORY 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 CInformational, and CDeveloping PDDs should be readily available,
in a centralized location, to at least the current Parrot development
circles.  All CStandard 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/[EMAIL PROTECTED]/msg01766.html

PDD status

[Simon Glover]

 PDD 0 (intro. to PDDs):

   Very, very out of date; I think it actually pre-dates Parrot

 PDD 1 (overview of Parrot):

   Not obviously out-of-date, but could use some text on IMCC and on the JIT

 PDD 2 (vtable functions):

   Needs documentation on freeze, thaw and share from somebody who
   actually understands what they do. We also need to figure out which
   of the functions described in it are simply waiting to be implemented
   and which are never going to be implemented

 PDD 4 (datatypes):

   The bigint/bignum stuff is completely out-of-date. We also need to
   figure out if there are any other internal datatypes that we should
   be documenting.

 PDD 5 (opfuncs):

   Very, very out-of-date. Needs a significant rewrite.

 PDD 6 (PASM):

   Missing a lot of ops. Also includes some ops that don't exist.
   (An easy task for the interested would be to put together a list of
each).

 PDD 7 (coding standards):

   OK, as far as I know.

 PDD 8 (keys):

  This is quite old, so we need to check if it accurately describes the
  current system.

 PDD 9 (GC):

  Doesn't discuss any of the recent changes, such as the early DOD stuff

 PDD 10 (embedding):

  Empty. (Although we do have embed.pod)

 PDD 11 (extending):

  Empty. (But see extend.pod)

 PDD 12 (assembly):

  Empty and obsolete.

 PDD 13 (bytecode):

  Empty. (But see parrotbyte.pod)

 PDD 14 (bignums):

  Bignums are unimplemented, so all of this may change in the future.


 PDD 3 (calling conventions):

 PDD 15 (objects):

  Dan's handling these.

 PDD 16 (NCI):

  Needs looking over by somebody who understands the NCI system.