[Python-checkins] peps: Bump PEP 426 metadata version to 2.0

[nick.coghlan]

http://hg.python.org/peps/rev/7702cc74d6ed
changeset:   4748:7702cc74d6ed
user:        Nick Coghlan <ncoghlan at gmail.com>
date:        Sun Feb 17 19:43:54 2013 +1000
summary:
  Bump PEP 426 metadata version to 2.0

files:
  pep-0426.txt |  51 +++++++++++++++++++++++++++++----------
  1 files changed, 38 insertions(+), 13 deletions(-)


diff --git a/pep-0426.txt b/pep-0426.txt
--- a/pep-0426.txt
+++ b/pep-0426.txt
@@ -1,5 +1,5 @@
 PEP: 426
-Title: Metadata for Python Software Packages 1.3
+Title: Metadata for Python Software Packages 2.0
 Version: $Revision$
 Last-Modified: $Date$
 Author: Daniel Holth <dholth at fastmail.fm>,
@@ -21,12 +21,12 @@
 It includes specifics of the field names, and their semantics and
 usage.
 
-This document specifies version 1.3 of the metadata format.
+This document specifies version 2.0 of the metadata format.
 Version 1.0 is specified in PEP 241.
 Version 1.1 is specified in PEP 314.
 Version 1.2 is specified in PEP 345.
 
-Version 1.3 of the metadata format adds fields designed to make
+Version 2.0 of the metadata format adds fields designed to make
 third-party packaging of Python Software easier and defines a formal
 extension mechanism.  It also adds support for optional features of
 distributions and allows the description to be placed into a payload
@@ -65,7 +65,7 @@
 Encoding
 ========
 
-Metadata 1.3 files are UTF-8 with the restriction that keys must be
+Metadata 2.0 files are UTF-8 with the restriction that keys must be
 ASCII. Parser implementations should be aware that older versions of
 the Metadata specification do not specify an encoding.
 
@@ -76,7 +76,7 @@
 This section specifies the names and semantics of each of the
 supported fields in the metadata header.
 
-In a single Metadata 1.3 file, fields marked with "(optional)" may occur
+In a single Metadata 2.0 file, fields marked with "(optional)" may occur
 0 or 1 times.  Fields marked with "(multiple use)" may be specified
 0, 1 or more times.  Only "Metadata-Version", "Name", "Version", and
 "Summary" must appear exactly once.
@@ -87,11 +87,15 @@
 Metadata-Version
 ----------------
 
-Version of the file format; "1.3" is the only legal value.
+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.
 
 Example::
 
-    Metadata-Version: 1.3
+    Metadata-Version: 2.0
 
 
 Name
@@ -144,7 +148,7 @@
 Description (optional, deprecated)
 ----------------------------------
 
-Starting with Metadata 1.3, the recommended place for the description is in
+Starting with Metadata 2.0, the recommended place for the description is in
 the payload section of the document, after the last header.  The description
 does not need to be reformatted when it is included in the payload.
 
@@ -1196,7 +1200,8 @@
 Summary of differences from \PEP 345
 ====================================
 
-* Metadata-Version is now 1.3
+* Metadata-Version is now 2.0, with semantics specified for handling
+  version changes
 
 * Most fields are now optional
 
@@ -1263,6 +1268,26 @@
 The rationale for major changes is given in the following sections.
 
 
+Metadata-Version semantics
+--------------------------
+
+The semantics of major and minor version increments are now specified,
+and follow the same model as the format version semantics specified for
+the wheel format in PEP 427: minor version increments must behave
+reasonably when processed by a tool that only understand earlier metadata
+versions with the same major version, while major version increments
+may include changes that are not compatible with existing tools.
+
+The major version number of the specification has been incremented
+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.
+
+
 Standard encoding and other format clarifications
 -------------------------------------------------
 
@@ -1491,7 +1516,7 @@
 References
 ==========
 
-This document specifies version 1.3 of the metadata format.
+This document specifies version 2.0 of the metadata format.
 Version 1.0 is specified in PEP 241.
 Version 1.1 is specified in PEP 314.
 Version 1.2 is specified in PEP 345.
@@ -1513,10 +1538,10 @@
 Appendix
 ========
 
-Parsing and generating the Metadata 1.3 serialization format using
+Parsing and generating the Metadata 2.0 serialization format using
 Python 3.3::
 
-    # Metadata 1.3 demo
+    # Metadata 2.0 demo
     from email.generator import Generator
     from email import header
     from email.parser import Parser
@@ -1545,7 +1570,7 @@
         import textwrap
 
         pkg_info = """\
-    Metadata-Version: 1.3
+    Metadata-Version: 2.0
     Name: package
     Version: 0.1.0
     Summary: A package.

-- 
Repository URL: http://hg.python.org/peps