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

-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.

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.

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.

> 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.

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.

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.

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.