From 98f250e6e3bc2d0bcbc6e39a436a509198a4bb9e Mon Sep 17 00:00:00 2001 From: Ofek Lev Date: Fri, 6 Sep 2024 19:37:41 -0400 Subject: [PATCH] PEP 755: Implicit namespace policy for PyPI (#3947) * PEP 755: Implicit namespace policy for PyPI * address feedback * address --- peps/pep-0755.rst | 252 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 252 insertions(+) create mode 100644 peps/pep-0755.rst diff --git a/peps/pep-0755.rst b/peps/pep-0755.rst new file mode 100644 index 000000000..e8f4ef147 --- /dev/null +++ b/peps/pep-0755.rst @@ -0,0 +1,252 @@ +PEP: 755 +Title: Implicit namespace policy for PyPI +Author: Ofek Lev +Sponsor: Barry Warsaw +PEP-Delegate: Dustin Ingram +Status: Draft +Type: Process +Topic: Packaging +Created: 05-Sep-2024 + +Abstract +======== + +This PEP codifies an implementation of :pep:`752` for PyPI [1]_. + +Motivation +========== + +Many projects and communities would benefit from the ability to reserve +namespaces. Since PyPI exists to serve the Python community, it is critical +to gather feedback to ensure that everyone's needs are met. + +A dedicated PEP is required because the operational and policy nuances are up +to each package repository to decide. + +Rationale +========= + +PyPI has been understaffed, receiving the first `dedicated specialist`__ in +July 2024. Due to lack of resources, user support has been lacking for +`package name claims `__, +`organization requests `__, +`storage limit increases `__, +and even `account recovery `__. + +__ https://pyfound.blogspot.com/2024/07/announcing-our-new-pypi-support.html + +The `default policy `_ of only allowing corporate +organizations to reserve namespaces (except in specific scenarios) provides +the following benefits: + +* PyPI would have a constant source of funding for support specialists, + infrastructure maintenance, bug fixes and new features. +* Although each application would require independent review, less human + feedback would be required because the process to approve a paid organization + already bestows a certain amount of trust. + +Terminology +=========== + +Corporate Organization + Corporate organizations are :pep:`organizations <752#organizations>` that + pay for special functionality on PyPI. +Root Grant + A grant as defined by :pep:`PEP 752 terminology <752#terminology>`. +Child Grant + A grant created from a root grant with the associated namespace being a + child namespace as defined by :pep:`PEP 752 terminology <752#terminology>`. + +Implementation +============== + +Grant Applications +------------------ + +Submission +'''''''''' + +Only organizations have access to the page for submitting grant applications. +Reviews of corporate organizations' applications will be prioritized. + +.. _approval-criteria: + +Approval Criteria +''''''''''''''''' + +1. The namespace must not be something common like ``tool`` or ``apps``. +2. The namespace should be greater than three characters. +3. The namespace should properly and clearly identify the reservation owner. +4. The organization should be actively using the namespace. +5. There should be evidence that *not* reserving the namespace may cause + ambiguity, confusion, or other harm to the community. + +Organizations that are not corporate organizations will +represent one of the following: + +* Large, popular open-source projects with many packages +* Universities that actively publish packages +* Government organizations that actively publish packages +* NPOs/NGOs that actively publish packages like + `Our World in Data `__ + +Generally speaking, reviewers should be more tolerant of corporate +organizations that apply for grants for which they are not yet using. + +For example, while it's reasonable to grant a namespace to a startup or an +existing company with a new product line, it's not as reasonable to grant a +namespace to a community project that doesn't have many users. + +Rejections +'''''''''' + +Rejected applications will receive clear rationale for the decision based on +the approval criteria. Applications rejected due to the namespace being too +common will be persisted internally for future reviewers to reference and new +applications attempting to reserve a namespace that was previously rejected +for that reason will display a warning. + +Grant Types +----------- + +There are two types of grants. + +.. _root-grant: + +Root Grant +'''''''''' + +An organization gets a root grant for every approved application. This grant +may produce any number of `child grants `_. + +.. _child-grant: + +Child Grant +''''''''''' + +A child grant may be created by the owner of a `root grant `_ at +any time without approval. The namespace associated with such grants must be a +child namespace of the root grant's namespace. + +Child grants cannot have their own child grants. + +.. _grant-ownership: + +Grant Ownership +--------------- + +The owner of a grant may allow any number of other organizations to use the +grant. The grants behave as if they were owned by the organization. The owner +may revoke this permission at any time. + +The owner may transfer ownership to another organization at any time without +approval from PyPI admins. If the organization is a corporate organization, +the target for transfer must also be a corporate organization. Settings for +permitted organizations are transferred as well. + +.. _user-interface: + +User Interface +-------------- + +Prefix +'''''' + +Every project's page +(`example `__) that +matches an active namespace grant will indicate what the prefix is (NuGet +currently does not do this) and will stand out as a pill or label. This value +will match the ``prefix`` key in the +:pep:`namespace detail API <752#namespace-detail>`. + +Clicking on the namespace will take the user to a page that has more +information such as the current owners, the time at which ownership was granted +and the total number of projects that match the namespace. + +Visual Indicators +''''''''''''''''' + +For projects that match an active namespace grant, users will be able to +quickly ascertain which of the following scenarios apply: + +1. Projects that are tied to a `grant owner `_ will not have + a visual indicator and users should solely rely on the always-present + prefix. +2. Projects that are not tied to a `grant owner `_ and the + matching grant is :pep:`open <752#open-namespaces>` will have a unique + indicator that does not convey mistrust or danger. A good choice might be + the `users `_ icon from Font Awesome or + the `groups`__ icon from Google Fonts. +3. Projects that are not tied to a `grant owner `_ and the + matching grant is restricted will have a unique visual indicator. This + situation arises when the project existed before the grant was created. + The indicator will convey inauthenticity or lack of trust. A good choice + might be a warning sign (⚠). + +__ https://fonts.google.com/icons?selected=Material+Symbols+Outlined:groups + +Open Namespaces +--------------- + +When a `child grant `_ is created, its +:pep:`open <752#open-namespaces>` status will be inherited from the +`root grant `_. Owners of child grants may make them open at any +time. If a grant is open, it cannot be made restricted unless the owner of the +grant is the owner of every project that matches the namespace. + +Root grants given to `community projects `_ should only be +open but is ultimately up to the reviewer of the application. + +Grant Removal +------------- + +If a grant is shared with other organizations, the owner organization must +initiate a transfer as a prerequisite for organization deletion. + +If a grant is not shared, the owner may unclaim the namespace in either of the +following circumstances: + +* The organization manually removes themselves as the owner. +* The organization is deleted. + +When a reserved namespace becomes unclaimed, matching projects will no longer +have a `visual indicator `_. + +How to Teach This +================= + +For organizations, we will document how to reserve namespaces, what the +benefits are and pricing. + +Rejected Ideas +============== + +Page for Viewing All Active Grants +---------------------------------- + +There is no page to view all active namespace grants because this has the +potential to leak private information such as upcoming products. + +Visual Indicator for Owned Projects +----------------------------------- + +There is no indicator for projects that are tied to a +`grant owner `_ primarily to reduce clutter, especially since +this is the most common scenario. + +If there was an indicator, it would not be a check mark or similar as NuGet +chose because it may mistakingly convey that there are associated security +guarantees inherent to the use of the package. Additionally, some social media +platforms use a check mark for verified users which may cause confusion. + +References +========== + +.. [1] The Python Package Index + (https://pypi.org) + +Copyright +========= + +This document is placed in the public domain or under the +CC0-1.0-Universal license, whichever is more permissive.