PHEP TBD: Packaging standards

pheps/phep-9999.md

@@ -0,0 +1,153 @@
+```
+PHEP: 9999
+Title: Packaging Standards
+Author: Jonathan T. Niehof <[email protected]> <https://orcid.org/0000-0001-6286-5809>
+Discussions-To: https://github.com/heliophysicsPy/standards/pull/51
+Revision: 1
+Status: Draft
+Type: Standards Track
+Content-Type: text/markdown; charset=UTF-8; variant=CommonMark
+Requires: 4
+Created:
+Post-History: 20-Feb-2026
+Resolution:
+```
+
+# Abstract
+<a name="abstract"></a>
+This PHEP establishes updated standards for packaging of PyHC projects.
+
+# Motivation
+<a name="motivation"></a>
+The consideration of PHEP 4 on package tiering requires a revisit of our standards to clarify how standards relate to various package tiers.
+
+# Rationale
+<a name="rationale"></a>
+PyHC standards GitHub [issue #35](https://github.com/heliophysicsPy/standards/issues/35) opened discussion regarding the existing "testing" and "software maturity" standards. [Fall meeting 2024](https://doi.org/10.5281/zenodo.15080483) discussion indicated that the biggest need in PyHC packaging practices is for community support and documentation, rather than significant new standards. However, several small changes will help standards reflect current practice.
+
+This PHEP makes minor changes to several PyHC standards that relate to packaging and provides additional information on packaging best practices. The rationale for each change is described in the context of the [specification](#specification) below.
+
+# Specification
+<a name="specification"></a>
+Considerable best-practice information is included in [How to Teach This](#how-to-teach-this) but is not considered part of this specification proper.
+
+## Packaging
+
+Modern build systems are essential for easy installation and dependency management, so they are added to this requirement.
+
+The current [PyHC standard 1](https://github.com/heliophysicsPy/standards/blob/main/standards.md#standards) is updated to read:
+
+"Standard #1 **Packaging** (PHEP TBD): All code must be organized and provided as part of installable Python packages. All packages should, and silver/gold tier packages must, use a build system compliant with [PEP517](https://peps.python.org/pep-0517/)/[518](https://peps.python.org/pep-0518/)."
+
+## Releases
+
+Regular releases are essential for distributing packages and so are now required. PyPI is the most common way of accessing Python software and conda-forge is the preferred conda channel for this community.
+
+Several packages have chosen to use versions other than semantic versioning.
+
+Build systems have gotten more complex and harder for an end-user to debug, so wheels are essential.
+
+PyHC standard 3 is updated to read:
+
+"Standard #3 **Releases** (PHEP TBD): All packages must provide releases, and should have a documented release schedule. Releases must be made available through [PyPI](https://pypi.org/). Gold packages must deliver wheels, including binary wheels as relevant, and be available through [conda-forge](https://conda-forge.org/). Gold and silver packages packages must have a documented versioning scheme."
+
+All packages **should** follow the requirements that are specified as **must** for higher tiers.
+
+## Operating System Support
+
+PyHC standard 4 is updated to read:
+
+"Standard #4 **Environment Support** (PHEP TBD): Packages must support common operating systems (e.g., macOS, Linux, Windows) available at time of release, on common architectures (e.g. x86_64 for Linux and Windows, and ARM for macOS)."
+
+## Dependencies
+
+The original standard stated "Projects should import the minimum number of packages necessary. Adding new dependencies should be a considered decision." This standard is in some tension with PyHC's goal of reducing duplication of effort. Modern packaging systems reduce the burden on the end user of dependencies. This recommendation seems too strong as a standard and may be misleading.
+
+PyHC standard 10 is updated to read:
+
+"Standard #10 **Dependencies** (PHEP TBD): This standard has been repealed."
+
+# Backwards Compatibility
+<a name="backwards-compatibility"></a>
+This PHEP makes minor changes to existing PyHC packaging standards, largely to clarify current practice. This should require only minor effort to the majority of packages. Some packages may need to make updates to be evaluated at the Silver tier (or higher). The section "[Changes from the previous standard](#changes-from-the-previous-standard)" may be helpful in preparing such updates.
+
+The best practices are intended in part to improve interoperability between different projects, facilitating e.g. installation into a single environment.
+
+# Security Implications
+<a name="security-implications"></a>
+This PHEP raises no security implications as it does not interact with any executing code or provide any coding standards.
+
+# How to Teach This
+<a name="how-to-teach-this"></a>
+## Standards
+Most standards have minor changes to meet current practice. The approval of this PHEP will help make them and the best practices more visible. Upon approval of this PHEP the included best practices will be advertised at the following telecon, and they will also be provided as a reference for package tiering applications. Reviewers of package tiering should provide feedback related to best practices as an education tool, but not enforce them as part of the review.
+
+For many projects, these standards will require no updates. The key education tool will be project tiering evaluation forms and processes.
+
+### Packaging
+Most modern build systems are compliant with PEP517/518 and following a [packaging guide](#best-practices) should be sufficient to meet this requirement. Older packages which install by direct invocation of `setup.py` need to be updated. For these projects, [setuptools](https://setuptools.pypa.io/) likely offers the simplest migration path, although other build systems may offert other advantages. `setup.py` may be used as part of a PEP517/518 compliant build.
+
+### Releases
+The requirement for wheels, particularly binary wheels, and conda-forge support will require community support for many maintainers. Relevant documentation:
+
+ * [conda-forge recipes](https://github.com/conda-forge/staged-recipes) (see the README)
+
+### Operating system support
+Stricter requirements on OS and architecture support will mostly affect maintainers of compiled code, and the needs will be project-specific.
+
+### Changes from the previous standard
+<a name="changes-from-the-previous-standard"></a>
+This PHEP makes the following changes relative to the original standards from 2018; projects compliant with the previous standards should only need to review this section:
+
+ * Standard 1, "Packaging", now requires PEP517/518 compliant build.
+ * Standard 3, "Releases":
+     * requires releases rather than "striving" and recommends a consistent schedule.
+     * requires rather than recommending PyPI.
+     * requires wheels for gold and recommends for other tiers.
+     * recommends conda-forge specifically, rather than other conda channels, and requires it at gold.
+     * removes the semantic versioning requirement in favor of a documented versioning scheme for silver and gold.
+ * Standard 4, "Environment support", requires support on common OS's rather than a "striving", and adds a requirement for support on common architectures.
+ * Standard 10, "Dependencies", has been repealed.
+
+## Best practices
+<a name="best-practices"></a>
+Maintainers of PyHC packages are encouraged to follow one of the existing packaging guides available in the scientific Python community:
+
+  * [pyOpenSci Python packaging guide](https://www.pyopensci.org/python-package-guide/), including several tutorials and references.
+  * [Scientific "simple packaging" guide](https://learn.scientific-python.org/development/guides/packaging-simple/), which also includes links that may be useful in less-simple packaging cases.
+  * [cibuildwheel](https://cibuildwheel.pypa.io/) is a project to simplify the building of wheels.
+
+The [versioning guide](https://www.pyopensci.org/python-package-guide/package-structure-code/python-package-versions.html) from pyOpenSci provides a lot of information on versioning strategy and tools, although it is [semantic versioning](https://www.semver.org) specific.
+
+[Reference Implementations](#reference-implementations) provides examples of how these best practices are used in PyHC and other projects.
+
+# Reference Implementations
+<a name="reference-implementations"></a>
+Several PyHC projects provide examples of best practices for packaging, and they should be provided here.
+
+# Rejected Ideas
+<a name="rejected-ideas"></a>
+Consideration was given to adopting pyOpenSci standards in lieu of our own. However, the pyOpenSci [packaging guide](https://www.pyopensci.org/python-package-guide/) is mostly a how-to document rather than a standard. Their [packaging requirements](https://www.pyopensci.org/software-peer-review/how-to/author-guide.html#does-your-package-meet-packaging-requirements) are provided as a part of their peer review guide and touch on elements other than packaging, including aspects of other PyHC standards. The pyOpenSci resources are useful but do not seem to substitute for PyHC standards needs.
+
+# Open Issues
+<a name="open-issues"></a>
+An explicit requirement on PEP517/518 may not be necessary, as any package following a reasonably current packaging guide will automatically be doing so. PyPI support is required at the bronze tier, but PEP517/518 is only "should" at this tier--it's not clear this is even possible.
+
+Examples for reference implementations are needed, particularly if there is any information on *how* the implementations can be reproduced. Be bold and point out where your project does well!
+
+# Revisions
+Revision 1 (pending): Initial approval.
+
+# Copyright
+<a name="copyright"></a>
+This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive. It should be cited as:
+```
+@techreport(phep9999,
+  author = {Jonathan T. Niehof},
+  title  = {Packaging Standards},
+    year = {2026},
+    type = {PHEP},
+  number = {9999},
+     doi = {10.5281/zenodo.XXXXXXXX}
+)
+```