Update PEP 413 to better explain rationale for a separate version number and note the possibility of actually slowing down the rate of change for the language definition itself

pep-0413.txt

@@ -7,7 +7,7 @@ Status: Draft
 Type: Process
 Content-Type: text/x-rst
 Created: 2012-02-24
-Post-History: 2012-02-24
+Post-History: 2012-02-24, 2012-02-25
 Resolution: TBD
 
 
@@ -162,6 +162,177 @@ The 3.4 release cycle would then follow a similar pattern to that for 3.3::
     3.5.0 + 15.08.0  # Language release
 
 
+User Scenarios
+==============
+
+The versioning scheme proposed above is based on a number of user scenarios
+that are likely to be encountered if this scheme is adopted. In each case,
+the scenario is described for both the status quo (i.e. slow release cycle)
+the versioning scheme in this PEP and the free wheeling minor version number
+scheme proposed in PEP 407.
+
+To give away the ending, the point of using a separate version number is that
+for almost all scenarios, the important number is the *language* version, not
+the standard library version. Most users won't even need to care that the
+standard library version number exists. In the two identified cases where
+it matters, providing it as a separate number is actually clearer and more
+explicit than embedding the two different kinds of number into a single
+sequence and then tagging some of the numbers in the unified sequence as
+special.
+
+
+Novice user, downloading Python from python.org in March 2013
+-------------------------------------------------------------
+
+*Status quo:* must choose between 3.3 and 2.7
+
+*This PEP:* must first choose between 3.3 and 2.7. If choosing 3.3, must then
+choose between 3.3 (13.02) or 3.3 (12.08)
+
+*PEP 407:* must choose between 3.4, 3.3 (LTS) and 2.7.
+
+Verdict: explaining the meaning of a Long Term Support release is about as
+complicated as explaining the meaning of the proposed standard library
+version numbers. I call this a tie.
+
+
+Novice user, looking for appropriate binary release
+---------------------------------------------------
+
+*Status quo:* look for the binary corresponding to the Python version you are
+running.
+
+*This PEP:* same as status quo.
+
+*PEP 407 (full releases):* same as status quo, but corresponding binary version
+is more likely to be missing (or, if it does exist, has to be found amongst
+a much larger list of alternatives).
+
+*PEP 407 (ABI updates limited to LTS releases):* all binary release pages will
+need to tell users that Python 3.3, 3.4 and 3.5 all need the 3.3 binary.
+
+Verdict: I call this a clear win for the scheme in this PEP. Absolutely
+nothing changes from the current situation, since the standard library
+version is actually irrelevant in this case (only binary extension
+compatibility is important).
+
+
+Extension module author, deciding whether or not to make a binary release
+-------------------------------------------------------------------------
+
+*Status quo:* unless using the PEP 384 stable ABI, a new binary release is
+needed every time the minor version number changes.
+
+*This PEP:* same as status quo.
+
+*PEP 407 (full releases):* same as status quo, but becomes a far more
+frequent occurrence.
+
+*PEP 407 (ABI updates limited to LTS releases):* before deciding, must first
+look up whether the new release is an LTS release or an interim release. If
+it is an LTS release, then a new build is necessary.
+
+Verdict: I call this another clear win for the scheme in this PEP. As with
+the end user facing side of this problem, the standard library version is
+actually irrelevant in this case. Moving that information out to a
+separate number avoids creating unnecessary confusion.
+
+
+Python developer, deciding priority of eliminating a Deprecation Warning
+------------------------------------------------------------------------
+
+*Status quo:* code that triggers deprecation warnings is not guaranteed to
+run on a version of Python with a higher minor version number.
+
+*This PEP:* same as status quo
+
+*PEP 407:* unclear, as the PEP doesn't currently spell this out. Assuming the
+deprecation cycle is linked to LTS releases, then upgrading to a non-LTS
+release is safe but upgrading to the next LTS release may require avoiding
+the deprecated construct.
+
+Verdict: another clear win for the scheme in this PEP since, once again, the
+standard library version is irrelevant in this scenario.
+
+
+Alternative interpreter implementor, updating with new features
+---------------------------------------------------------------
+
+*Status quo:* new Python versions arrive infrequently, but are a mish-mash of
+standard library updates and core language definition and interpreter
+changes.
+
+*This PEP:* standard library updates, which are easier to integrate, are
+made available more frequently in a form that is clearly and explicitly
+compatible with the previous version of the language definition. This means
+that, once an alternative implementation catches up to Python 3.3, they
+should have a much easier time incorporating standard library features as
+they happen (especially pure Python changes), leaving minor version number
+updates as the only task that requires updates to their core compilation and
+execution components.
+
+*PEP 407 (full releases):* same as status quo, but becomes a far more
+frequent occurrence.
+
+*PEP 407 (language updates limited to LTS releases):* unclear, as the PEP
+doesn't currently spell out a specific development strategy. Assuming a
+3.3 compatibility branch is adopted (as proposed in this PEP), then the
+outcome would be much the same, but the version number signalling would be
+slightly less clear (since you would have to look up to see if a particular
+release was an LTS release or not).
+
+Verdict: while not as clear cut as some previous scenarios, I'm still calling
+this one in favour of the scheme in this PEP. Explicit is better than
+implicit, and the scheme in this PEP makes a clear split between the two
+different kinds of update rather than adding a separate "LTS" tag to an
+otherwise ordinary release number. Tagging is great for version control
+systems, but it's a lousy way to communicate information to other humans.
+
+
+Python developer, deciding their minimum version dependency
+-----------------------------------------------------------
+
+*Status quo:* look for "version added" or "version tagged" markers in the
+documentation, check against ``sys.version_info``
+
+*This PEP:* look for "version added" or "version tagged" markers in the
+documentation. If written as a bare Python version, such as "3.3", check
+against ``sys.version_info``. If qualified with a standard library version,
+such as "3.3 (13.02)", check against ``sys.stdlib_info``.
+
+*PEP 407:* same as status quo
+
+Verdict: the scheme in this PEP actually allows third party libraries to be
+more explicit about their rate of adoption of standard library features. More
+conservative projects will likely pin their dependency to the language
+version and avoid features added in the standard library releases. Faster
+moving projects could instead declare their dependency on a particular
+standard library version. However, since PEP 407 does have the advantage of
+preserving the status quo, I'm calling this one for PEP 407 (albeit with a
+slim margin).
+
+
+Python developers, attempting to reproduce a tracker issue
+----------------------------------------------------------
+
+*Status quo:* if not already provided, ask the reporter which version of
+Python they're using. This is often done by asking for the first two lines
+displayed by the interactive prompt or the value of ``sys.version``.
+
+*This PEP:* same as the status quo (as ``sys.version`` will be updated to
+also include the standard library version), but may be needed on additional
+occasions (where the user knew enough to state their Python version, but that
+proved to be insufficient to reproduce the fault).
+
+*PEP 407:* same as the status quo
+
+Verdict: another marginal win for PEP 407. The new standard library version
+*is* an extra piece of information that users may need to pass back to
+developers when reporting issues with Python libraries (or Python itself,
+on our own tracker). However, by including it in ``sys.version``, many
+fault reports will already include, and it is easy to request if needed.
+
+
 Effects
 =======
 
