On Wed, Dec 23, 2009 at 3:31 AM, Tres Seaver <tseaver@palladion.com> wrote: [..]
The deprecation of the existing Requires/Provides/Obsoletes fields should be more prominent - tucked away below the examples, I missed these notices on the first read through (I only noticed that they actually had been formally deprecated when I got to the summary of differences at the end). I suggest placing the deprecation notice immediately after the relevant field headers.
Good point. I thought I had done so in the initial editing pass.
I've done it yesterday.
There also needs to be an explanation in the PEP as to whether or not it is legal to use both Requires and Requires-Dist (etc) in the same PKG-INFO file. (i.e. what is the use case for allowing the old fields to be used in a metadata v1.2 PKG-INFO file? Should PEP 345 aware packaging tools just ignore the old fields, while v1.1 tools ignore the new ones? Or should new tools attempt to handle both?)
No tools that I know of currently use 'Requires' / 'Provides' / 'Obsoletes' at all: their contents have never been informative enough to allow for useful automation. For completeness sake, we can document that tools should ignore any 'Requires', 'Provides', or 'Obsoletes' fields when any of the '-Dist' versions are present.
Although some (a small number) distributions use these, so one way to handle it is to do a little bit like what was done when 1.1 came out: if a "1.2" field is found and no "1.1" field is found: metadata 1.2 is used if a "1.1" field is found and no "1.2" field is found: metadata 1.1 is used + a warning is displayed if a "1.1" field is found and a "1.2" field is found: a warning is displayed and 1.2 is used, 1.1 fields are ignored if no 1.1 field or 1.2 fields are found: metadata 1.2 is used
The various lines about there being no standards or canonical definitions for particular fields also seem to run counter to the spirit of the detailed guidelines in the description of each field (which imply that some standards have already been adopted by convention). Perhaps these comments could be softened to say that although the metadata specification formally allows arbitrary strings in these fields, the descriptions are recommended guidelines for creating field entries that automated tools will handle correctly?
That language is left over from PEP 314, which introduced those "advisory" fields. The expectation of PEP 345 is that developers who want their packages to be easily consumable by automated tools will avoid the deprecated fields and use the more usefully-specifiied new ones.
Notice that I now provide in 2.7/3.2 a way to read *and* write PKG-INFO from an API: http://docs.python.org/dev/distutils/examples.html#reading-the-metadata meaning that whatever fields a developer use, this API will let the installers and other automated tool gets the metadata. It might be a good thing to inform about that API in the PEP I guess,
Finally, as a general formatting request - some blank space between the end of the previous example and the header for the next field description would make the field descriptions much easier to read.
Hmm, I thought we were following stock ReST formats: perhaps the CSS should be adjusted to give a larger leading space to headings?
I've changed the layout yesterday, so its easier to read. Regards Tarek -- Tarek Ziadé | http://ziade.org