python:portspolicy

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision		 Previous revision
python:portspolicy [2021/07/23 02:08] – Add Metadata section, add COMMENT guidelines KubilayKocakpython:portspolicy [2023/03/02 02:17] (current) – emphasise case-sensitivity CharlieLi
Line 7: Line 7:
   * As a reference to a well-defined target-state   * As a reference to a well-defined target-state
   * To inform discussions and technical implementations   * To inform discussions and technical implementations
-  * To provide %%FreeBSD%% tesPython Users and Organisations with insight into the Python@ team goals+  * To provide %%FreeBSD%% Python Users and Organisations with insight into the Python@ team goals
   * To orient and focus resources towards common initiatives or goals.   * To orient and focus resources towards common initiatives or goals.
  
Line 20: Line 20:
 ===== Naming ===== ===== Naming =====
  
-==== General ====+==== Prefixing (py-*) ==== 
 + 
 +**Guideline**: Prefix all ports unless Python version is entirely irrelevant.
  
   * Port directory name MUST be lowercase(''%%py-PORTNAME%%'')   * Port directory name MUST be lowercase(''%%py-PORTNAME%%'')
- 
-==== Prefixing (py-*) ==== 
  
   * Python ports MUST be prefixed with ''%%py-%%'', named ''%%category/py-<PORTNAME>%%'', unless there is a compelling case not to.   * Python ports MUST be prefixed with ''%%py-%%'', named ''%%category/py-<PORTNAME>%%'', unless there is a compelling case not to.
Line 34: Line 34:
  
 ==== PORTNAME ==== ==== PORTNAME ====
 +
 +**Guideline**: Match port names to upstream names exactly.
  
 //IMPORTANT// //IMPORTANT//
Line 39: Line 41:
 Check if a package is registered in %%PyPI%% (CHEESESHOP), even when using alternate code sources. Check if a package is registered in %%PyPI%% (CHEESESHOP), even when using alternate code sources.
  
-  * ''%%PORTNAME%%'' MUST be lowercase(PORTNAME) 
-  * ''%%PORTNAME%%'' MUST **exactly** match the //upstream name//. 
   * If the package is registered on %%PyPI%%   * If the package is registered on %%PyPI%%
