[Python-Dev] New Pythondoc by effbot (original) (raw)

Fredrik Lundh fredrik at pythonware.com
Sun Jan 22 13:30:41 CET 2006

Guido van Rossum wrote:

> On this page, 8 of 30 entries have a 'new in' comment. For anyone with no > interest in the past, these constitute noise. I wonder if for 3.0, the > timer can be reset and the docs start clean again. To keep them backwards > compatible, they would also have to be littered with 'changed in 3.0' and > 'deleted in 3.0' entries. Better, I think, to refer people to the last 2.x > docs and a separate 2.x/3.0 changes doc.

(That has nothing to do with Fredrik's efforts of course -- he's just faithfully copying the annotations from the existing docs.) If Python 3.0 is indeed the major incompatible release that we currently expect it will be, I agree that "new in 3.0" and "new in 2.x" annotations make little sense, since so much will be "new in 3.0" (or "deleted in 3.0"). It's probably better to have a separate document explaining the differences between 2.x and 3.0.

absolutely.

For the 2.x line, however (and again post-3.0) I think the "new in X" annotations are important -- lots of people have to deal with different Python versions, and it's a lot easier to depend on "new in X" notations than to manually compare two or more versions of the docs. (Although you still need to do thorough testing -- like the rest of the docs, these annotations can't be 100% perfect.)

if we move over to a web-oriented (wiki-ish) maintenance model, we probably have to accept that "X" will, sometimes, be a future release.

More information about the Python-Dev mailing list