Update PEP 426 based on distutils-sig feedback

- include an example of Python-Requires + environment markers
- allow a bare Extension field (and give an example use case)
- be explicit that projects that refuse to use compliant version
  numbering must continue to use metadata v1.1
- add guidelines for sorting across metadata versions
- add guidelines for dependencies across metadata versions
- point out that the new sort order is more consistent with that
  of pkg_resources
- mention the implicit test and doc features in the rationale
  for supporting optional features in general
- consistently use sentence case for headings, instead of a mix
  of sentence case and title case
- other typo fixes

pep-0426.txt

@@ -32,7 +32,7 @@ placed into a payload section. Finally, this version addresses several
 issues with the previous iteration of the standard version numbering scheme.
 
 
-Metadata Files
+Metadata files
 ==============
 
 The syntax defined in this PEP is for use with Python distribution
@@ -64,7 +64,7 @@ ASCII. Parser implementations should be aware that older versions of
 the Metadata specification do not specify an encoding.
 
 
-Metadata Header Fields
+Metadata header fields
 =======================
 
 This section specifies the names and semantics of each of the
@@ -101,7 +101,7 @@ Example::
 Version
 -------
 
-A string containing the distribution's version number. See `Version Scheme`_
+A string containing the distribution's version number. See `Version scheme`_
 below.
 
 Example::
@@ -300,7 +300,7 @@ that it provides ``ExampleORM-somedb-bindings``, allowing other
 projects to depend only on having at least one of them installed.
 
 A version declaration may be supplied and must follow the rules described
-in `Version Scheme`_. The distribution's version number will be implied
+in `Version scheme`_. The distribution's version number will be implied
 if none is specified.
 
 Examples::
@@ -336,7 +336,7 @@ Indicates that this project is no longer being developed.  The named
 project provides a substitute or replacement.
 
 A version declaration may be supplied and must follow the rules described
-in `Version Specifiers`_.
+in `Version specifiers`_.
 
 Possible uses for this field include handling project name changes and
 project mergers.