-    * ''%%PORTNAME%%'' MUST **exactly** match the registered %%PyPI%% package name+    * ''%%PORTNAME%%'' MUST **exactly** match the registered %%PyPI%% package name, **including casing**.
     * The %%PyPI%% package name is that which is displayed in the URL at [[https://pypi.org/]]%%<%%package-name>     * The %%PyPI%% package name is that which is displayed in the URL at [[https://pypi.org/]]%%<%%package-name>
     * Note: The displayed %%PyPI%% package name can be different than the package name specified in ''%%setup.py:name%%''     * Note: The displayed %%PyPI%% package name can be different than the package name specified in ''%%setup.py:name%%''
Line 52: Line 52:
  
 ==== PKGNAMEPREFIX ==== ==== PKGNAMEPREFIX ====
 +
 +**Guideline**: Prefix all ports unless Python version is entirely irrelevant.
  
   * Ports MUST use ''%%PKGNAMEPREFIX%%'', unless there is a compelling case not to.   * Ports MUST use ''%%PKGNAMEPREFIX%%'', unless there is a compelling case not to.
Line 59: Line 61:
  
 ==== CATEGORIES ==== ==== CATEGORIES ====
 +
 +**Guideline**: Always include python category unless use of Python is entirely irrelevant.
  
   * Ports MUST add ''%%python%%'' as a secondary category, unless there is a compelling reason not to.   * Ports MUST add ''%%python%%'' as a secondary category, unless there is a compelling reason not to.
Line 65: Line 69:
 ==== COMMENT ==== ==== COMMENT ====
  
-  * Ports SHOULD match the upstream short description or summary where possible, modulo portlint requirements+**Guideline**: Match upstream metadata as completely and closely as possible. 
 + 
 +  * Ports SHOULD match the upstream short description or summary where possible, modulo requirements and changes for portlint compliance
     * For Python ports, this almost always means what is defined in ''%%setup.py:description%%''     * For Python ports, this almost always means what is defined in ''%%setup.py:description%%''
  
 ===== MASTER_SITES ===== ===== MASTER_SITES =====
  
-Ports SHOULD use ''%%MASTER_SITES=CHEESESHOP%%'' if a Python package is registered on %%PyPI%%, unless there is a compelling (temporary) case not to.+**Guideline**: Use standard Python ecosystem infrastructure whenever possible. 
 + 
 +  * Ports SHOULD use ''%%MASTER_SITES=CHEESESHOP%%'' if a Python package is registered on %%PyPI%%, unless there is a compelling (temporary) case not to.
  
 Examples where temporarily using an alternate MASTER_SITES is warranted: Examples where temporarily using an alternate MASTER_SITES is warranted:
Line 83: Line 91:
  
 ===== USES=python ===== ===== USES=python =====
 +
 +**Guideline**: Python ports are declarative ("this supports x,y,z", not imperative ("install/use x,y,z").
 +**Guideline**: Match upstream metadata as completely and closely as possible.
  
   * Python ports MUST declare USES=python ''%%:<version-spec>%%'' as completely and accurately as possible, without being incorrect, given existing syntax constraints.   * Python ports MUST declare USES=python ''%%:<version-spec>%%'' as completely and accurately as possible, without being incorrect, given existing syntax constraints.
Line 90: Line 101:
  
 ===== USE_PYTHON Features ===== ===== USE_PYTHON Features =====
 +
 +**Guideline**: Use all standard Python ecosystem infrastructure whenever possible.
 +
 +==== pep517 ====
 +
 +  * Packages following PEP-517 (have a pyproject.toml specifying a build backend that builds an installable wheel) SHALL use pep517, unless there is a compelling reason not to.
 +
 +==== distutils ====
 +
 +  * Packages that use distutils (directly executes a setup.py, import distutils/setuptools), SHOULD use distutils, unless there is a compelling reason not to.
  
 ==== autoplist ==== ==== autoplist ====
  
 +  * Packages following PEP-517 (have a pyproject.toml specifying a build backend that builds an installable wheel) and built as such SHALL use autoplist.
   * Packages that use distutils (have a setup.py, import distutils/setuptools), SHOULD use autoplist, unless there is a compelling reason not to.   * Packages that use distutils (have a setup.py, import distutils/setuptools), SHOULD use autoplist, unless there is a compelling reason not to.
  
Line 105: Line 127:
 See Also: https://reviews.freebsd.org/D20927#454268 See Also: https://reviews.freebsd.org/D20927#454268
  
-==== distutils ====+===== Dependencies =====
  
-  * Packages that use distutils (have a setup.py, import distutils/setuptools), SHOULD use distutils, unless there is a compelling reason not to. +**Guideline**: Match upstream metadata as completely and closely as possible.
- +
-===== Dependencies =====+
  
 **IMPORTANT**: **IMPORTANT**:
Line 124: Line 144:
     * Port maintainers SHOULD fix missing or incorrectly specified dependencies, in the port, AND [[Python/PortsPolicy#Upstream|upstream]] the changes.     * Port maintainers SHOULD fix missing or incorrectly specified dependencies, in the port, AND [[Python/PortsPolicy#Upstream|upstream]] the changes.
     * Use common sense for upstream version requirements that set //maximum versions// or pin //very specific// versions, eg: ''%%==%%'', ''%%<=%%'', ''%%<%%''     * Use common sense for upstream version requirements that set //maximum versions// or pin //very specific// versions, eg: ''%%==%%'', ''%%<=%%'', ''%%<%%''
 +      * **IMPORTANT**: Common sense does not create an exception to the //exactly matching dependencies// requirement above.
  
 ==== Modifying Dependencies ==== ==== Modifying Dependencies ====
Line 137: Line 158:
   * Port OPTIONS for optional functionality, SHOULD be enabled by default (defined in OPTIONS_DEFAULT).   * Port OPTIONS for optional functionality, SHOULD be enabled by default (defined in OPTIONS_DEFAULT).
  
-==== Transitive Dependencies ====+==== Optional / Transitive Dependencies ====
  
   * If a package depends on another packages **optional** dependencies, the package MUST depend on those dependencies directly/explicitly.   * If a package depends on another packages **optional** dependencies, the package MUST depend on those dependencies directly/explicitly.
-    * Eg: Package A depends on %%PackageB%%[optional] (defined in extras_require). Package A should depend explicitly on all dependencies listed in Package B's %%%%''%%extras_require{ optional: ..., ...}%%''%%%% list.+    * Example: Package A depends on %%PackageB%%[optional] (defined in extras_require). Package A should depend explicitly on all dependencies listed in Package B's %%%%''%%extras_require{ optional: ..., ...}%%''%%%% list.
  
 ===== Tests ===== ===== Tests =====
 +
 +**Guideline**: Ports should be testable unless they cannot be.
  
   * Python ports SHOULD include a ''%%do-test%%'' target if the package includes tests.   * Python ports SHOULD include a ''%%do-test%%'' target if the package includes tests.
Line 149: Line 172:
  
 ===== Patches ===== ===== Patches =====
 +
 +**Guideline**: Document downstream patches & changes that diverge from upstream.
  
   * Python ports SHOULD [[Python/PortsPolicy#Breadcrumb_Format|document their patches]]   * Python ports SHOULD [[Python/PortsPolicy#Breadcrumb_Format|document their patches]]
Line 155: Line 180:
  
 ===== Upstreaming ===== ===== Upstreaming =====
 +
 +**Guideline**: Upstream is a first priority.
  
   * Python port maintainers SHOULD (strongly encouraged) aim to:   * Python port maintainers SHOULD (strongly encouraged) aim to:
  • python/portspolicy.1627006136.txt.gz
  • Last modified: 2021/07/23 02:08
  • by KubilayKocak