[Python-Dev] docs.python.org pointing to Python 3 by default?

Nick Coghlan ncoghlan at gmail.com
Mon May 21 06:28:06 CEST 2012


On Mon, May 21, 2012 at 11:23 AM, Guido van Rossum <guido at python.org> wrote:
> I suggest that we add a separate (virtual) subdomain, e.g. docs3.python.org.

Rather than a new subdomain, I'd prefer to see a discreet
"documentation version" CSS widget, similar to that used in the Django
docs (see https://docs.djangoproject.com/en/1.4/) that indicated the
current displayed version and provided quick links to the 2.7 docs,
the stable 3.x docs and the development docs. The
versionadded/versionchanged notes in the 3.x series are not adequate
for 2.x development, as everything up to and including 3.0 is taken as
a given - the notes are used solely for changes within the 3.x series.

I know plenty of people are keen to push the migration to Python 3
forward as quickly as possible, but this is *definitely* a case of
"make haste slowly". We need to tread carefully or we're going to give
existing users an even stronger feeling that we simply don't care
about the impact the Python 3 migration is having (or is going to
have) on them. *We* know that we care, but there's still plenty of
folks out there that don't realise how deeply rooted the problems are
in Python 2's text model and why the Python 3 backwards compatibility
break was needed to fix them. They don't get to see the debates that
happen on this list - they only get to see the end results of our
decisions. Switching the default docs.python.org version to the 3.x
series is a move that needs to be advertised *well* in advance as a
courtesy to our users, so that those that need to specifically
reference 2.7 have plenty of time to update their links.

Back when Python 3 was first released, we set a target for the
migration period of around 5 years. Since the io performance problems
in 3.0 meant that 3.1 was the first real production ready release of
3.x, that makes June 2014 the target date for when we would like the
following things to be true:
- all major third party libraries and frameworks support Python 3 (or
there are Python 3 forks or functional replacements)
- Python 3 is the default choice for most new Python projects
- most Python instruction uses Python 3, with Python 2 differences
described for those that need to work with legacy code
- (less likely, but possible) user-focused distros such as Ubuntu and
Fedora have changed their "python" symlink to refer to Python 3

That's still 2 years away, and should line up fairly nicely with the
release of Python 3.4 (assuming the current release cadence is
maintained for at least one more version). Key web and networking
frameworks such as Django [1], Pyramid [2] and Twisted [3] should also
be well supported on 3.x by that point.

In the meantime, I propose the following steps be taken in order to
prepare for the eventual migration:
- change the current unqualified URLs into redirects to the
corresponding direct 2.7 URLs
- add a "latest" subpath that is equivalent to the current "py3k" subpath
- add a Django-inspired version switching widget to the CSS & HTML for
the 2.7, 3.2 and trunk docs that offers the following options: 2.7,
3.2, latest (3.2), dev (3.3).

Cheers,
Nick.

[1] https://www.djangoproject.com/weblog/2012/mar/13/py3k/
[2] http://docs.pylonsproject.org/projects/pyramid/en/1.3-branch/whatsnew-1.3.html
[3] http://twistedmatrix.com/trac/milestone/Python-3.x

-- 
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia


More information about the Python-Dev mailing list