From 2c85e597bc64e938096d33981a351ee42de10fad Mon Sep 17 00:00:00 2001 From: Nick Coghlan Date: Sun, 28 Oct 2012 21:54:33 +1000 Subject: [PATCH] Clarify what 'latest version' means, mark Georg as PEP czar and bump status back to Draft until Georg gives a +1 on the redirection of /dev/ URLs --- pep-0430.txt | 46 +++++++++++++++++++++++++++++++--------------- 1 file changed, 31 insertions(+), 15 deletions(-) diff --git a/pep-0430.txt b/pep-0430.txt index 7e5729e7c..f5fdb293d 100644 --- a/pep-0430.txt +++ b/pep-0430.txt @@ -3,7 +3,8 @@ Title: Migrating to Python 3 as the default online documentation Version: $Revision$ Last-Modified: $Date$ Author: Nick Coghlan -Status: Final +BDFL-Delegate: Georg Brandl +Status: Draft Type: Informational Content-Type: text/x-rst Created: 27-Oct-2012 @@ -85,13 +86,13 @@ This PEP (based on an idea originally put forward back in May [4_]) is to 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 +Visitors to the root URL at ``http://docs.python.org`` will 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 +``http://docs.python.org/library/os``, will 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 +The specific subpaths which will be redirected to explicitly qualified paths for the Python 2 docs are: * ``/c-api/`` @@ -114,7 +115,12 @@ paths for the Python 2 docs are: * ``/py-modindex.html`` * ``/search.html`` -The existing ``/py3k/`` subpath would be remapped to the new ``/3/`` subpath. +The existing ``/py3k/`` subpath will be redirected to the new ``/3/`` +subpath. + +To help ensure future stability even of links to the in-development version, +the ``/dev/`` subpath will be redirected to the appropriate version specific +subpath (currently ``/3.4/``). Presented URLs @@ -128,20 +134,30 @@ resolution of any aliasing and rewriting rules: * ``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/`` URLs mean "give me the latest documentation for a released +version in this release series". It will draw the documentation from the +relevant maintenance branch in source control (this will always be the +2.7 branch for Python 2 and is currently 3.3 for Python 3). 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 +It will draw the documentation from the relevant maintenance branch in +source control (or the default branch for the currently in development +version. 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). +The ``/release/x.y.x/`` URLs will refer to the documentation of those +releases, exactly as it was at the time of the release. + +The developer's guide is not version specific, and thus retains its own +stable ``/devguide/`` URL. Rationale =========