[Python-Dev] Breaking undocumented API

[Tres Seaver]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On 11/17/2010 09:16 AM, Steven D'Aprano wrote:
> Ben Finney wrote:
> 
>> I don't know about Guido, but I'd be −1 on suggestions to add more
>> normative information to PEP 7, PEP 8, PEP 257, or any other established
>> style guide PEP. I certainly don't want to have to keep going back to
>> the same documents frequently just to see if the set of recommendations
>> I already know has changed recently.
> 
> This is not a problem unique to any specific PEP. How do we learn about 
> any changes that might interest us? What are the alternatives?
> 
> - our knowledge is fixed to what we knew at some particular date, and 
> gets further and further obsolete as time goes by;
> 
> - we actively search out new knowledge;
> 
> - we wait for somebody to tell us that something we knew has changed.
> 
> (E.g. I was rather surprised to learn that, sometime over the last few 
> years, the number of extra-solar planets known to astronomers have 
> increased from the one or two I was aware of to multiple dozens.)
> 
> All three strategies have advantages and disadvantages.
> 
> Regardless of whether future versions of the style-guide are called "PEP 
> 8" or whether they are given new names ("PEP 8" -> "PEP 88" -> ...), we 
> have the identical problem -- how do we know whether or not there is a 
> new version of the style guide to look for? In twelve months time, how 
> sure will we be that PEP 88 is the most recent version to look for? 
> Perhaps we missed the release of PEP 95.
> 
> The one advantage of giving each revision of the document an updated 
> name is that, under some circumstances, we *might* be able to detect a 
> new revision easily. If I think that PEP 88 is the most recent version, 
> and somebody says that the recommended style guide is PEP 89, I might:
> 
> - think that he merely made a mistake, and meant to say 88; or
> - think that there is a new document for me to look at.
> 
> 
>> Rather, I took Guido's mention of “this belongs in a style guide” as
>> suggesting a *new* style guide. Perhaps one that explicitly obsoletes an
>> existing one or perhaps not; either way, the updated normative
>> recommendations are in a new document with a new name, so that one knows
>> whether one has already read it.
> 
> How do you know which is the most recent version of the style guide to 
> look at? Instead of doing a O(1) lookup of PEP 8, you have to follow a 
> potentially O(N) search:
> 
> PEP 8 is obsoleted by PEP 88... go and look at PEP 88.
> PEP 88 is obsoleted by PEP 93... go at look at PEP 93.
> PEP 93 is obsoleted by PEP 123... go and look at PEP 123.
> PEP 123 doesn't contain an "obsoleted by" notice, so:
> (1) either it is the current document, or
> (2) it has been obsoleted, but the link to the new version was missed, 
> and it is now very hard to discover what the current document is called.
> 
> Personally, I don't think the current PEP arrangement is broken enough 
> to change it. Each PEP is already tracked in VCS and history is 
> available for it. There's insufficient advantage, and some disadvantage, 
> to splitting each revision of the PEPs into new documents with new 
> names. -1 on the idea.

FWIW, Guido recently ruled that updating PEP 333 to indicate how WSGI
would work in Python3 was not appropriate, and suggested instead a new
PEP (3333), stating[1]:

 Of those, IMO only textual clarifications ought to be made to an
 existing, accepted, widely implemented standards-track PEP.

Note that the BDFL ruled this way even though the changes to PEP 333
were essentially clarifications which applied only to Python 3:  the
existing Python 2 semantics would have rmeained the same.[2]


[1] http://permalink.gmane.org/gmane.comp.python.devel/117269
[2] http://permalink.gmane.org/gmane.comp.python.devel/117249



Tres.
- -- 
===================================================================
Tres Seaver          +1 540-429-0999          tseaver at palladion.com
Palladion Software   "Excellence by Design"    http://palladion.com
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.10 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iEYEARECAAYFAkzj7ZwACgkQ+gerLs4ltQ7mPgCg1TpA+rF0WigLGB1xeuUTyRF7
MLQAnjGUgWZUqQBLfbwl6RanA+ME4Hth
=zuiQ
-----END PGP SIGNATURE-----