PEP for updating the URL layout on docs.python.org

pep-0430.txt

@@ -0,0 +1,200 @@
+PEP: 430
+Title: Migrating to Python 3 as the default online documentation
+Version: $Revision$
+Last-Modified: $Date$
+Author: Nick Coghlan <ncoghlan@gmail.com>
+Status: Draft
+Type: Informational
+Content-Type: text/x-rst
+Created: 27-Oct-2012
+
+
+Abstract
+========
+
+This PEP proposes a strategy for migrating the default version of the
+Python documentation presented to users of Python when accessing
+docs.python.org from 2.7 to Python 3.3.
+
+It proposes a backwards compatible scheme that preserves the meaning of
+existing deep links in to the Python 2 documentation, while still
+presenting the Python 3 documentation by default, and presenting the
+Python 2 and 3 documentation in a way that avoids making the Python 3
+documentation look like a second-class citizen.
+
+
+Background
+==========
+
+With the transition of the overall Python ecosystem from Python 2 to Python 3
+still in progress, one question which arises periodically [1_, 2_] is when
+and how to handle the change from providing the Python 2 documentation as
+the default version displayed at the docs.python.org root URL to providing
+the Python 3 documentation.
+
+While efforts are under way [3_] to improve the general version switching
+support in the online documentation, this PEP is technically independent
+of those improvements.
+
+
+Key Concerns
+============
+
+There are a couple of key concerns that any migration proposal needs to
+address.
+
+
+Don't Confuse Beginners
+-----------------------
+
+Many beginners learn Python through third party resources. These resources,
+not all of which are online resources, may reference in to the python.org
+online documentation for additional background and details.
+
+Importantly, even when the online documentation is updated, the "version
+added" and "version changed" tags usually provide enough information for
+users to adjust appropriately for the specific version they are using.
+
+While deep links in to the python.org documentation may occasionally break
+within the Python 2 series, this is very rare.
+
+Migrating to Python 3 is a very different matter. Many links would break due
+to renames and removals, and the "version added" and "version changed"
+information for the Python 2 series is completely absent.
+
+
+Don't Break Useful Resources
+----------------------------
+
+There are many useful Python resources out there, such as the mailing list
+archives on python.org and question-and-answer sites like Stack Overflow,
+where links are highly unlikely to be updated, no matter how much notice
+is provided.
+
+Old posts and answers to questions all currently link to docs.python.org
+expecting to get the Python 2 documentation at unqualified URLs. Links from
+answers that relate to Python 3 are explicitly qualified with ``/py3k/`` in
+the path component.
+
+
+Proposal
+========
+
+This PEP (based on an idea originally put forward back in May [4_]) is to
+*not migrate* the Python 2 specific deep links at all, and instead adopt a
+scheme where all URLs presented to users on docs.python.org are qualified
+appropriately with the relevant release series.
+
+Visitors to the root URL at ``http://docs.python.org`` would be automatically
+redirected to ``http://docs.python.org/3/``, but links deeper in
+the version-specific hierarchy, such as to
+``http://docs.python.org/library/os``, would instead be redirected to
+a Python 2 specific link such as ``http://docs.python.org/2/library/os``.
+
+The specific subpaths which would be remapped to explicitly qualified
+paths for the Python 2 docs are:
+
+* ``/c-api/``
+* ``/distutils/``
+* ``/extending/``
+* ``/faq/``
+* ``/howto/``
+* ``/library/``
+* ``/reference/``
+* ``/tutorial/``
+* ``/using/``
+* ``/whatsnew/``
+* ``/about.html``
+* ``/bugs.html``
+* ``/contents.html``
+* ``/copyright.html``
+* ``/license.html``
+* ``/genindex.html``
+* ``/glossary.html``
+* ``/py-modindex.html``
+* ``/search.html``
+
+The existing ``/py3k/`` subpath would be remapped to the new ``/3/`` subpath.
+
+
+Presented URLs
+--------------
+
+With this scheme, the following URLs would be presented to users after
+resolution of any aliasing and rewriting rules:
+
+* ``http://docs.python.org/x/*``
+* ``http://docs.python.org/x.y/*``
+* ``http://docs.python.org/release/x.y.z/*``
+* ``http://docs.python.org/devguide``
+
+The ``/x/`` URLs mean "give me the latest documentation for this release
+series``. Differences relative to previous versions in the release series
+will be available through "version added" and "version changed" markers.
+
+The ``/x.y/`` URLs mean "give me the latest documentation for this release".
+It differs from the status quo in that the URLs will actually remain
+available in the user's browser for easy copy and pasting. (Currently,
+references to specific versions that are not the latest in their release
+series will resolve to a stable URL for a specific maintenance version in
+the "release" hierarchy, while the current latest version in the release
+series resolves to the release series URL. This makes it hard to get a
+"latest version specific URL", since it is always necessary to construct
+them manually).
+
+
+Rationale
+=========
+
+There is some desire to switch the unqualified references to mean Python 3
+as a sign of confidence in Python 3. Such a move would either break a lot of
+things, or else involve an awful lot of work to *avoid* breaking things.
+
+I believe we can get much the same effect without breaking the world by:
+
+1. Deprecating the use of unqualified references to the online
+   documentation (while promising to preserve the meaning of such
+   references indefinitely)
+2. Updating all python.org and python-dev controlled links to use
+   qualified references (excluding archived email)
+3. Redirecting visitors to the root of ``http://docs.python.org`` to
+   ``http://docs.python.org/3.x``
+
+Most importantly, because this scheme doesn't alter the behaviour of any
+existing deep links, it could be implemented with a significantly shorter
+warning period than would be required for a scheme that risked breaking
+deep links, or started to redirect unqualified links to Python 3. The
+only part of the scheme which would require any warning at all is the
+step of redirecting the "http://docs.python.org/" landing page to the
+Python 3.3 documentation.
+
+Namespaces are one honking great idea - let's do more of those.
+
+
+Implementation
+==============
+
+The URLs on docs.python.org are controlled by the python.org infrastructure
+team rather than through the CPython source repo, so acceptance and
+implementation of the ideas in this PEP will be up to the team.
+
+
+References
+==========
+
+.. [1] May 2012 discussion
+   (http://mail.python.org/pipermail/python-dev/2012-May/119524.html)
+
+.. [2] October 2012 discussion
+   (http://mail.python.org/pipermail/python-ideas/2012-October/017406.html)
+
+.. [3] Issue for easier access to other version of the same docs page
+   (http://bugs.python.org/issue8040)
+
+.. [4] Using a "/latest/" path prefix
+   (http://mail.python.org/pipermail/python-dev/2012-May/119567.html)
+
+
+Copyright
+===========
+This document has been placed in the public domain.