New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Split specifications page into multiple pages #386

Merged
merged 4 commits into from Oct 3, 2017

Conversation

Projects
None yet
3 participants
@di
Member

di commented Sep 29, 2017

This should fix #319:

  • Each section on /specifications is now it's own page;
  • Included the contents of PEP 345 in /specifications/core-metadata;
  • Added relevant versionadded directives to metadata field specs.

di added some commits Sep 29, 2017

@pradyunsg

This comment has been minimized.

Member

pradyunsg commented Oct 1, 2017

Included the contents of PEP 345 in /specifications/core-metadata

Would this result in redundant information?

@di

This comment has been minimized.

Member

di commented Oct 1, 2017

@pradyunsg Yes, this will "duplicate" fields in PEP 345 for a short time until we can write a new PEP which supersedes it.

You might have missed that this was specifically requested in #319 (comment).

@pradyunsg

This comment has been minimized.

Member

pradyunsg commented Oct 1, 2017

Yes, this will "duplicate" fields in PEP 345 for a short time until we can write a new PEP which supersedes it.

Oh, cool then. :)

You might have missed that this was specifically requested

Indeed.

@pradyunsg

LGTM.

Still on the border about the core-metadata though. If it's till the next PEP comes, then cool. :)

@ncoghlan

Thanks for this! It generally looks good to me, just some requested tweaks to the extracted core metadata page.

(I'm aware that external section heading links to the specifications page will now just get the spec subsection listing, but I figure navigating from there will still be easy enough, so I'm not worried about it)

The source distribution format (``sdist``) is not currently formally defined.
Instead, its format is implicitly defined by the behaviour of the
standard library's ``distutils`` module when executing the ``setup.py sdist``
command.

This comment has been minimized.

@ncoghlan

ncoghlan Oct 2, 2017

Member

Given PEP 517, this section isn't quite accurate any more, but fixing that is out of scope for this PR. I've filed #388 to keep track of it.


However, the version specifiers and environment markers sections of that PEP
have been superceded as described below. In addition, metadata files are
permitted to contain the following additional fields:

This comment has been minimized.

@ncoghlan

ncoghlan Oct 2, 2017

Member

Given the change to include all the existing metadata fields as well, this intro paragraph need to be updated accordingly.

I'd also include an explicit note saying that:

  1. All fields added to later versions are considered optional in earlier versions (so metadata 1.3 fields can be listed even when the nominal metadata version is only 1.2)
  2. Metadata version 1.3 will be defined in a forthcoming PEP that also makes this URL the canonical source for the latest metadata description, so the fields listed as being added in 1.3 aren't typos, they're already-defined fields that will be included without further changes in the next version of the metadata specification

.. versionadded:: 1.0

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

This comment has been minimized.

@ncoghlan

ncoghlan Oct 2, 2017

Member

Now that this is a multi-version format description, this should be reworded more in line with the description in PEP 416: https://www.python.org/dev/peps/pep-0426/#metadata-version

Currently permitted field values are then "1.0", "1.1", and "1.2"

di added some commits Oct 2, 2017

@di

This comment has been minimized.

Member

di commented Oct 2, 2017

@ncoghlan Thanks for your feedback! I think I've addressed everything.

@ncoghlan

LGTM!

@ncoghlan ncoghlan merged commit 6c1cc86 into pypa:master Oct 3, 2017

1 check passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment