[Python-Dev] Python Enhancement Proposals (PEPs)

[Barry A. Warsaw]

>>>>> "JH" == Jeremy Hylton <jeremy@beopen.com> writes:

    JH> At our meeting yesterday Tim suggested that each enhancement
    JH> or language feature have two documents -- a specification and
    JH> a rationale.  It looks like Barry did not adopt that
    JH> suggestion explicitly, but I think it's still a good approach
    JH> for writing a single PEP.

Agreed.  I think a single document can contain both spec and
rationale.

    JH> Each PEP should have a brief technical specification of the
    JH> new feature.  For a feature like augmented assignment, it
    JH> would need to specify the syntax and semantics of each
    JH> operation on each type and on the overloading mechanism for
    JH> classes, e.g. is "a += b += c" valid syntactically and what
    JH> does it mean.

Yes.

    JH> The PEP should also have a rationale that describes why the
    JH> specification is the way it is.  It should discuss
    JH> alternatives that were considered and why there were not
    JH> adopted.  Other topics appropriate for the rationale might be
    JH> motivation (why do we want this feature at all?) and
    JH> comparison (what do other languages do?).

Yes.

    JH> The Scheme language has a similar mechanism called Scheme
    JH> Requests for Implementation (SRFI),
    JH> <http://srfi.schemers.org/>. It is not exactly the same,
    JH> because Scheme seems to have no end of proposals that include
    JH> specification and rationale; they just can't agree on a
    JH> standard set <0.2 wink>.  We might adopt some of their
    JH> processes for the PEPs.

Great pointer, thanks.  Would you like to co-own PEP001 and help me
flesh out the guidelines?  There are lots of good ideas in the SRFI's,
but we should tailor them toward the Python community.

    JH> Two things that each SRFI that PEPs don't yet have are:

    JH> - a mail archive attached to the PEP that contains relevant
    JH>   discussion.  A mail archive seems valuable for people
    JH> interested in the next level of detail, but I'm not sure what
    JH> mechanism to use to create one.  (It also seems valuable
    JH> because the old "search dejanews" certainly isn't stable in
    JH> the long-term.)  Maybe PEP authors could maintain their own
    JH> archives.

One thing mentioned in teh SRFI's is that each gets its own mailing
list.  That might not be a bad idea.  I definitely had the notion that
a PEP would contain URLs to other information (a References section).

    JH> - a copyright notice.  As a strawman, I propose that the
    JH> owner/author
    JH>   of each PEP retains copyright, but must publish it under the
    JH>   OpenContent license, <http://opencontent.org/opl.shtml>.

Looks good to me.

-Barry