@@ -174,6 +345,10 @@ in a language release, each language release will be limited to 6 months
 worth of standard library changes, as well as any changes associated with
 new syntax.
 
+If a release date slips by a month or two, I would keep the planned standard
+library version number rather than updating it to reflect the actual release
+date.
+
 Effect on workflow
 ------------------
 
@@ -191,6 +366,16 @@ it is an acceptable change for a standard library release. If so, then it
 should be checked in on ``3.3-compat`` and then merged to ``default``.
 Otherwise it should be checked in directly to ``default``.
 
+The ``3.3-compat`` branch would be closed after the 3.3+13.08 release, as
+the next release at that time will be a full language release.
+
+The "version added" and "version changed" markers for any changes made on
+the ``3.3-compat`` branch would need to be flagged with both the language
+version and the standard library version. For example: "3.3 (13.02)".
+
+Any changes made directly on the ``default`` branch would just be flagged
+with "3.4" as usual.
+
 
 Effect on bugfix cycle
 ----------------------
@@ -259,7 +444,7 @@ eventual numbering conflict can be safely deemed somebody elses problem :)
 NEWS
 ----
 
-Merge conflicts on the NEWS file is already a hassle. Since this PEP
+Merge conflicts on the NEWS file are already a hassle. Since this PEP
 proposes introduction of an additional branch into the normal workflow,
 resolving this becomes even more critical. While Mercurial phases will
 help to some degree, it would be good to eliminate the problem entirely.
