[Python-Dev] docs.python.org pointing to Python 3 by default? (original) (raw)
Nick Coghlan ncoghlan at gmail.com
Mon May 21 06:28:06 CEST 2012
- Previous message: [Python-Dev] docs.python.org pointing to Python 3 by default?
- Next message: [Python-Dev] docs.python.org pointing to Python 3 by default?
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
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
- Previous message: [Python-Dev] docs.python.org pointing to Python 3 by default?
- Next message: [Python-Dev] docs.python.org pointing to Python 3 by default?
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]