[Python-Dev] PEP 426 is now the draft spec for distribution metadata 2.0

[Nick Coghlan]

On Mon, Feb 18, 2013 at 9:54 AM, Nick Coghlan <ncoghlan at gmail.com> wrote:
>
> On 18 Feb 2013 08:36, "Fred Drake" <fred at fdrake.net> wrote:
>>
>> On Sun, Feb 17, 2013 at 4:21 PM, Nick Coghlan <ncoghlan at gmail.com> wrote:
>> > As Daniel pointed out, easy_install and pip also don't follow this rule
>> > yet,
>> > so it won't really have any impact if we never get to metadata 3.0.
>>
>> Actually, my point was that using a separate filename for version 2.0
>> would
>> allow provision of both 1.x and 2.0, so version 2.0 metadata can be
>> deployed
>> as tool support becomes available, instead of having to wait until 1.x
>> tools
>> are replaced.
>>
>> Once tools are following the new rule about version compatibility, there's
>> less worry about this (at least on my part).
>
> None of sdist, wheel or the installation database currently support parallel
> metadata versions. Interpreting 2.0 metadata as 1.1 also won't be
> catastrophically wrong in general, especially if the production tools still
> also ship the legacy dependency and entry points data as separate files. The
> worst thing that is likely to happen is an old tool may fail to show a 2.0
> style description.
>
> However, I *will* update the PEP to state explicitly that tools should emit
> the lowest required metadata version for the fields being published.

I clarified the metadata version handling here:
http://hg.python.org/peps/rev/630c5dd5a123

Rather than "should", I softened the "use the lowest metadata format"
suggestion to a "may". I also pointed out that these new rules will
only apply to a future major version transition, and for this one,
people can just emit the extra files they do today and even older
versions of tools will probably get things fairly right.

Cheers,
Nick.

diff --git a/pep-0426.txt b/pep-0426.txt
--- a/pep-0426.txt
+++ b/pep-0426.txt
@@ -89,9 +89,15 @@

 Version of the file format; "2.0" is the only legal value.

-Automated tools should warn if ``Metadata-Version`` is greater than the
-highest version they support, and must fail if ``Metadata-Version`` has
-a greater major version than the highest version they support.
+Automated tools consuming metadata should warn if ``Metadata-Version`` is
+greater than the highest version they support, and must fail if
+``Metadata-Version`` has a greater major version than the highest
+version they support.
+
+For broader compatibility, automated tools may choose to produce
+distribution metadata using the lowest metadata version that includes
+all of the needed fields.
+

 Example::

@@ -1283,9 +1289,19 @@
 metadata specifications is unlikely to give the expected behaviour.

 Whenever the major version number of the specification is incremented, it
-is expected that deployment will take some time, as metadata consuming tools
-much be updated before other tools can safely start producing the new
-format.
+is expected that deployment will take some time, as either metadata
+consuming tools must be updated before other tools can safely start
+producing the new format, or else the sdist and wheel formats, along with
+the installation database definition, will need to be updated to support
+provision of multiple versions of the metadata in parallel.
+
+Existing tools won't abide by this guideline until they're updated to
+support the new metadata standard, so the new semantics will first take
+effect for a hypothetical 2.x -> 3.0 transition. For the 1.x -> 2.0
+transition, it is recommended that tools continue to produce the
+existing supplementary files (such as ``entry_points.txt``) in addition
+to any equivalents specified using the new features of the standard
+metadata format (including the formal extension mechanism).

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