PHEP TBD: Development standards

pheps/phep-9999.md

@@ -0,0 +1,135 @@
+```
+PHEP: 9999
+Title: Development Standards
+Author: Jonathan T. Niehof <jtniehof@gmail.com> <https://orcid.org/0000-0001-6286-5809>
+Discussions-To: https://github.com/heliophysicsPy/standards/pull/52
+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 development and testing 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 development practices is for community support and documentation, rather than significant new standards. However, several small changes will clarify standards and help them reflect current practice.
+
+This PHEP makes minor changes to PyHC standards that relate to development approach. It also collects substantial best practices information from the community.
+
+# 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.
+
+## Coding Style
+The current [PyHC standard 7](https://github.com/heliophysicsPy/standards/blob/main/standards.md#standards) is updated to read:
+
+"Standard #7 **Coding Style** (PHEP TBD): "Projects must adopt the basic style recommendations of [PEP 8](https://www.python.org/dev/peps/pep-0008/). Projects that use static analysis tools for code checking should do so in continuous integration."
+
+## Testing
+
+PyHC standard 9 is updated to read:
+
+"Standard #9 **Testing** (PHEP TBD): Stable packages must provide unit tests of individual components (e.g. functions, classes) as well as integration tests that test the interaction between components that covers most of the code. Testing coverage should be measured and data coverage considered. Automated testing is recommended, in which tests are run before any code is merged. System and [acceptance](https://agilealliance.org/glossary/acceptance-testing/) testing are also recommended."
+
+
+## Binaries
+PyHC standard 14 is updated to read:
+
+"Standard #14 **Binaries** (PHEP TBD): Packages should not include large binary files in their repository, as they can make history difficult to follow and make the repository large. Small (<100kiB) binaries may be appropriate."
+
+
+# Backwards Compatibility
+<a name="backwards-compatibility"></a>
+This PHEP makes very minor changes to existing PyHC packaging standards, which should not require updates to packages. The section "[Changes from the previous standard](#changes-from-the-previous-standard)" may be helpful in deciding if updates are needed.
+
+# 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
+Standards have minor changes to meet current practice, although there are no changes to "musts". 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.
+
+The [pyOpenSci Python packaging guide](https://www.pyopensci.org/python-package-guide/) provides information on code style, testing, and continuous integration.
+
+### 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 7, "Coding Style": Rather than recommending static tools as such, recommends using CI *if* using static analysis tools.
+ * Standard 9, "Testing": Mentions data coverage and provide definition of acceptance testing.
+ * Standard 14, "Binaries": Provides a specific cutoff number and removes mention of notebooks; these recommendations are moved to [best practices](#best-practices).
+
+## Best practices
+<a name="best-practices"></a>
+Suggested tools for static analysis of code include:
+
+  * [black](https://black.readthedocs.io/)
+  * [flake8](https://flake8.pycqa.org/)
+  * [pycodestyle](https://pycodestyle.pycqa.org/)
+  * [pylint](https://www.pylint.org/)
+  * [ruff](https://docs.astral.sh/ruff/)
+
+Automatic checking and/or automatic fixing can reduce developer effort, and can be done in continuous integration or with tools such as [pre-commit](https://pre-commit.com/).
+
+It can be difficult for somebody unfamiliar with a project to figure out how to run the tests. Include this information in your documentation. Consider how the tests and test data are packaged in the repository and potentially via `pip install`; people who do not normally develop on a project may need to run tests across multiple projects for combined environments like the [PyHC docker environment](https://github.com/heliophysicsPy/pyhc-docker-environment).
+
+[Reference Implementations](#reference-implementations) provides examples of how these best practices are used in PyHC and other projects.
+
+### Binaries
+There are several approaches to handling the use case of binaries in the repository:
+
+  * Include the binary in another repository (not necessarily a code repository) and link it.
+  * Generate the binary on-the-fly at installation or testing time.
+  * Use alternative file formats, e.g. [Jupytext](https://jupytext.readthedocs.io/) for Jupyter notebooks.
+  * If a binary must be included in the repository for testing, do not include it in the wheel or installed files.
+
+# Reference Implementations
+<a name="reference-implementations"></a>
+Several PyHC projects provide examples of best practices for development practices, and they should be provided here.
+
+[pyspedas](https://github.com/spedas/pyspedas?tab=readme-ov-file) provides automated tests, static checks, and coverage (do we have a better place to link in the repository?). It uses [coveralls](https://coveralls.io/) for [test coverage](https://coveralls.io/github/spedas/pyspedas): [workflow configuration](https://github.com/spedas/pyspedas/blob/master/.github/workflows/pythonpackage.yml).
+
+[IMAP](https://github.com/IMAP-Science-Operations-Center/imap_processing/) does automated coverage checks using [codecov and GitHub actions](https://about.codecov.io/tool/github-actions/): [testing workflow configuration](https://github.com/IMAP-Science-Operations-Center/imap_processing/blob/dev/.github/workflows/test.yml); [codecov configuration](https://github.com/IMAP-Science-Operations-Center/imap_processing/blob/dev/codecov.yml).
+
+Other coverage options include [using GHA directly](https://hynek.me/articles/ditch-codecov-python/).
+
+# Rejected Ideas
+<a name="rejected-ideas"></a>
+
+# Open Issues
+<a name="open-issues"></a>
+Do we want suggestions for packaging tests to make testing in the combined environments easier?
+
+Examples for reference implementations are needed, particularly if there is any information on *how* the implementations can be reproduced. Be bold and point out what 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  = {Development Standards},
+    year = {2026},
+    type = {PHEP},
+  number = {9999},
+     doi = {10.5281/zenodo.XXXXXXXX}
+)
+```