[PEP 817] Switch To Informational Track

[DEKHTIARJonathan]

No description provided.

[Copilot]

Pull request overview

This PR updates PEP 817 to the Informational track and correspondingly trims/restructures the document, including removing the standalone variant-metadata JSON schema appendix and schema file.

Changes:

• Switches the PEP header from Standards Track to Informational and adds an “Informational PEP” section near the top.
• Removes the appendix that literal-included the variant metadata JSON schema and deletes the standalone variant_schema.json.
• Restructures several sections in pep-0817.rst, including substantial removals of previously specified material.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 8 comments.

File	Description
peps/pep-0817.rst	Updates PEP type to Informational and significantly restructures/removes content, adding new framing sections.
peps/pep-0817/appendix-variant-metadata-json-schema.rst	Removes the appendix that embedded the JSON schema via literalinclude.
peps/pep-0817/variant_schema.json	Deletes the standalone JSON Schema file that was referenced by the removed appendix.

Suppressed comments (2)

peps/pep-0817.rst:951

• Unresolved “” placeholder text is checked in right before the example. Replace it with a brief lead-in sentence (and avoid the inline “FLIP it on its head” note).

<TODO> FLIP it on its head => information hardcoded in the pyproject.toml

peps/pep-0817.rst:1366

• Unresolved “ Rephrase” placeholder should be replaced with final prose (or removed) before merging.

<TODO> Rephrase

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[read-the-docs-community]

Documentation build overview

📚 wheelnext-peps | 🛠️ Build #34061870 | 📁 Comparing 97fc8a2 against latest (8605833)

  🔍 Preview build  

6 files changed · ± 5 modified · - 1 deleted

± Modified

• index.html
• numerical/index.html
• pep-0000/index.html
• pep-0817/index.html
• topic/packaging/index.html

- Deleted

• pep-0817/appendix-variant-metadata-json-schema/index.html

[rgommers]

Thanks @DEKHTIARJonathan. Looking at the current state of this PR, it's a good step towards what we need. Given that the diff is already quite large, I'd like to propose keeping the review here fairly minimal, merging this PR as a "remove Specification, rework the structure" and then work on two follow-up PRs:

1. We need to take the second half of the document and make it more conceptual (remove MUST/SHOULD/MAY, overlap in tool implementation suggestions with PEP 825, rewrite the pylock.toml section completely, etc. - then add higher-level narrative explanations)
2. Before the conceptual explanation of what the design is, we need to insert the comparison between different designs that I have a draft for, explaining the main alternative designs we considered and why we ended up with this design.

WDYT?

[mgorny]

Do I understand correctly that the purpose of PEP 817 henceforth will be to define a minimal "end-to-end" view of what PEP 825 and followup PEPs will design in detail?

[rgommers]

I'd say that that's only one part. The Specification should be removed completely (it's Informational), so the outline is something like:

• Abstract & umbrella for the other PEPs (explain / link to)
• Motivation
• Possible design approaches & trade-offs
• High-level explanation of the chosen design & how we see it implemented used

I think with minimal "end-to-end" view you're referring to the last bullet only.

[DEKHTIARJonathan]

@mgorny what we discussed with Ralf @ EuroPython was to capture the context and reasoning behind the variant design and the intended final goal we are collectively aiming at.

[mgorny]

I think with minimal "end-to-end" view you're referring to the last bullet only.

Yeah, that's the part I was referring to.

[mgorny]

Let's merge it as-is and go from there, I guess?

[rgommers]

Agreed, merged. How about you work on the last bullet and I work on the third one @mgorny?

[mgorny]

Sure. Do you see it as replacing the current "overview" or separate?

[rgommers]

I think yes, start at Overview and reassess the content. I think some of the current content needs to stay, and some is too specific or has too much overlap with 825 or one of the PEPs that is to follow. I think for example:

• Keep the pyproject.toml example
• Keep the diagram
• Remove the detailed tool implementation logic
• Shorten niche sections (e.g., null variant) as appropriate
• Get rid of anything that smells like a spec (e.g., the pylock.toml part) and replace it with a higher-level conceptual implementation

Then also give it a fresh look - what, if anything, is completely missing (static file for overrides with use cases that we accepted in the meantime for example?) and see if the whole design explanation is coherent.