[Python-Dev] PEP 411: Provisional packages in the Python standard library

[Nick Coghlan]

On Sun, Feb 12, 2012 at 1:20 AM, Antoine Pitrou <solipsis at pitrou.net> wrote:
> On Fri, 10 Feb 2012 16:06:15 +0200
> Eli Bendersky <eliben at gmail.com> wrote:
>>
>> Following the intensive and fruitful discussion of the (now rejected)
>> PEP 408 (http://mail.python.org/pipermail/python-dev/2012-January/115850.html),
>> we've drafted PEP 411 to summarize the conclusions with regards to the
>> process of marking packages provisional. Note that this is an
>> informational PEP, and that for the sake of completeness it duplicates
>> some of the contents of PEP 408.
>
> I think the word "provisional" doesn't mean anything to many
> (non-native English speaking) people. I would like to suggest something
> clearer, e.g. "experimental" or "unstable" - which have the benefit of
> *already* having a meaning in other software-related contexts.

No, those words are far too strong. "Provisional" is exactly the right
word for the meaning we want to convey (see
http://dictionary.reference.com/browse/provisional, especially the
second sense). Radical changes to provisional modules are highly
unlikely (if we're that wrong about a module, we're more likely to
just drop it than we are to change it significantly), but tweaks to
eliminate rough edges are a real possibility. Truly experimental,
unstable code has no place in the standard library in the first place
(that's one of the things PyPI is for).

For the record (and the PEP should probably mention this), the end
user facing explanation of provisional modules is closely modelled on
the one Red Hat use in explaining their Tech Preview concept:
https://access.redhat.com/support/offerings/techpreview/

(Unfortunately, Google don't appear to have a clear user facing
explanation of the meaning of "experimental" disclaimers in Google App
Engine APIs, although it appears such APIs really are closer in nature
to being truly experimental than what we're proposing for the stdlib)

Now, what would make sense is to have a definition of "provisional
API" in the glossary, and link to that from the module docs, rather
than explaining the concept separately in each provisional module.

The notice in each package could then be shortened to:

    The <X> API has been included in the standard library on a
provisional basis.
    Backwards incompatible changes (up to and including removal of the API) may
    occur if deemed necessary by the standard library developers.

The phrase "provisional basis" would then be a link to the glossary
term "provisional API", defined as:

    A provisional API is one which has been deliberately excluded from
the standard library's normal
    backwards compatibility guarantees. While major changes to such
APIs are not expected, as long
    as they are marked as provisional, backwards incompatible changes
(up to and including removal
    of the API) may occur if deemed necessary by the standard library
developers. Such changes will
    not be made gratuitously - they will occur only if serious flaws
are uncovered that were missed prior
    to inclusion of the API.

    This process allows the standard library to continue to evolve
over time, without locking in problematic
    design errors for extended periods of time. See PEP 411 for more details.

Cheers,
Nick.

-- 
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia