classification
Title: Add link to PortingPythonToPy3k to What's New documentation
Type: enhancement Stage:
Components: Documentation Versions: Python 3.1
process
Status: closed Resolution: out of date
Dependencies: Superseder:
Assigned To: docs@python Nosy List: amcnabb, ezio.melotti, georg.brandl, loewis, r.david.murray, rhettinger
Priority: normal Keywords:

Created on 2010-03-12 19:02 by amcnabb, last changed 2010-12-14 18:54 by r.david.murray. This issue is now closed.

Messages (8)
msg100956 - (view) Author: Andrew McNabb (amcnabb) Date: 2010-03-12 19:02
The What's New documentation for Python 3.0 and 3.1 have sections called "Porting to Python 3.0".  It would be great to add a link to the Python wiki page about porting Python to Python 3:

http://wiki.python.org/moin/PortingPythonToPy3k
msg100960 - (view) Author: Martin v. Löwis (loewis) * (Python committer) Date: 2010-03-12 19:46
-1. The page contains bad advice, and shouldn't be recommended in its current form. 

That probably could be fixed, but points to the core problem: in the wiki, anybody can add text, even if it's not properly reviewed.

It would IMO be better if a reviewed and rewritten version of that text was contributed to the documentation directly.
msg100969 - (view) Author: Andrew McNabb (amcnabb) Date: 2010-03-12 21:03
What advice in particular do you consider bad?  I would be happy to submit some changes to the wiki page for anything that's wrong.

I think it would be great to have a reviewed version in the documentation directly, but I think the world needs a little more experience with Python 3 before it could be done well.  In the meantime, I think it's important to get the discussion moving towards finding a set of best practices.  Raising the visibility of the wiki page seems like a great way to encourage participation and to get things moving forward.

Right now, there's no sense of best practices in porting to Python 3, and it's leaving people with the impression that it's too hard and not worth it.
msg100971 - (view) Author: Andrew McNabb (amcnabb) Date: 2010-03-12 21:22
By the way, I just noticed your notes on the wiki page and added a response/question.  It seems that the advice that you consider bad is the official porting story (upgrade to 2.6 and use 2to3).  I agree that it's easier and better to not drop support for 2.4 and 2.5, but this seems to be officially discouraged.  The current content on the What's New page only talks about upgrading to 2.6 and using 2to3.

In any case, most of the current content on the wiki page is about supporting Python 2 and Python 3 simultaneously.  I think this is actually better than the official documentation.
msg100974 - (view) Author: Martin v. Löwis (loewis) * (Python committer) Date: 2010-03-12 21:34
> What advice in particular do you consider bad?  I would be happy to
> submit some changes to the wiki page for anything that's wrong.

See my comments on the page. The first headline is IMO fairly
counter-productive, as it (essentially) suggests that you can't start
supporting 3.x until you can leave 2.5 behind - which for most projects
will still be several years in the future.

> Right now, there's no sense of best practices in porting to Python 3,
> and it's leaving people with the impression that it's too hard and
> not worth it.

Then discuss the page and its contents on the python-porting list.
msg100975 - (view) Author: Martin v. Löwis (loewis) * (Python committer) Date: 2010-03-12 21:41
Andrew McNabb wrote:
> Andrew McNabb <amcnabb@mcnabbs.org> added the comment:
> 
> By the way, I just noticed your notes on the wiki page and added a
> response/question.  It seems that the advice that you consider bad is
> the official porting story (upgrade to 2.6 and use 2to3).

No, "drop support for Python older than 2.6" is completely, entirely
different from "upgrade to 2.6".

> I agree
> that it's easier and better to not drop support for 2.4 and 2.5, but
> this seems to be officially discouraged.

Says who?

> In any case, most of the current content on the wiki page is about
> supporting Python 2 and Python 3 simultaneously.  I think this is
> actually better than the official documentation.

If, by "official documentation", you refer to the 3 paragraphs in
"what's new", then I agree that the text could be improved. However,
I completely disagree that your Wiki page is better wrt. to running code
 simultaneously on 2.x and 3.x unmodified.

Your page encourages such a style, and "what's new" discourages,
pointing out that it leads to contorted code. I completely agree that it
does, and the approaches proposed should be the absolute exception in
any porting strategy.
msg100976 - (view) Author: Andrew McNabb (amcnabb) Date: 2010-03-12 21:43
Thanks for your advice.  I just signed up for the python-porting list, and I'll start a discussion there.

I'm trying to improve the wiki page to address your concerns.  There are multiple valid approaches to take, and I'm trying to make the page show this.  I'll remove the inline notes for now (since they clutter things), and I'll try to incorporate your changes.  I apologize in advance if I make any mistakes.
msg123971 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2010-12-14 18:54
Raymond, I'm adding you as nosy even though I'm closing the issue as out of date in case you do want to add a link in the 3.2 What's New.
History
Date User Action Args
2010-12-14 18:54:04r.david.murraysetstatus: open -> closed

nosy: + rhettinger, r.david.murray
messages: + msg123971

type: enhancement
resolution: out of date
2010-10-29 10:07:21adminsetassignee: georg.brandl -> docs@python
2010-03-12 21:43:37amcnabbsetmessages: + msg100976
2010-03-12 21:41:45loewissetmessages: + msg100975
2010-03-12 21:34:59loewissetmessages: + msg100974
title: Add link to PortingPythonToPy3k to What's New documentation -> Add link to PortingPythonToPy3k to What's New documentation
2010-03-12 21:22:59amcnabbsetmessages: + msg100971
2010-03-12 21:03:12amcnabbsetmessages: + msg100969
2010-03-12 20:48:38ezio.melottisetpriority: normal
nosy: + ezio.melotti
2010-03-12 19:46:15loewissetnosy: + loewis
messages: + msg100960
2010-03-12 19:02:01amcnabbcreate