@@ -272,13 +457,8 @@ the release of 3.3.0+12.8.0 using the existing NEWS process) might look
 like::
 
   Misc/
-    lang_news/
+    news_entries/
-      3.3.1/
+      3.3.1/ # Maintenance branch changes
-        <files for core language changes>
-      3.4.0/
-        <files for core language changes>
-    stdlib_news/
-      12.08.1/
         builtins/
           <files for builtin changes>
         extensions/
@@ -289,7 +469,9 @@ like::
           <files for documentation changes>
         tests/
           <files for testing changes>
-      13.02.0/
+      3.4.0/ # default branch changes
+        language/
+          <files for core language changes>
         builtins/
           <files for builtin changes>
         extensions/
@@ -300,14 +482,70 @@ like::
           <files for documentation changes>
         tests/
           <files for testing changes>
-    NEWS  # Now autogenerated from lang_news and stdlib_news
+      13.02.0/ # 3.3 compatibility branch changes
+        builtins/
+          <files for builtin changes>
+        extensions/
+          <files for extension module changes>
+        library/
+          <files for pure Python module changes>
+        documentation/
+          <files for documentation changes>
+        tests/
+          <files for testing changes>
+    NEWS  # Now autogenerated from news_entries
 
 Putting the version information in the directory heirarchy isn't strictly
 necessary (since the NEWS file generator could figure out from the version
-history), but does make it easy for *humans* to keep the different versions
+history), but does make it easier for *humans* to keep the different versions
 in order.
 
 
+Option: Slowing down the language release cycle
+===============================================
+
+The current release cycle is a compromise between the desire for stability
+in the core language definition and C extension ABI, and the desire to get
+new feature (most notably standard library updates) into users hands quickly.
+
+With the standard library release cycle decoupled (to some degree) from that
+of the core language definition, it provides an opportunity to actually 
+*slow down* the rate of change in the language definition. The language
+moratorium for Python 3.2 effectively slowed that cycle down to *more than 3
+years* (3.1: June 2009, 3.3: August 2012) without causing any major
+complaints.
+
+The NEWS file management scheme described above is actually designed to
+allow us the flexibility to slow down language releases at the same time
+as standard library releases become more frequent.
+
+As simple example, if a full two years was allowed between 3.3 and 3.4,
+the 3.3 release cycle would be up looking like::
+
+    3.2.4            # Maintenance release
+    3.3.0 + 12.08.0  # Language release
+
+    3.3.1 + 12.08.1  # Maintenance release
+    3.3.1 + 13.02.0  # Standard library release
+
+    3.3.2 + 12.08.2  # Maintenance release
+    3.3.2 + 13.08.1  # Standard library release
+
+    3.3.3 + 12.08.3  # Maintenance release
+    3.3.3 + 14.02.1  # Standard library release
+
+    3.3.4 + 12.08.4  # Maintenance release
+    3.4.0 + 14.08.0  # Language release
+
+The elegance of the proposed NEWS entry layout is that this decision
+wouldn't need to be made until after the 13.08 standard library release. At
+that point, the ``3.3-compat`` branch could be kept open (thus adding
+another standard library release to the cycle), or else it could be closed,
+committing to the next release being a full language release. The choice
+between another standard library release or a full language release would
+then be available every 6 months after that.
+
+
 Why isn't PEP 384 enough?
 =========================