@@ -365,7 +365,7 @@ Package Index`_; often the same as, but distinct from, the module names
 as accessed with ``import x``.
 
 Version declarations must follow the rules described in
-`Version Specifiers`_
+`Version specifiers`_
 
 Distributions may also depend on optional features of other distributions.
 See `Optional Features`_ for details.
@@ -398,9 +398,9 @@ Examples::
 
     Setup-Requires-Dist: custom_setup_command
 
-Dependencies mentioned in ``Setup-Requires-Dist`` may be installed exclusively
+Dependencies mentioned in ``Setup-Requires-Dist`` may be installed
-for setup and are not guaranteed to be available at run time. If a
+exclusively for setup and are not guaranteed to be available at run time.
-dependency is needed during distribution creation or installation
+If a dependency is needed during distribution creation or installation
 *and* at run time, it should be listed under both ``Requires-Dist`` and
 ``Setup-Requires-Dist``.
 
@@ -411,19 +411,28 @@ Requires-Python (multiple use)
 This field specifies the Python version(s) that the distribution is
 guaranteed to be compatible with.
 
-If specified multiple times, the Python version must satisfy all such
+Version declarations must be in the format specified in
-constraints to be considered compatible (this is most useful in combination
+`Version specifiers`_.
-with appropriate `Environment markers`_)
-
-Version numbers must be in the format specified in `Version Specifiers`_.
 
 Examples::
 
-    Requires-Python: 2.5
+    Requires-Python: 3.2
-    Requires-Python: >2.1
+    Requires-Python: >3.1
     Requires-Python: >=2.3.4
     Requires-Python: >=2.5,<2.7
 
+If specified multiple times, the Python version must satisfy all such
+constraints to be considered compatible. This is most useful in combination
+with appropriate `Environment markers`_.
+
+For example, if a feature was initially introduced to Python as a
+Unix-specific addition, and then Windows support was added in the
+subsequent release, this could be indicated with the following pair
+of entries::
+
+    Requires-Python: >= 3.1
+    Requires-Python: >= 3.2; sys.platform == 'win32'
+
 
 Requires-External (multiple use)
 --------------------------------
@@ -439,7 +448,7 @@ parentheses.
 
 Because they refer to non-Python software releases, version numbers
 for this field are **not** required to conform to the format
-described in `Version Scheme`_:  they should correspond to the
+described in `Version scheme`_:  they should correspond to the
 version scheme used by the external dependency.
 
 Notice that there is no particular rule on the strings to be used.
@@ -504,12 +513,15 @@ extension fields ``Chili/Type:`` etc.
 Values in extension fields must still respect the general formatting
 requirements for metadata headers.
 
-An ``Extension: Name`` entry with no corresponding extension fields is an
+A bare ``Extension: Name`` entry with no corresponding extension fields is
-error, as is an extension field with no corresponding ``Extension: Name``
+permitted. It may, for example, indicate the expected presence of an
-entry.
+additional metadata file rather than the presence of extension fields.
+
+An extension field with no corresponding ``Extension: Name`` entry is an
+error.
 
 
-Describing the Distribution
+Describing the distribution
 ===========================
 
 The distribution metadata should include a longer description of the
@@ -534,20 +546,20 @@ field as plain text without any special formatting.  This means that
 authors should be conservative in the markup they use.
 
 
-Version Scheme
+Version scheme
 ==============
 
 Version numbers must comply with the following scheme::
 
     N.N[.N]+[{a|b|c|rc}N][.postN][.devN]
 
-Parser implementations should be aware that versions of the Metadata
+Version numbers which do not comply with this scheme are an error. Projects
-specification prior to v1.2 (PEP 345) do not specify a standard version
+which wish to use non-compliant version numbers must restrict themselves
-numbering scheme. For metadata v1.2, it is recommended that implementations
+to metadata v1.1 (PEP 314) or earlier, as those versions do not mandate
-use the sorting scheme defined below rather than the one defined in PEP 386.
+a particular versioning scheme.
 
 
-Suffixes and Ordering
+Suffixes and ordering
 ---------------------
 
 The following suffixes are the only ones allowed at the given level of the
@@ -578,7 +590,7 @@ that within a particular project you do not mix `c` and `rc`, especially
 within the same numeric version.
 
 
-Example Version Order
+Example version order
 ---------------------
 
 ::
@@ -599,7 +611,30 @@ Example Version Order
     1.1.dev1
 
 
-Version Specifiers
+Ordering across different metadata versions
+-------------------------------------------
+
+After making a release with a given metadata version, it is assumed that
+projects will not revert to an older metadata version.
+
+Accordingly, and to allow projects with non-compliant version schemes
+to more easily migrate to the version scheme defined in this PEP,
+releases should be sorted by their declared metadata version *before*
+being sorted by the distribution version.
+
+Software that processes distribution metadata should account for the fact
+that metadata v1.0 (PEP 241) and metadata v1.1 (PEP 314) do not
+specify a standard version numbering or sorting scheme. This PEP does
+not mandate any particular approach to handling such versions, but
+acknowledges that the de facto standard for sorting such versions is
+the scheme used by the ``pkg_resources`` component of ``setuptools``.
+
+For metadata v1.2 (PEP 345), the recommended sort order is defined in
+PEP 386 (It is expected that projects where the defined PEP 386 sort
+order is incorrect will skip straight from metadata v1.1 to metadata v1.3).
+
+
+Version specifiers
 ==================
 
 A version specifier consists of a series of version clauses, separated by
@@ -609,7 +644,7 @@ followed by a version number. For example::
    0.9, >= 1.0, != 1.3.4, < 2.0
 
 Each version number must be in the standard format described in
-`Version Scheme`_.
+`Version scheme`_.
 
 Comparison operators must be one of ``<``, ``>``, ``<=``, ``>=``, ``==``
 and ``!=``.
@@ -658,7 +693,7 @@ first release in a series, such as ``2.5.0``, can easily refer specifically
 to that version with the clause ``2.5.0``, while the clause ``2.5`` refers
 to that entire series. Projects which omit the ".0" suffix for the first
 release of a series, by using a version string like ``2.5`` rather than
-``2.5.0``, will need to use an explicit clause like ``2.5, < 2.5.1`` to
+``2.5.0``, will need to use an explicit clause like ``>= 2.5, < 2.5.1`` to
 refer specifically to that initial release.
 
 Some Examples:
@@ -687,6 +722,23 @@ Some Examples:
   pre-releases like 3.4a1.
 
 
+Depending on distributions that use non-compliant version schemes
+-----------------------------------------------------------------
+
+A distribution using this version of the metadata standard may need to depend
+on another distribution using an earlier version of the metadata standard
+and a non-compliant versioning scheme.
+
+The normal ``Requires-Dist`` and ``Setup-Requires-Dist`` fields can be used
+for such dependencies, so long as the dependency itself can be expressed
+using a compliant version specifier.
+
+For more exotic dependencies, a metadata extension would be needed in order
+to express the dependencies accurately while still obeying the restrictions
+on standard version specifiers. The ``Requires-External`` field may also
+be used, but would not be as amenable to automatic processing.
+
+
 Environment markers
 ===================
 
@@ -775,7 +827,7 @@ Listing these implicit features explicitly in a ``Provides-Extra`` field is
 permitted, but not required.
 
 
-Updating the Metadata Specification
+Updating the metadata specification
 ===================================
 
 The metadata specification may be updated with clarifications without
@@ -786,7 +838,7 @@ changing the meaning of existing fields, requires a new metadata version
 defined in a new PEP.
 
 
-Summary of Differences From \PEP 345
+Summary of differences from \PEP 345
 ====================================
 
 * Metadata-Version is now 1.3
@@ -804,6 +856,8 @@ Summary of Differences From \PEP 345
 
 * Changed interpretation of version specifiers
 
+* Explicit handling of ordering and dependencies across metadata versions
+
 * Support for packaging, build and installation dependencies
 
    * the new ``Setup-Requires-Dist`` field
@@ -858,7 +912,14 @@ PEP 386 is to sort top level developmental releases like ``X.Y.devN`` ahead
 of alpha releases like ``X.Ya1``. This is a far more logical sort order, as
 projects already using both development releases and alphas/betas/release
 candidates do not want their developmental releases sorted in
-between their release candidates and their full releases.
+between their release candidates and their full releases. There is no
+rationale for using ``dev`` releases in that position rather than
+merely creating additional release candidates.
+
+The updated sort order also means the sorting of ``dev`` versions is now
+consistent between the metadata standard and the pre-existing behaviour
+of ``pkg_resources`` (and hence the behaviour of current installation
+tools).
 
 Making this change should make it easier for affected existing projects to
 migrate to the latest version of the metadata standard.
@@ -910,9 +971,10 @@ requested.
 The ``Requires-Dist`` and ``Setup-Requires-Dist`` fields then allow
 distributions to require optional features of other distributions.
 
-One key motivation for this feature is to allow distributions to
+The ``test`` and ``doc`` features are implicitly defined for all
-explicitly declare the dependencies needed to run their automatic
+distributions, as one key motivation for this feature is to encourage
-tests, or build their documentation, without demanding those
+distributions to explicitly declare the dependencies needed to run
+their automatic tests, or build their documentation, without demanding those
 dependencies be present in order to merely install or use the software.
 
 
@@ -925,7 +987,7 @@ standard overal format metadata format for easy of processing by
 distribution tools that do not support a particular extension.
 
 It also works well in combination with the new ``Setup-Requires-Dist`` field
-to allow a distribution to depend on tools which *do* now how to handle
+to allow a distribution to depend on tools which *do* know how to handle
 the chosen extension, and the new optional features mechanism, allowing
 support for particular extensions to be provided as optional features.
 
@@ -968,7 +1030,7 @@ Version 1.0 is specified in PEP 241.
 Version 1.1 is specified in PEP 314.
 Version 1.2 is specified in PEP 345.
 
-The initial attempt at a standardised Version Scheme, along with the
+The initial attempt at a standardised version scheme, along with the
 justifications for needing such a standard can be found in PEP 386.
 
 .. [1] reStructuredText markup: