pypi: import Name Retention Policy from PEP 541

[woodruffw]

Hi all!

This is my attempt to copy another piece of PyPI policy into the policies website.

What I've done here is take PEP 541 and copy it mostly verbatim into the MkDocs site. The only changes I've made are:

1. I've removed the non-policy parts of the PEP (i.e. the procedurally required sections that aren't part of the PEP's policy specification). I figured that this is easier to read/follow than having PEP-isms in the policy page here.

2. I've preserved all links exactly as they were, but turned them all into direct links instead of footnote links. This is a slightly change from the PEP, where a mix is used.

Apart from those changes, the language of the policy should be exactly as it appears in PEP 541. However, it'd be good for someone to go over it with a fine-toothed comb to ensure I didn't make any formatting errors during conversion to Markdown.

CC @ewdurbin @miketheman

xref pypi/warehouse#17999 for context 🙂

[woodruffw]

(NB: If/when this is merged, I'll also make a PR to the PEPs repo providing an appropriate "living spec" or similar link from PEP 541 to this page, similar to what the packaging PEPs do with PyPUG.)

[miketheman]

I'm in favor of adopting this language into the policies page.

@ewdurbin is there a reason we should not merge this?

[woodruffw]

Gentle ping 🙂

[ewdurbin]

I think this should probably just live in docs.pypi.org. I fundamentally get why it semantically fits in "Policies", but it's probably saner to have it where folks expect PyPI things that aren't legal mumbo jumbo like ToS.

Thoughts @Thespi-Brain?

[woodruffw]

Yeah, that makes sense to me -- I'd be happy to find a home in the PyPI docs if you all would prefer it there instead of here.

(My main goal -- if I'm remembering from a few months back -- was to put this somewhere other than the PEP itself, since linking to the PEP rather than a living docs site seems non-ideal for ordinary users who don't know or care about the standards process.)

[Thespi-Brain]

@ewdurbin and @woodruffw, I am leaning towards having it in PyPI docs but I think I might have missed the original context behind this. Was the goal/intention to have a separate space for PEP 541 name retention be available on PyPI and not just the actual PEP page? Just need a clarification to understand better.

[woodruffw]

Was the goal/intention to have a separate space for PEP 541 name retention be available on PyPI and not just the actual PEP page? Just need a clarification to understand better.

Yeah, the goal here is twofold:

1. Put the polices (as standardized) somewhere other than the PEP page, since PEPs aren't the friendliest user resource (and PyPI currently links to them instead of a more accessible resource)
2. From the procedural perspective, put the policies somewhere so that (like the other PyPA specifications) they can be given a "living canonical location"

Both of those subgoals are achieved if this is on docs.pypi.org or here; so I'm open to whatever is easier and more intuitive for you all 🙂

[Thespi-Brain]

@woodruffw Thanks for the clarification. I think because it is less of a policy (even though I realize it says in the name, context wise it's not really a "policy" per se such as ToS) and more of what to expect for users looking to create a PEP 541 request, I think having it be on docs.pypi.org would be a better fit.

[woodruffw]

Sounds good! I'll close this then, and I'll open a similar PR on PyPI's docs.