From 57dc04d92af05b1affeb960ff27b5202dfc11535 Mon Sep 17 00:00:00 2001 From: Nick Coghlan Date: Mon, 18 Feb 2013 22:02:45 +1000 Subject: [PATCH] PEP 426: clarify metadata version transitions --- pep-0426.txt | 28 ++++++++++++++++++++++------ 1 file changed, 22 insertions(+), 6 deletions(-) diff --git a/pep-0426.txt b/pep-0426.txt index 3689546e9..0e269a0b3 100644 --- a/pep-0426.txt +++ b/pep-0426.txt @@ -89,9 +89,15 @@ Metadata-Version 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 @@ accordingly, as interpreting PEP 426 metadata in accordance with earlier 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). Standard encoding and other format clarifications