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
This commit is contained in:
Nick Coghlan
parent
cbfb3afdb3
commit
828ed616fd
262
pep-0413.txt
262
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/
|
||||
3.3.1/
|
||||
<files for core language changes>
|
||||
3.4.0/
|
||||
<files for core language changes>
|
||||
stdlib_news/
|
||||
12.08.1/
|
||||
news_entries/
|
||||
3.3.1/ # Maintenance branch changes
|
||||
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?
|
||||
=========================
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue