From 2c73a8428e564b10e19c43789657b74a94414545 Mon Sep 17 00:00:00 2001 From: sapols Date: Thu, 6 Jun 2024 14:16:30 -0600 Subject: [PATCH 01/20] Initial draft of new PHEP --- pheps/phep-9999.md | 147 ++++++++++++++++++++++ pheps/phep-9999/python-support-window.svg | 1 + 2 files changed, 148 insertions(+) create mode 100644 pheps/phep-9999.md create mode 100644 pheps/phep-9999/python-support-window.svg diff --git a/pheps/phep-9999.md b/pheps/phep-9999.md new file mode 100644 index 0000000..910a1ff --- /dev/null +++ b/pheps/phep-9999.md @@ -0,0 +1,147 @@ +``` +PHEP: 9999 +Title: PyHC Python Support Policy +Author: Shawn Polson +Discussions-To: https://github.com/heliophysicsPy/standards/issues/21 +Revision: 1 +Status: Draft +Type: Standards Track +Content-Type: text/markdown; charset=UTF-8; variant=CommonMark +Created: 06-Jun-2024 +Post-History: 06-Jun-2024 +``` + +# Abstract + +This PHEP recommends that all projects across the PyHC ecosystem adopt a common time-based policy for support of Python versions, similar to [NEP 29](https://numpy.org/neps/nep-0029-deprecation_policy.html) and [SPEC-0](https://scientific-python.org/specs/spec-0000/). Specifically, it recommends that: +1. Support for Python versions be dropped **42 months** (3.5 years) after their initial release. +2. New Python versions be adopted within **6 months** of their release. + +This policy will replace the current standard [#11](https://github.com/heliophysicsPy/standards/blob/main/standards.md#standards) which simply mandates Python 3 support. + +# Motivation + +The current PyHC standard [#11](https://github.com/heliophysicsPy/standards/blob/main/standards.md#standards), which mandates compatibility with Python 3, is outdated. Python 3 support is virtually universal now, so it would be more benefitial to replace this standard with a policy for how to support new minor Python versions. [NEP 29](https://numpy.org/neps/nep-0029-deprecation_policy.html) and [SPEC-0](https://scientific-python.org/specs/spec-0000/) provide a structured support timeline that balances stability and progress, essential for software in the heliophysics community. Adopting a similar policy ensures consistency and predictability in support timelines. Additionally, limiting the scope of supported Python versions is an effective way for packages to limit maintenance burden while promoting interoperability. + +# Rationale + +Following [NEP 29](https://numpy.org/neps/nep-0029-deprecation_policy.html)'s 42-month support timeline ensures that PyHC packages maintain compatibility with newer Python features while providing adequate time for package maintainers to adapt. Allowing 6 months to adopt new Python versions ensures packages stay current with Python's development cycle while providing a reasonable timeframe for testing and integration. + +# Specification + +This PHEP refers to feature releases of Python, i.e., updates to the minor version assuming semantic versioning (e.g., Python 3.12.0, not Python 3.12.1). + +This PHEP specifies that all PyHC packages should: +1. Drop support for Python versions **42 months** (3.5 years) after their initial release. +2. Adopt support for new Python versions within **6 months** of their release. + +Since new minor Python versions are released annually every October ([PEP 602](https://peps.python.org/pep-0602/)), this effectively means that PyHC packages should be supporting about three minor Python versions at any given time. Packages should be tested against the minimum and maximum supported versions of Python. + +![Python Support Window](phep-9999/python-support-window.svg) + +This new policy will replace the current standard [#11](https://github.com/heliophysicsPy/standards/blob/main/standards.md#standards) in the PyHC standards document with the following new text: + +> **Python Support:** All packages must support minor Python versions released only within the past 42 months (3.5 years). Additionally, packages must support new minor Python versions within 6 months of their release (see [PHEP 9999](???)). + +# Backwards Compatibility + +This policy introduces backwards incompatibilities by enforcing a new support timeline, which may require some packages to drop support for older Python versions sooner than planned. Packages currently supporting versions outside this window will need updates to comply with the new standard. + +# Security Implications + +There are no direct security implications of this policy. However, ensuring packages are updated to newer Python versions may indirectly improve security by incorporating fixes and improvements from newer releases. + +# How to Teach This + +A new web page under the PyHC Projects page detailing the support schedule? (Similar to the Gantt chart in SPEC-0?) + +# Reference Implementation + +Multiple PyHC packages already follow this Python version support policy. One notable example is PlasmaPy which currently comments this policy above the `requires-python` line in their [pyproject.toml](https://github.com/PlasmaPy/PlasmaPy/blob/main/pyproject.toml#L24-L27) file. + +## Code to generate support and drop schedule tables: +```python +import pandas as pd +from datetime import datetime, timedelta + +# Define the release dates of the Python versions +py_releases = { + "3.9": "Oct 5, 2020", + "3.10": "Oct 4, 2021", + "3.11": "Oct 24, 2022", + "3.12": "Oct 2, 2023", +} + +# Define the support periods of 3.5 years / 6 months +plus42 = timedelta(days=int(365*3.5 + 1)) +plus6 = timedelta(days=int(365 * 0.5)) + +# Create a DataFrame from the predefined py_releases data +data = [] +for version, release_date in py_releases.items(): + release_date_dt = datetime.strptime(release_date, "%b %d, %Y") + drop_date_dt = release_date_dt + plus42 + support_by_dt = release_date_dt + plus6 + data.append((version, release_date_dt, support_by_dt, drop_date_dt)) + +# Create a DataFrame +df = pd.DataFrame(data, columns=["python version", "release", "support by", "drop"]) +df["quarter"] = df["drop"].dt.to_period("Q") + +# Save the DataFrame to a CSV file +df.to_csv('python_version_support_schedule.csv', index=False) + +# Generate Mermaid syntax for the Gantt chart +mermaid_gantt = """gantt + dateFormat YYYY-MM-DD + title Python Version Support Window + axisFormat %m / %Y + + section python +""" + +for _, row in df.iterrows(): + mermaid_gantt += f" {row['python version']} : {row['release'].strftime('%Y-%m-%d')},{row['drop'].strftime('%Y-%m-%d')}\n" + +# Save the Mermaid syntax to a Markdown file +# The Mermaid Gantt chart syntax is saved in 'python_version_support_gantt.md'. +# You can paste the content of that file into https://mermaid.live/ to generate the chart image. +with open("python_version_support_chart.md", "w") as file: + file.write(mermaid_gantt) + +print("Version support schedule saved to 'python_version_support_schedule.csv'") +print("Mermaid Gantt chart syntax saved to 'python_version_support_chart.md' (render at https://mermaid.live/)") +``` + +# Rejected Ideas + +[SPEC-0](https://scientific-python.org/specs/spec-0000/)'s 36-month support timeline was considered instead of [NEP 29](https://numpy.org/neps/nep-0029-deprecation_policy.html)'s 42 months, but it was ultimately decided that the extra stability of 42 months is more desirable. + +# Open Issues + +1. This PHEP recommends supporting Python versions for 42 months (3.5 years) which is in line with [NEP 29](https://numpy.org/neps/nep-0029-deprecation_policy.html), _not_ 36 months (3 years) as recommended by [SPEC-0](https://scientific-python.org/specs/spec-0000/). The thinking is that 42 months is more linient and therefore less of a burden to the community, but is that the right call? Should it be 36 months instead? +2. Should we adopt the 2-year core package support policy from SPEC-0 in a separate PHEP? (`numpy, scipy, matplotlib, pandas, scikit-image, networkx, scikit-learn, xarray, ipython, zarr`) + +# Footnotes + +1. NEP 29: https://numpy.org/neps/nep-0029-deprecation_policy.html +2. SPEC-0: https://scientific-python.org/specs/spec-0000/ + +# Revisions + +Revision 1 (06-Jun-2024): Initial draft. + +# Copyright + +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 = {Shawn Polson}, + title = {PyHC Python Support Policy}, + year = {2024}, + type = {PHEP}, + number = {9999}, + doi = {10.5281/zenodo.xxxxxxx} +) +``` diff --git a/pheps/phep-9999/python-support-window.svg b/pheps/phep-9999/python-support-window.svg new file mode 100644 index 0000000..fc6a9c4 --- /dev/null +++ b/pheps/phep-9999/python-support-window.svg @@ -0,0 +1 @@ + 01 / 2021 01 / 2022 01 / 2023 01 / 2024 01 / 2025 01 / 2026 01 / 20273.9 3.10 3.11 3.12 python Python Version Support Window \ No newline at end of file From 1b9ff9caa6a34a73e365cc91d6e5c1b4c15799c0 Mon Sep 17 00:00:00 2001 From: sapols Date: Thu, 6 Jun 2024 14:21:04 -0600 Subject: [PATCH 02/20] Update 'Discussions-To' link --- pheps/phep-9999.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pheps/phep-9999.md b/pheps/phep-9999.md index 910a1ff..12ea746 100644 --- a/pheps/phep-9999.md +++ b/pheps/phep-9999.md @@ -2,7 +2,7 @@ PHEP: 9999 Title: PyHC Python Support Policy Author: Shawn Polson -Discussions-To: https://github.com/heliophysicsPy/standards/issues/21 +Discussions-To: https://github.com/heliophysicsPy/standards/pull/29 Revision: 1 Status: Draft Type: Standards Track From 60fde5a308fa3696566df4132b1af3fbdf9c288a Mon Sep 17 00:00:00 2001 From: sapols Date: Thu, 6 Jun 2024 16:58:10 -0600 Subject: [PATCH 03/20] Assign PHEP number 3 --- pheps/phep-9999.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/pheps/phep-9999.md b/pheps/phep-9999.md index 12ea746..d8e8058 100644 --- a/pheps/phep-9999.md +++ b/pheps/phep-9999.md @@ -1,5 +1,5 @@ ``` -PHEP: 9999 +PHEP: 3 Title: PyHC Python Support Policy Author: Shawn Polson Discussions-To: https://github.com/heliophysicsPy/standards/pull/29 @@ -136,12 +136,12 @@ Revision 1 (06-Jun-2024): Initial draft. 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, +@techreport(phep3, author = {Shawn Polson}, title = {PyHC Python Support Policy}, year = {2024}, type = {PHEP}, - number = {9999}, + number = {3}, doi = {10.5281/zenodo.xxxxxxx} ) ``` From fdc4c47e511a1eb94c1da97cc27e3f21cedef375 Mon Sep 17 00:00:00 2001 From: sapols Date: Thu, 6 Jun 2024 17:01:08 -0600 Subject: [PATCH 04/20] Rename files to match PHEP number --- pheps/phep-0003.md | 147 ++++++++++++++++++++++ pheps/phep-0003/python-support-window.svg | 1 + 2 files changed, 148 insertions(+) create mode 100644 pheps/phep-0003.md create mode 100644 pheps/phep-0003/python-support-window.svg diff --git a/pheps/phep-0003.md b/pheps/phep-0003.md new file mode 100644 index 0000000..d8e8058 --- /dev/null +++ b/pheps/phep-0003.md @@ -0,0 +1,147 @@ +``` +PHEP: 3 +Title: PyHC Python Support Policy +Author: Shawn Polson +Discussions-To: https://github.com/heliophysicsPy/standards/pull/29 +Revision: 1 +Status: Draft +Type: Standards Track +Content-Type: text/markdown; charset=UTF-8; variant=CommonMark +Created: 06-Jun-2024 +Post-History: 06-Jun-2024 +``` + +# Abstract + +This PHEP recommends that all projects across the PyHC ecosystem adopt a common time-based policy for support of Python versions, similar to [NEP 29](https://numpy.org/neps/nep-0029-deprecation_policy.html) and [SPEC-0](https://scientific-python.org/specs/spec-0000/). Specifically, it recommends that: +1. Support for Python versions be dropped **42 months** (3.5 years) after their initial release. +2. New Python versions be adopted within **6 months** of their release. + +This policy will replace the current standard [#11](https://github.com/heliophysicsPy/standards/blob/main/standards.md#standards) which simply mandates Python 3 support. + +# Motivation + +The current PyHC standard [#11](https://github.com/heliophysicsPy/standards/blob/main/standards.md#standards), which mandates compatibility with Python 3, is outdated. Python 3 support is virtually universal now, so it would be more benefitial to replace this standard with a policy for how to support new minor Python versions. [NEP 29](https://numpy.org/neps/nep-0029-deprecation_policy.html) and [SPEC-0](https://scientific-python.org/specs/spec-0000/) provide a structured support timeline that balances stability and progress, essential for software in the heliophysics community. Adopting a similar policy ensures consistency and predictability in support timelines. Additionally, limiting the scope of supported Python versions is an effective way for packages to limit maintenance burden while promoting interoperability. + +# Rationale + +Following [NEP 29](https://numpy.org/neps/nep-0029-deprecation_policy.html)'s 42-month support timeline ensures that PyHC packages maintain compatibility with newer Python features while providing adequate time for package maintainers to adapt. Allowing 6 months to adopt new Python versions ensures packages stay current with Python's development cycle while providing a reasonable timeframe for testing and integration. + +# Specification + +This PHEP refers to feature releases of Python, i.e., updates to the minor version assuming semantic versioning (e.g., Python 3.12.0, not Python 3.12.1). + +This PHEP specifies that all PyHC packages should: +1. Drop support for Python versions **42 months** (3.5 years) after their initial release. +2. Adopt support for new Python versions within **6 months** of their release. + +Since new minor Python versions are released annually every October ([PEP 602](https://peps.python.org/pep-0602/)), this effectively means that PyHC packages should be supporting about three minor Python versions at any given time. Packages should be tested against the minimum and maximum supported versions of Python. + +![Python Support Window](phep-9999/python-support-window.svg) + +This new policy will replace the current standard [#11](https://github.com/heliophysicsPy/standards/blob/main/standards.md#standards) in the PyHC standards document with the following new text: + +> **Python Support:** All packages must support minor Python versions released only within the past 42 months (3.5 years). Additionally, packages must support new minor Python versions within 6 months of their release (see [PHEP 9999](???)). + +# Backwards Compatibility + +This policy introduces backwards incompatibilities by enforcing a new support timeline, which may require some packages to drop support for older Python versions sooner than planned. Packages currently supporting versions outside this window will need updates to comply with the new standard. + +# Security Implications + +There are no direct security implications of this policy. However, ensuring packages are updated to newer Python versions may indirectly improve security by incorporating fixes and improvements from newer releases. + +# How to Teach This + +A new web page under the PyHC Projects page detailing the support schedule? (Similar to the Gantt chart in SPEC-0?) + +# Reference Implementation + +Multiple PyHC packages already follow this Python version support policy. One notable example is PlasmaPy which currently comments this policy above the `requires-python` line in their [pyproject.toml](https://github.com/PlasmaPy/PlasmaPy/blob/main/pyproject.toml#L24-L27) file. + +## Code to generate support and drop schedule tables: +```python +import pandas as pd +from datetime import datetime, timedelta + +# Define the release dates of the Python versions +py_releases = { + "3.9": "Oct 5, 2020", + "3.10": "Oct 4, 2021", + "3.11": "Oct 24, 2022", + "3.12": "Oct 2, 2023", +} + +# Define the support periods of 3.5 years / 6 months +plus42 = timedelta(days=int(365*3.5 + 1)) +plus6 = timedelta(days=int(365 * 0.5)) + +# Create a DataFrame from the predefined py_releases data +data = [] +for version, release_date in py_releases.items(): + release_date_dt = datetime.strptime(release_date, "%b %d, %Y") + drop_date_dt = release_date_dt + plus42 + support_by_dt = release_date_dt + plus6 + data.append((version, release_date_dt, support_by_dt, drop_date_dt)) + +# Create a DataFrame +df = pd.DataFrame(data, columns=["python version", "release", "support by", "drop"]) +df["quarter"] = df["drop"].dt.to_period("Q") + +# Save the DataFrame to a CSV file +df.to_csv('python_version_support_schedule.csv', index=False) + +# Generate Mermaid syntax for the Gantt chart +mermaid_gantt = """gantt + dateFormat YYYY-MM-DD + title Python Version Support Window + axisFormat %m / %Y + + section python +""" + +for _, row in df.iterrows(): + mermaid_gantt += f" {row['python version']} : {row['release'].strftime('%Y-%m-%d')},{row['drop'].strftime('%Y-%m-%d')}\n" + +# Save the Mermaid syntax to a Markdown file +# The Mermaid Gantt chart syntax is saved in 'python_version_support_gantt.md'. +# You can paste the content of that file into https://mermaid.live/ to generate the chart image. +with open("python_version_support_chart.md", "w") as file: + file.write(mermaid_gantt) + +print("Version support schedule saved to 'python_version_support_schedule.csv'") +print("Mermaid Gantt chart syntax saved to 'python_version_support_chart.md' (render at https://mermaid.live/)") +``` + +# Rejected Ideas + +[SPEC-0](https://scientific-python.org/specs/spec-0000/)'s 36-month support timeline was considered instead of [NEP 29](https://numpy.org/neps/nep-0029-deprecation_policy.html)'s 42 months, but it was ultimately decided that the extra stability of 42 months is more desirable. + +# Open Issues + +1. This PHEP recommends supporting Python versions for 42 months (3.5 years) which is in line with [NEP 29](https://numpy.org/neps/nep-0029-deprecation_policy.html), _not_ 36 months (3 years) as recommended by [SPEC-0](https://scientific-python.org/specs/spec-0000/). The thinking is that 42 months is more linient and therefore less of a burden to the community, but is that the right call? Should it be 36 months instead? +2. Should we adopt the 2-year core package support policy from SPEC-0 in a separate PHEP? (`numpy, scipy, matplotlib, pandas, scikit-image, networkx, scikit-learn, xarray, ipython, zarr`) + +# Footnotes + +1. NEP 29: https://numpy.org/neps/nep-0029-deprecation_policy.html +2. SPEC-0: https://scientific-python.org/specs/spec-0000/ + +# Revisions + +Revision 1 (06-Jun-2024): Initial draft. + +# Copyright + +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(phep3, + author = {Shawn Polson}, + title = {PyHC Python Support Policy}, + year = {2024}, + type = {PHEP}, + number = {3}, + doi = {10.5281/zenodo.xxxxxxx} +) +``` diff --git a/pheps/phep-0003/python-support-window.svg b/pheps/phep-0003/python-support-window.svg new file mode 100644 index 0000000..fc6a9c4 --- /dev/null +++ b/pheps/phep-0003/python-support-window.svg @@ -0,0 +1 @@ + 01 / 2021 01 / 2022 01 / 2023 01 / 2024 01 / 2025 01 / 2026 01 / 20273.9 3.10 3.11 3.12 python Python Version Support Window \ No newline at end of file From 466d08098ec51a1034c535be24bfec1ec71f7af3 Mon Sep 17 00:00:00 2001 From: sapols Date: Thu, 6 Jun 2024 17:01:51 -0600 Subject: [PATCH 05/20] Delete old files from before rename --- pheps/phep-9999.md | 147 ---------------------- pheps/phep-9999/python-support-window.svg | 1 - 2 files changed, 148 deletions(-) delete mode 100644 pheps/phep-9999.md delete mode 100644 pheps/phep-9999/python-support-window.svg diff --git a/pheps/phep-9999.md b/pheps/phep-9999.md deleted file mode 100644 index d8e8058..0000000 --- a/pheps/phep-9999.md +++ /dev/null @@ -1,147 +0,0 @@ -``` -PHEP: 3 -Title: PyHC Python Support Policy -Author: Shawn Polson -Discussions-To: https://github.com/heliophysicsPy/standards/pull/29 -Revision: 1 -Status: Draft -Type: Standards Track -Content-Type: text/markdown; charset=UTF-8; variant=CommonMark -Created: 06-Jun-2024 -Post-History: 06-Jun-2024 -``` - -# Abstract - -This PHEP recommends that all projects across the PyHC ecosystem adopt a common time-based policy for support of Python versions, similar to [NEP 29](https://numpy.org/neps/nep-0029-deprecation_policy.html) and [SPEC-0](https://scientific-python.org/specs/spec-0000/). Specifically, it recommends that: -1. Support for Python versions be dropped **42 months** (3.5 years) after their initial release. -2. New Python versions be adopted within **6 months** of their release. - -This policy will replace the current standard [#11](https://github.com/heliophysicsPy/standards/blob/main/standards.md#standards) which simply mandates Python 3 support. - -# Motivation - -The current PyHC standard [#11](https://github.com/heliophysicsPy/standards/blob/main/standards.md#standards), which mandates compatibility with Python 3, is outdated. Python 3 support is virtually universal now, so it would be more benefitial to replace this standard with a policy for how to support new minor Python versions. [NEP 29](https://numpy.org/neps/nep-0029-deprecation_policy.html) and [SPEC-0](https://scientific-python.org/specs/spec-0000/) provide a structured support timeline that balances stability and progress, essential for software in the heliophysics community. Adopting a similar policy ensures consistency and predictability in support timelines. Additionally, limiting the scope of supported Python versions is an effective way for packages to limit maintenance burden while promoting interoperability. - -# Rationale - -Following [NEP 29](https://numpy.org/neps/nep-0029-deprecation_policy.html)'s 42-month support timeline ensures that PyHC packages maintain compatibility with newer Python features while providing adequate time for package maintainers to adapt. Allowing 6 months to adopt new Python versions ensures packages stay current with Python's development cycle while providing a reasonable timeframe for testing and integration. - -# Specification - -This PHEP refers to feature releases of Python, i.e., updates to the minor version assuming semantic versioning (e.g., Python 3.12.0, not Python 3.12.1). - -This PHEP specifies that all PyHC packages should: -1. Drop support for Python versions **42 months** (3.5 years) after their initial release. -2. Adopt support for new Python versions within **6 months** of their release. - -Since new minor Python versions are released annually every October ([PEP 602](https://peps.python.org/pep-0602/)), this effectively means that PyHC packages should be supporting about three minor Python versions at any given time. Packages should be tested against the minimum and maximum supported versions of Python. - -![Python Support Window](phep-9999/python-support-window.svg) - -This new policy will replace the current standard [#11](https://github.com/heliophysicsPy/standards/blob/main/standards.md#standards) in the PyHC standards document with the following new text: - -> **Python Support:** All packages must support minor Python versions released only within the past 42 months (3.5 years). Additionally, packages must support new minor Python versions within 6 months of their release (see [PHEP 9999](???)). - -# Backwards Compatibility - -This policy introduces backwards incompatibilities by enforcing a new support timeline, which may require some packages to drop support for older Python versions sooner than planned. Packages currently supporting versions outside this window will need updates to comply with the new standard. - -# Security Implications - -There are no direct security implications of this policy. However, ensuring packages are updated to newer Python versions may indirectly improve security by incorporating fixes and improvements from newer releases. - -# How to Teach This - -A new web page under the PyHC Projects page detailing the support schedule? (Similar to the Gantt chart in SPEC-0?) - -# Reference Implementation - -Multiple PyHC packages already follow this Python version support policy. One notable example is PlasmaPy which currently comments this policy above the `requires-python` line in their [pyproject.toml](https://github.com/PlasmaPy/PlasmaPy/blob/main/pyproject.toml#L24-L27) file. - -## Code to generate support and drop schedule tables: -```python -import pandas as pd -from datetime import datetime, timedelta - -# Define the release dates of the Python versions -py_releases = { - "3.9": "Oct 5, 2020", - "3.10": "Oct 4, 2021", - "3.11": "Oct 24, 2022", - "3.12": "Oct 2, 2023", -} - -# Define the support periods of 3.5 years / 6 months -plus42 = timedelta(days=int(365*3.5 + 1)) -plus6 = timedelta(days=int(365 * 0.5)) - -# Create a DataFrame from the predefined py_releases data -data = [] -for version, release_date in py_releases.items(): - release_date_dt = datetime.strptime(release_date, "%b %d, %Y") - drop_date_dt = release_date_dt + plus42 - support_by_dt = release_date_dt + plus6 - data.append((version, release_date_dt, support_by_dt, drop_date_dt)) - -# Create a DataFrame -df = pd.DataFrame(data, columns=["python version", "release", "support by", "drop"]) -df["quarter"] = df["drop"].dt.to_period("Q") - -# Save the DataFrame to a CSV file -df.to_csv('python_version_support_schedule.csv', index=False) - -# Generate Mermaid syntax for the Gantt chart -mermaid_gantt = """gantt - dateFormat YYYY-MM-DD - title Python Version Support Window - axisFormat %m / %Y - - section python -""" - -for _, row in df.iterrows(): - mermaid_gantt += f" {row['python version']} : {row['release'].strftime('%Y-%m-%d')},{row['drop'].strftime('%Y-%m-%d')}\n" - -# Save the Mermaid syntax to a Markdown file -# The Mermaid Gantt chart syntax is saved in 'python_version_support_gantt.md'. -# You can paste the content of that file into https://mermaid.live/ to generate the chart image. -with open("python_version_support_chart.md", "w") as file: - file.write(mermaid_gantt) - -print("Version support schedule saved to 'python_version_support_schedule.csv'") -print("Mermaid Gantt chart syntax saved to 'python_version_support_chart.md' (render at https://mermaid.live/)") -``` - -# Rejected Ideas - -[SPEC-0](https://scientific-python.org/specs/spec-0000/)'s 36-month support timeline was considered instead of [NEP 29](https://numpy.org/neps/nep-0029-deprecation_policy.html)'s 42 months, but it was ultimately decided that the extra stability of 42 months is more desirable. - -# Open Issues - -1. This PHEP recommends supporting Python versions for 42 months (3.5 years) which is in line with [NEP 29](https://numpy.org/neps/nep-0029-deprecation_policy.html), _not_ 36 months (3 years) as recommended by [SPEC-0](https://scientific-python.org/specs/spec-0000/). The thinking is that 42 months is more linient and therefore less of a burden to the community, but is that the right call? Should it be 36 months instead? -2. Should we adopt the 2-year core package support policy from SPEC-0 in a separate PHEP? (`numpy, scipy, matplotlib, pandas, scikit-image, networkx, scikit-learn, xarray, ipython, zarr`) - -# Footnotes - -1. NEP 29: https://numpy.org/neps/nep-0029-deprecation_policy.html -2. SPEC-0: https://scientific-python.org/specs/spec-0000/ - -# Revisions - -Revision 1 (06-Jun-2024): Initial draft. - -# Copyright - -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(phep3, - author = {Shawn Polson}, - title = {PyHC Python Support Policy}, - year = {2024}, - type = {PHEP}, - number = {3}, - doi = {10.5281/zenodo.xxxxxxx} -) -``` diff --git a/pheps/phep-9999/python-support-window.svg b/pheps/phep-9999/python-support-window.svg deleted file mode 100644 index fc6a9c4..0000000 --- a/pheps/phep-9999/python-support-window.svg +++ /dev/null @@ -1 +0,0 @@ - 01 / 2021 01 / 2022 01 / 2023 01 / 2024 01 / 2025 01 / 2026 01 / 20273.9 3.10 3.11 3.12 python Python Version Support Window \ No newline at end of file From 46e95222ca3ac15312bbd6958f6c375e10e4feca Mon Sep 17 00:00:00 2001 From: sapols Date: Thu, 6 Jun 2024 17:03:38 -0600 Subject: [PATCH 06/20] Update image path --- pheps/phep-0003.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pheps/phep-0003.md b/pheps/phep-0003.md index d8e8058..abd5041 100644 --- a/pheps/phep-0003.md +++ b/pheps/phep-0003.md @@ -37,7 +37,7 @@ This PHEP specifies that all PyHC packages should: Since new minor Python versions are released annually every October ([PEP 602](https://peps.python.org/pep-0602/)), this effectively means that PyHC packages should be supporting about three minor Python versions at any given time. Packages should be tested against the minimum and maximum supported versions of Python. -![Python Support Window](phep-9999/python-support-window.svg) +![Python Support Window](phep-0003/python-support-window.svg) This new policy will replace the current standard [#11](https://github.com/heliophysicsPy/standards/blob/main/standards.md#standards) in the PyHC standards document with the following new text: From e83c965503a85e666a827ab11a45b48000b3e8e7 Mon Sep 17 00:00:00 2001 From: sapols Date: Thu, 6 Jun 2024 17:08:32 -0600 Subject: [PATCH 07/20] Update "How to Teach This" section --- pheps/phep-0003.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/pheps/phep-0003.md b/pheps/phep-0003.md index abd5041..8a7aa48 100644 --- a/pheps/phep-0003.md +++ b/pheps/phep-0003.md @@ -53,7 +53,8 @@ There are no direct security implications of this policy. However, ensuring pack # How to Teach This -A new web page under the PyHC Projects page detailing the support schedule? (Similar to the Gantt chart in SPEC-0?) + - A new webpage under the PyHC Projects page detailing the support schedule (similar to the Gantt chart in SPEC-0)? + - Automated email reminders sent near upcoming drop/support dates? # Reference Implementation @@ -104,7 +105,7 @@ for _, row in df.iterrows(): mermaid_gantt += f" {row['python version']} : {row['release'].strftime('%Y-%m-%d')},{row['drop'].strftime('%Y-%m-%d')}\n" # Save the Mermaid syntax to a Markdown file -# The Mermaid Gantt chart syntax is saved in 'python_version_support_gantt.md'. +# The Mermaid Gantt chart syntax is saved in 'python_version_support_chart.md'. # You can paste the content of that file into https://mermaid.live/ to generate the chart image. with open("python_version_support_chart.md", "w") as file: file.write(mermaid_gantt) From e50538c93410da8aafce6fdad77a34a6bec6ca96 Mon Sep 17 00:00:00 2001 From: sapols Date: Thu, 6 Jun 2024 17:10:08 -0600 Subject: [PATCH 08/20] Update new standard's text --- pheps/phep-0003.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pheps/phep-0003.md b/pheps/phep-0003.md index 8a7aa48..9d25bda 100644 --- a/pheps/phep-0003.md +++ b/pheps/phep-0003.md @@ -41,7 +41,7 @@ Since new minor Python versions are released annually every October ([PEP 602](h This new policy will replace the current standard [#11](https://github.com/heliophysicsPy/standards/blob/main/standards.md#standards) in the PyHC standards document with the following new text: -> **Python Support:** All packages must support minor Python versions released only within the past 42 months (3.5 years). Additionally, packages must support new minor Python versions within 6 months of their release (see [PHEP 9999](???)). +> **11. Python Support:** All packages must support minor Python versions released only within the past 42 months (3.5 years). Additionally, packages must support new minor Python versions within 6 months of their release (see [PHEP 9999](???)). # Backwards Compatibility From 2fcf21105f601550a526fc28d97861b3a9e2716a Mon Sep 17 00:00:00 2001 From: sapols Date: Thu, 6 Jun 2024 17:11:50 -0600 Subject: [PATCH 09/20] Update open issues --- pheps/phep-0003.md | 1 + 1 file changed, 1 insertion(+) diff --git a/pheps/phep-0003.md b/pheps/phep-0003.md index 9d25bda..33117e1 100644 --- a/pheps/phep-0003.md +++ b/pheps/phep-0003.md @@ -122,6 +122,7 @@ print("Mermaid Gantt chart syntax saved to 'python_version_support_chart.md' (re 1. This PHEP recommends supporting Python versions for 42 months (3.5 years) which is in line with [NEP 29](https://numpy.org/neps/nep-0029-deprecation_policy.html), _not_ 36 months (3 years) as recommended by [SPEC-0](https://scientific-python.org/specs/spec-0000/). The thinking is that 42 months is more linient and therefore less of a burden to the community, but is that the right call? Should it be 36 months instead? 2. Should we adopt the 2-year core package support policy from SPEC-0 in a separate PHEP? (`numpy, scipy, matplotlib, pandas, scikit-image, networkx, scikit-learn, xarray, ipython, zarr`) +3. What should go in the "How to Teach This" section? # Footnotes From 6366e0ee9ddbc22f3e646b5c45b9474090962118 Mon Sep 17 00:00:00 2001 From: sapols Date: Thu, 6 Jun 2024 17:22:08 -0600 Subject: [PATCH 10/20] Fix typos --- pheps/phep-0003.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/pheps/phep-0003.md b/pheps/phep-0003.md index 33117e1..94cb2d9 100644 --- a/pheps/phep-0003.md +++ b/pheps/phep-0003.md @@ -21,7 +21,7 @@ This policy will replace the current standard [#11](https://github.com/heliophys # Motivation -The current PyHC standard [#11](https://github.com/heliophysicsPy/standards/blob/main/standards.md#standards), which mandates compatibility with Python 3, is outdated. Python 3 support is virtually universal now, so it would be more benefitial to replace this standard with a policy for how to support new minor Python versions. [NEP 29](https://numpy.org/neps/nep-0029-deprecation_policy.html) and [SPEC-0](https://scientific-python.org/specs/spec-0000/) provide a structured support timeline that balances stability and progress, essential for software in the heliophysics community. Adopting a similar policy ensures consistency and predictability in support timelines. Additionally, limiting the scope of supported Python versions is an effective way for packages to limit maintenance burden while promoting interoperability. +The current PyHC standard [#11](https://github.com/heliophysicsPy/standards/blob/main/standards.md#standards), which mandates compatibility with Python 3, is outdated. Python 3 support is virtually universal now, so it would be more beneficial to replace this standard with a policy for how to support new minor Python versions. [NEP 29](https://numpy.org/neps/nep-0029-deprecation_policy.html) and [SPEC-0](https://scientific-python.org/specs/spec-0000/) provide a structured support timeline that balances stability and progress, essential for software in the heliophysics community. Adopting a similar policy ensures consistency and predictability in support timelines. Additionally, limiting the scope of supported Python versions is an effective way for packages to limit maintenance burden while promoting interoperability. # Rationale @@ -41,7 +41,7 @@ Since new minor Python versions are released annually every October ([PEP 602](h This new policy will replace the current standard [#11](https://github.com/heliophysicsPy/standards/blob/main/standards.md#standards) in the PyHC standards document with the following new text: -> **11. Python Support:** All packages must support minor Python versions released only within the past 42 months (3.5 years). Additionally, packages must support new minor Python versions within 6 months of their release (see [PHEP 9999](???)). +> **11. Python Support:** All packages must support minor Python versions released only within the past 42 months (3.5 years). Additionally, packages must support new minor Python versions within 6 months of their release (see [PHEP 3](https://github.com/heliophysicsPy/standards/pull/29)). # Backwards Compatibility @@ -120,7 +120,7 @@ print("Mermaid Gantt chart syntax saved to 'python_version_support_chart.md' (re # Open Issues -1. This PHEP recommends supporting Python versions for 42 months (3.5 years) which is in line with [NEP 29](https://numpy.org/neps/nep-0029-deprecation_policy.html), _not_ 36 months (3 years) as recommended by [SPEC-0](https://scientific-python.org/specs/spec-0000/). The thinking is that 42 months is more linient and therefore less of a burden to the community, but is that the right call? Should it be 36 months instead? +1. This PHEP recommends supporting Python versions for 42 months (3.5 years) which is in line with [NEP 29](https://numpy.org/neps/nep-0029-deprecation_policy.html), _not_ 36 months (3 years) as recommended by [SPEC-0](https://scientific-python.org/specs/spec-0000/). The thinking is that 42 months is more lenient and therefore less of a burden to the community, but is that the right call? Should it be 36 months instead? 2. Should we adopt the 2-year core package support policy from SPEC-0 in a separate PHEP? (`numpy, scipy, matplotlib, pandas, scikit-image, networkx, scikit-learn, xarray, ipython, zarr`) 3. What should go in the "How to Teach This" section? From da3871556838b00cace882cb43de16c7858a6131 Mon Sep 17 00:00:00 2001 From: sapols Date: Thu, 6 Jun 2024 20:28:33 -0600 Subject: [PATCH 11/20] Minor text changes --- pheps/phep-0003.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/pheps/phep-0003.md b/pheps/phep-0003.md index 94cb2d9..ae592f8 100644 --- a/pheps/phep-0003.md +++ b/pheps/phep-0003.md @@ -41,7 +41,9 @@ Since new minor Python versions are released annually every October ([PEP 602](h This new policy will replace the current standard [#11](https://github.com/heliophysicsPy/standards/blob/main/standards.md#standards) in the PyHC standards document with the following new text: -> **11. Python Support:** All packages must support minor Python versions released only within the past 42 months (3.5 years). Additionally, packages must support new minor Python versions within 6 months of their release (see [PHEP 3](https://github.com/heliophysicsPy/standards/pull/29)). +> **11. Python Support:** All packages must support minor Python versions released only within the last 42 months (3.5 years). Additionally, packages must support new minor Python versions within 6 months of their release (see [PHEP 3](https://github.com/heliophysicsPy/standards/pull/29)). + +Lastly, if there is a Python 4, this policy will have to be reviewed in light of the community's and projects' best interests. # Backwards Compatibility @@ -53,7 +55,7 @@ There are no direct security implications of this policy. However, ensuring pack # How to Teach This - - A new webpage under the PyHC Projects page detailing the support schedule (similar to the Gantt chart in SPEC-0)? + - A new web page under the PyHC Projects page detailing the support schedule (similar to the Gantt chart in SPEC-0)? - Automated email reminders sent near upcoming drop/support dates? # Reference Implementation From 7ce321cae6c9dd486ead4d3d9a04b3e22c0f9af9 Mon Sep 17 00:00:00 2001 From: sapols Date: Thu, 6 Jun 2024 20:31:31 -0600 Subject: [PATCH 12/20] Remove the word "tables" --- pheps/phep-0003.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pheps/phep-0003.md b/pheps/phep-0003.md index ae592f8..81e5de4 100644 --- a/pheps/phep-0003.md +++ b/pheps/phep-0003.md @@ -62,7 +62,7 @@ There are no direct security implications of this policy. However, ensuring pack Multiple PyHC packages already follow this Python version support policy. One notable example is PlasmaPy which currently comments this policy above the `requires-python` line in their [pyproject.toml](https://github.com/PlasmaPy/PlasmaPy/blob/main/pyproject.toml#L24-L27) file. -## Code to generate support and drop schedule tables: +## Code to generate support and drop schedules: ```python import pandas as pd from datetime import datetime, timedelta From 6a6a5aad5b4841d6dea83b7c30f7948ce5010597 Mon Sep 17 00:00:00 2001 From: sapols Date: Thu, 6 Jun 2024 20:43:43 -0600 Subject: [PATCH 13/20] Add an open issue about "should" vs "must" --- pheps/phep-0003.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/pheps/phep-0003.md b/pheps/phep-0003.md index 81e5de4..c7a30a1 100644 --- a/pheps/phep-0003.md +++ b/pheps/phep-0003.md @@ -123,8 +123,9 @@ print("Mermaid Gantt chart syntax saved to 'python_version_support_chart.md' (re # Open Issues 1. This PHEP recommends supporting Python versions for 42 months (3.5 years) which is in line with [NEP 29](https://numpy.org/neps/nep-0029-deprecation_policy.html), _not_ 36 months (3 years) as recommended by [SPEC-0](https://scientific-python.org/specs/spec-0000/). The thinking is that 42 months is more lenient and therefore less of a burden to the community, but is that the right call? Should it be 36 months instead? -2. Should we adopt the 2-year core package support policy from SPEC-0 in a separate PHEP? (`numpy, scipy, matplotlib, pandas, scikit-image, networkx, scikit-learn, xarray, ipython, zarr`) +2. The new standard #11 text uses "must" while the rest of this document uses "should". Should this policy be a "should" or a "must"? 3. What should go in the "How to Teach This" section? +4. Should we adopt the 2-year core package support policy from SPEC-0 in a separate PHEP? (`numpy, scipy, matplotlib, pandas, scikit-image, networkx, scikit-learn, xarray, ipython, zarr`) # Footnotes From 4c39bb6d7733469251fec3e87da8926ad8a130df Mon Sep 17 00:00:00 2001 From: sapols Date: Tue, 11 Jun 2024 12:15:09 -0600 Subject: [PATCH 14/20] Adopt SPEC 0's 36 month policy, use "should" not "must" --- pheps/phep-0003.md | 40 +++++++++++------------ pheps/phep-0003/python-support-window.svg | 2 +- 2 files changed, 20 insertions(+), 22 deletions(-) diff --git a/pheps/phep-0003.md b/pheps/phep-0003.md index c7a30a1..4fca2c5 100644 --- a/pheps/phep-0003.md +++ b/pheps/phep-0003.md @@ -8,46 +8,46 @@ Status: Draft Type: Standards Track Content-Type: text/markdown; charset=UTF-8; variant=CommonMark Created: 06-Jun-2024 -Post-History: 06-Jun-2024 +Post-History: 06-Jun-2024, 11-Jun-2024 ``` # Abstract -This PHEP recommends that all projects across the PyHC ecosystem adopt a common time-based policy for support of Python versions, similar to [NEP 29](https://numpy.org/neps/nep-0029-deprecation_policy.html) and [SPEC-0](https://scientific-python.org/specs/spec-0000/). Specifically, it recommends that: -1. Support for Python versions be dropped **42 months** (3.5 years) after their initial release. +This PHEP recommends that all projects across the PyHC ecosystem adopt a common time-based policy for support of Python versions, similar to [SPEC 0](https://scientific-python.org/specs/spec-0000/). Specifically, it recommends that: +1. Support for Python versions be dropped **36 months** (3 years) after their initial release. 2. New Python versions be adopted within **6 months** of their release. This policy will replace the current standard [#11](https://github.com/heliophysicsPy/standards/blob/main/standards.md#standards) which simply mandates Python 3 support. # Motivation -The current PyHC standard [#11](https://github.com/heliophysicsPy/standards/blob/main/standards.md#standards), which mandates compatibility with Python 3, is outdated. Python 3 support is virtually universal now, so it would be more beneficial to replace this standard with a policy for how to support new minor Python versions. [NEP 29](https://numpy.org/neps/nep-0029-deprecation_policy.html) and [SPEC-0](https://scientific-python.org/specs/spec-0000/) provide a structured support timeline that balances stability and progress, essential for software in the heliophysics community. Adopting a similar policy ensures consistency and predictability in support timelines. Additionally, limiting the scope of supported Python versions is an effective way for packages to limit maintenance burden while promoting interoperability. +The current PyHC standard [#11](https://github.com/heliophysicsPy/standards/blob/main/standards.md#standards), which mandates compatibility with Python 3, is outdated. Python 3 support is virtually universal now, so it would be more beneficial to replace this standard with a policy for how to support new minor Python versions. [SPEC 0](https://scientific-python.org/specs/spec-0000/) provides a structured support timeline that balances stability and progress, essential for software in the heliophysics community. Adopting a similar policy ensures consistency and predictability in support timelines. Additionally, limiting the scope of supported Python versions is an effective way for packages to limit maintenance burden while promoting interoperability. # Rationale -Following [NEP 29](https://numpy.org/neps/nep-0029-deprecation_policy.html)'s 42-month support timeline ensures that PyHC packages maintain compatibility with newer Python features while providing adequate time for package maintainers to adapt. Allowing 6 months to adopt new Python versions ensures packages stay current with Python's development cycle while providing a reasonable timeframe for testing and integration. +Following [SPEC 0](https://scientific-python.org/specs/spec-0000/)'s 36-month support timeline ensures that PyHC packages maintain compatibility with newer Python features while providing adequate time for package maintainers to adapt. Allowing 6 months to adopt new Python versions ensures packages stay current with Python's development cycle while providing a reasonable timeframe for testing and integration. # Specification This PHEP refers to feature releases of Python, i.e., updates to the minor version assuming semantic versioning (e.g., Python 3.12.0, not Python 3.12.1). This PHEP specifies that all PyHC packages should: -1. Drop support for Python versions **42 months** (3.5 years) after their initial release. +1. Drop support for Python versions **36 months** (3 years) after their initial release. 2. Adopt support for new Python versions within **6 months** of their release. -Since new minor Python versions are released annually every October ([PEP 602](https://peps.python.org/pep-0602/)), this effectively means that PyHC packages should be supporting about three minor Python versions at any given time. Packages should be tested against the minimum and maximum supported versions of Python. +Since new minor Python versions are released annually every October ([PEP 602](https://peps.python.org/pep-0602/)), this effectively means that PyHC packages should be supporting about three minor Python versions at any given time. Providing ongoing support for older versions beyond this period is optional but not recommended. Packages should be tested against the minimum and maximum supported versions of Python. ![Python Support Window](phep-0003/python-support-window.svg) This new policy will replace the current standard [#11](https://github.com/heliophysicsPy/standards/blob/main/standards.md#standards) in the PyHC standards document with the following new text: -> **11. Python Support:** All packages must support minor Python versions released only within the last 42 months (3.5 years). Additionally, packages must support new minor Python versions within 6 months of their release (see [PHEP 3](https://github.com/heliophysicsPy/standards/pull/29)). +> **11. Python Support:** All packages should support minor Python versions released only within the last 36 months (3 years). Additionally, packages should support new minor Python versions within 6 months of their release (see [PHEP 3](https://github.com/heliophysicsPy/standards/pull/29)). Lastly, if there is a Python 4, this policy will have to be reviewed in light of the community's and projects' best interests. # Backwards Compatibility -This policy introduces backwards incompatibilities by enforcing a new support timeline, which may require some packages to drop support for older Python versions sooner than planned. Packages currently supporting versions outside this window will need updates to comply with the new standard. +This policy introduces backwards incompatibilities by enforcing a new support timeline, which may require some packages to drop support for older Python versions sooner than planned. # Security Implications @@ -55,7 +55,7 @@ There are no direct security implications of this policy. However, ensuring pack # How to Teach This - - A new web page under the PyHC Projects page detailing the support schedule (similar to the Gantt chart in SPEC-0)? + - A new web page under the PyHC Projects page detailing the support schedule (similar to the Gantt chart in SPEC 0)? - Automated email reminders sent near upcoming drop/support dates? # Reference Implementation @@ -75,15 +75,15 @@ py_releases = { "3.12": "Oct 2, 2023", } -# Define the support periods of 3.5 years / 6 months -plus42 = timedelta(days=int(365*3.5 + 1)) +# Define the support periods of 3 years / 6 months +plus36 = timedelta(days=int(365 * 3)) plus6 = timedelta(days=int(365 * 0.5)) # Create a DataFrame from the predefined py_releases data data = [] for version, release_date in py_releases.items(): release_date_dt = datetime.strptime(release_date, "%b %d, %Y") - drop_date_dt = release_date_dt + plus42 + drop_date_dt = release_date_dt + plus36 support_by_dt = release_date_dt + plus6 data.append((version, release_date_dt, support_by_dt, drop_date_dt)) @@ -118,23 +118,21 @@ print("Mermaid Gantt chart syntax saved to 'python_version_support_chart.md' (re # Rejected Ideas -[SPEC-0](https://scientific-python.org/specs/spec-0000/)'s 36-month support timeline was considered instead of [NEP 29](https://numpy.org/neps/nep-0029-deprecation_policy.html)'s 42 months, but it was ultimately decided that the extra stability of 42 months is more desirable. +[NEP 29](https://numpy.org/neps/nep-0029-deprecation_policy.html)'s more lenient 42-month support timeline was originally considered instead of [SPEC 0](https://scientific-python.org/specs/spec-0000/)'s 36 months, but it was ultimately decided to follow SPEC 0 because it supersedes NEP 29. # Open Issues -1. This PHEP recommends supporting Python versions for 42 months (3.5 years) which is in line with [NEP 29](https://numpy.org/neps/nep-0029-deprecation_policy.html), _not_ 36 months (3 years) as recommended by [SPEC-0](https://scientific-python.org/specs/spec-0000/). The thinking is that 42 months is more lenient and therefore less of a burden to the community, but is that the right call? Should it be 36 months instead? -2. The new standard #11 text uses "must" while the rest of this document uses "should". Should this policy be a "should" or a "must"? -3. What should go in the "How to Teach This" section? -4. Should we adopt the 2-year core package support policy from SPEC-0 in a separate PHEP? (`numpy, scipy, matplotlib, pandas, scikit-image, networkx, scikit-learn, xarray, ipython, zarr`) +1. What should go in the "How to Teach This" section? +2. Should we adopt the 2-year core package support policy from SPEC 0 in a separate PHEP? (`numpy, scipy, matplotlib, pandas, scikit-image, networkx, scikit-learn, xarray, ipython, zarr`) # Footnotes -1. NEP 29: https://numpy.org/neps/nep-0029-deprecation_policy.html -2. SPEC-0: https://scientific-python.org/specs/spec-0000/ +1. SPEC 0: https://scientific-python.org/specs/spec-0000/ +2. NEP 29: https://numpy.org/neps/nep-0029-deprecation_policy.html # Revisions -Revision 1 (06-Jun-2024): Initial draft. +Revision 1 (pending): Initial draft. # Copyright diff --git a/pheps/phep-0003/python-support-window.svg b/pheps/phep-0003/python-support-window.svg index fc6a9c4..cdb5967 100644 --- a/pheps/phep-0003/python-support-window.svg +++ b/pheps/phep-0003/python-support-window.svg @@ -1 +1 @@ - 01 / 2021 01 / 2022 01 / 2023 01 / 2024 01 / 2025 01 / 2026 01 / 20273.9 3.10 3.11 3.12 python Python Version Support Window \ No newline at end of file + 01 / 2021 01 / 2022 01 / 2023 01 / 2024 01 / 2025 01 / 20263.9 3.10 3.11 3.12 python Python Version Support Window \ No newline at end of file From a65acc6db092fa0da1da0875f7e31ead0b4d7d22 Mon Sep 17 00:00:00 2001 From: sapols Date: Tue, 2 Jul 2024 21:12:05 -0600 Subject: [PATCH 15/20] Expand scope to include upstream package support policy --- pheps/phep-0003.md | 324 ++++++++++++++---- pheps/phep-0003/dependency-support-window.svg | 3 + pheps/phep-0003/python-support-window.svg | 1 - 3 files changed, 268 insertions(+), 60 deletions(-) create mode 100644 pheps/phep-0003/dependency-support-window.svg delete mode 100644 pheps/phep-0003/python-support-window.svg diff --git a/pheps/phep-0003.md b/pheps/phep-0003.md index 4fca2c5..3b2939e 100644 --- a/pheps/phep-0003.md +++ b/pheps/phep-0003.md @@ -1,6 +1,6 @@ ``` PHEP: 3 -Title: PyHC Python Support Policy +Title: PyHC Python & Upstream Package Support Policy Author: Shawn Polson Discussions-To: https://github.com/heliophysicsPy/standards/pull/29 Revision: 1 @@ -8,122 +8,328 @@ Status: Draft Type: Standards Track Content-Type: text/markdown; charset=UTF-8; variant=CommonMark Created: 06-Jun-2024 -Post-History: 06-Jun-2024, 11-Jun-2024 +Post-History: 06-Jun-2024, 11-Jun-2024, 02-Jul-2024 ``` # Abstract -This PHEP recommends that all projects across the PyHC ecosystem adopt a common time-based policy for support of Python versions, similar to [SPEC 0](https://scientific-python.org/specs/spec-0000/). Specifically, it recommends that: -1. Support for Python versions be dropped **36 months** (3 years) after their initial release. -2. New Python versions be adopted within **6 months** of their release. +This PHEP recommends that all projects across the PyHC ecosystem adopt a common time-based policy for support of dependencies, similar to [SPEC 0](https://scientific-python.org/specs/spec-0000/). Specifically, for Python versions and the upstream Scientific Python packages covered by SPEC 0, it recommends that projects: +1. Support Python versions for at least **36 months** (3 years) after their initial release. +2. Support upstream Scientific Python packages for at least **24 months** (2 years) after their initial release. +3. Adopt support for new versions of these dependencies within **6 months** of their release. + +The upstream Scientific Python packages are: `numpy, scipy, matplotlib, pandas, scikit-image, networkx, scikit-learn, xarray, ipython, zarr`. This policy will replace the current standard [#11](https://github.com/heliophysicsPy/standards/blob/main/standards.md#standards) which simply mandates Python 3 support. # Motivation -The current PyHC standard [#11](https://github.com/heliophysicsPy/standards/blob/main/standards.md#standards), which mandates compatibility with Python 3, is outdated. Python 3 support is virtually universal now, so it would be more beneficial to replace this standard with a policy for how to support new minor Python versions. [SPEC 0](https://scientific-python.org/specs/spec-0000/) provides a structured support timeline that balances stability and progress, essential for software in the heliophysics community. Adopting a similar policy ensures consistency and predictability in support timelines. Additionally, limiting the scope of supported Python versions is an effective way for packages to limit maintenance burden while promoting interoperability. +The current PyHC standard [#11](https://github.com/heliophysicsPy/standards/blob/main/standards.md#standards), which mandates compatibility with Python 3, is outdated. Python 3 support is virtually universal now, so it would be more beneficial to replace this standard with a policy for how to support new minor Python versions and key upstream dependencies. [SPEC 0](https://scientific-python.org/specs/spec-0000/) provides a structured support timeline that balances stability and progress, essential for software in the heliophysics community. Adopting a similar policy ensures consistency and predictability in support timelines. Additionally, limiting the scope of supported versions is an effective way for packages to limit maintenance burden while promoting interoperability. # Rationale -Following [SPEC 0](https://scientific-python.org/specs/spec-0000/)'s 36-month support timeline ensures that PyHC packages maintain compatibility with newer Python features while providing adequate time for package maintainers to adapt. Allowing 6 months to adopt new Python versions ensures packages stay current with Python's development cycle while providing a reasonable timeframe for testing and integration. +Following [SPEC 0](https://scientific-python.org/specs/spec-0000/)'s 24/36-month support timeline keeps PyHC in better sync with the broader Scientific Python community, maintaining compatibility with newer Python features and key upstream dependencies, while providing adequate time for package maintainers to adapt. Allowing 6 months to adopt new versions ensures packages stay current with development cycles while providing a reasonable timeframe for testing and integration. # Specification -This PHEP refers to feature releases of Python, i.e., updates to the minor version assuming semantic versioning (e.g., Python 3.12.0, not Python 3.12.1). +This PHEP refers to feature releases of dependencies (e.g., Python 3.12.0, NumPy 2.0.0; not Python 3.12.1, NumPy 2.0.1). This PHEP specifies that all PyHC packages should: -1. Drop support for Python versions **36 months** (3 years) after their initial release. -2. Adopt support for new Python versions within **6 months** of their release. +1. Support Python versions for at least **36 months** (3 years) after their initial release. +2. Support upstream Scientific Python packages for at least **24 months** (2 years) after their initial release. +3. Adopt support for new versions of these dependencies within **6 months** of their release. + +The upstream Scientific Python packages are: `numpy, scipy, matplotlib, pandas, scikit-image, networkx, scikit-learn, xarray, ipython, zarr`. + +Since new minor Python versions are released annually every October ([PEP 602](https://peps.python.org/pep-0602/)), this effectively means that PyHC packages should be supporting about three minor Python versions at any given time. Upstream packages have more varied release schedules, but several recent versions should typically be supported concurrently. Providing ongoing support for older versions beyond the specified support periods is optional. -Since new minor Python versions are released annually every October ([PEP 602](https://peps.python.org/pep-0602/)), this effectively means that PyHC packages should be supporting about three minor Python versions at any given time. Providing ongoing support for older versions beyond this period is optional but not recommended. Packages should be tested against the minimum and maximum supported versions of Python. +![Dependency Support Window](phep-0003/dependency-support-window.svg) -![Python Support Window](phep-0003/python-support-window.svg) +PyHC packages should clearly document their dependency version policy (e.g., like [PlasmaPy](https://docs.plasmapy.org/en/stable/contributing/coding_guide.html#python-and-dependency-version-support) and [SpacePy](https://spacepy.github.io/dep_versions.html)) and be tested against the minimum and maximum supported versions. Testing with CI against release candidates is encouraged, too, as a way to stay ahead of future releases. Packages that use semantic versioning should consider using their version number to indicate versions that drop support for older dependencies. There is no expectation that a package "deprecate" an older dependency before dropping support for it. However, there is an expectation that maximum or exact requirements (e.g., `numpy<2` or `matplotlib==3.5.3`) be set only when absolutely necessary (and that GitHub issues be immediately created to remove such requirements). This new policy will replace the current standard [#11](https://github.com/heliophysicsPy/standards/blob/main/standards.md#standards) in the PyHC standards document with the following new text: -> **11. Python Support:** All packages should support minor Python versions released only within the last 36 months (3 years). Additionally, packages should support new minor Python versions within 6 months of their release (see [PHEP 3](https://github.com/heliophysicsPy/standards/pull/29)). +> **11. Python and Upstream Package Support:** All packages should support minor Python versions released within the last 36 months (3 years) and upstream core Scientific Python packages released within the last 24 months (2 years). Additionally, packages should support new versions within 6 months of their release (see [PHEP 3](https://github.com/heliophysicsPy/standards/pull/29)). -Lastly, if there is a Python 4, this policy will have to be reviewed in light of the community's and projects' best interests. +Lastly, if there is a Python 4 or other significant changes in dependencies, this policy will have to be reviewed in light of the community's and projects' best interests. # Backwards Compatibility -This policy introduces backwards incompatibilities by enforcing a new support timeline, which may require some packages to drop support for older Python versions sooner than planned. +This policy potentially introduces backwards incompatibilities by enforcing a new support timeline, which may encourage some packages to drop support for older dependency versions sooner than planned. # Security Implications -There are no direct security implications of this policy. However, ensuring packages are updated to newer Python versions may indirectly improve security by incorporating fixes and improvements from newer releases. +There are no direct security implications of this policy. However, ensuring packages are updated to newer dependency versions may indirectly improve security by incorporating fixes and improvements from newer releases. # How to Teach This - A new web page under the PyHC Projects page detailing the support schedule (similar to the Gantt chart in SPEC 0)? - - Automated email reminders sent near upcoming drop/support dates? + - Automated email reminders sent quarterly and/or near upcoming drop/support dates? # Reference Implementation -Multiple PyHC packages already follow this Python version support policy. One notable example is PlasmaPy which currently comments this policy above the `requires-python` line in their [pyproject.toml](https://github.com/PlasmaPy/PlasmaPy/blob/main/pyproject.toml#L24-L27) file. +Multiple PyHC packages already follow this version support policy. One notable example is PlasmaPy which currently [documents their SPEC 0-based policy](https://docs.plasmapy.org/en/stable/contributing/coding_guide.html#python-and-dependency-version-support) and even mentions it in comments inside their [pyproject.toml](https://github.com/PlasmaPy/PlasmaPy/blob/main/pyproject.toml) file. ## Code to generate support and drop schedules: ```python -import pandas as pd +import requests +import collections from datetime import datetime, timedelta -# Define the release dates of the Python versions +import pandas as pd +from packaging.version import Version + + py_releases = { "3.9": "Oct 5, 2020", "3.10": "Oct 4, 2021", "3.11": "Oct 24, 2022", "3.12": "Oct 2, 2023", } - -# Define the support periods of 3 years / 6 months +core_packages = [ + "numpy", + "scipy", + "matplotlib", + "pandas", + "scikit-image", + "networkx", + "scikit-learn", + "xarray", + "ipython", + "zarr", +] plus36 = timedelta(days=int(365 * 3)) +plus24 = timedelta(days=int(365 * 2)) plus6 = timedelta(days=int(365 * 0.5)) -# Create a DataFrame from the predefined py_releases data +# Release data + +# put cutoff 3 quarters ago – we do not use "just" -9 month, +# to avoid the content of the quarter to change depending on when we generate this +# file during the current quarter. + +current_date = pd.Timestamp.now() +current_quarter_start = pd.Timestamp( + current_date.year, (current_date.quarter - 1) * 3 + 1, 1 +) +cutoff = current_quarter_start - pd.DateOffset(months=9) + + +def get_release_dates(package, support_time=plus24): + releases = {} + + print(f"Querying pypi.org for {package} versions...", end="", flush=True) + response = requests.get( + f"https://pypi.org/simple/{package}", + headers={"Accept": "application/vnd.pypi.simple.v1+json"}, + ).json() + print("OK") + + file_date = collections.defaultdict(list) + for f in response["files"]: + ver = f["filename"].split("-")[1] + try: + version = Version(ver) + except: + continue + + if version.is_prerelease or version.micro != 0: + continue + + release_date = None + for format in ["%Y-%m-%dT%H:%M:%S.%fZ", "%Y-%m-%dT%H:%M:%SZ"]: + try: + release_date = datetime.strptime(f["upload-time"], format) + except: + pass + + if not release_date: + continue + + file_date[version].append(release_date) + + release_date = {v: min(file_date[v]) for v in file_date} + + for ver, release_date in sorted(release_date.items()): + drop_date = release_date + support_time + if drop_date >= cutoff: + releases[ver] = { + "release_date": release_date, + "drop_date": drop_date, + "support_by_date": release_date + plus6 + } + + return releases + + +package_releases = { + "python": { + version: { + "release_date": datetime.strptime(release_date, "%b %d, %Y"), + "drop_date": datetime.strptime(release_date, "%b %d, %Y") + plus36, + "support_by_date": datetime.strptime(release_date, "%b %d, %Y") + plus6 + } + for version, release_date in py_releases.items() + } +} + +package_releases |= {package: get_release_dates(package) for package in core_packages} + +# filter all items whose drop_date are in the past +package_releases = { + package: { + version: dates + for version, dates in releases.items() + if dates["drop_date"] > cutoff + } + for package, releases in package_releases.items() +} + + +# Save Gantt chart +# You can paste the contents into https://mermaid.live/ to generate the chart image. + +print("Saving Mermaid chart to chart.md (render at https://mermaid.live/)") +with open("chart.md", "w") as fh: + fh.write( + """gantt +dateFormat YYYY-MM-DD +axisFormat %m / %Y +title Support Window""" + ) + + for name, releases in package_releases.items(): + fh.write(f"\n\nsection {name}") + for version, dates in releases.items(): + fh.write( + f"\n{version} : {dates['release_date'].strftime('%Y-%m-%d')},{dates['drop_date'].strftime('%Y-%m-%d')}" + ) + fh.write("\n") + +# Print drop schedule + data = [] -for version, release_date in py_releases.items(): - release_date_dt = datetime.strptime(release_date, "%b %d, %Y") - drop_date_dt = release_date_dt + plus36 - support_by_dt = release_date_dt + plus6 - data.append((version, release_date_dt, support_by_dt, drop_date_dt)) - -# Create a DataFrame -df = pd.DataFrame(data, columns=["python version", "release", "support by", "drop"]) -df["quarter"] = df["drop"].dt.to_period("Q") - -# Save the DataFrame to a CSV file -df.to_csv('python_version_support_schedule.csv', index=False) - -# Generate Mermaid syntax for the Gantt chart -mermaid_gantt = """gantt - dateFormat YYYY-MM-DD - title Python Version Support Window - axisFormat %m / %Y - - section python -""" - -for _, row in df.iterrows(): - mermaid_gantt += f" {row['python version']} : {row['release'].strftime('%Y-%m-%d')},{row['drop'].strftime('%Y-%m-%d')}\n" - -# Save the Mermaid syntax to a Markdown file -# The Mermaid Gantt chart syntax is saved in 'python_version_support_chart.md'. -# You can paste the content of that file into https://mermaid.live/ to generate the chart image. -with open("python_version_support_chart.md", "w") as file: - file.write(mermaid_gantt) - -print("Version support schedule saved to 'python_version_support_schedule.csv'") -print("Mermaid Gantt chart syntax saved to 'python_version_support_chart.md' (render at https://mermaid.live/)") +for k, versions in package_releases.items(): + for v, dates in versions.items(): + data.append( + ( + k, + v, + pd.to_datetime(dates["release_date"]), + pd.to_datetime(dates["drop_date"]), + pd.to_datetime(dates["support_by_date"]), + ) + ) + +df = pd.DataFrame(data, columns=["package", "version", "release", "drop", "support_by"]) + +df["quarter_drop"] = df["drop"].dt.to_period("Q") +df["quarter_support_by"] = df["support_by"].dt.to_period("Q") + +dq_drop = df.set_index(["quarter_drop", "package"]).sort_index() +dq_support_by = df.set_index(["quarter_support_by", "package"]).sort_index() + + +print("Saving support schedule to schedule.md") + + +def pad_table(table): + rows = [[el.strip() for el in row.split("|")] for row in table] + col_widths = [max(map(len, column)) for column in zip(*rows)] + rows[1] = [ + el if el != "----" else "-" * col_widths[i] for i, el in enumerate(rows[1]) + ] + padded_table = [] + for row in rows: + line = "" + for entry, width in zip(row, col_widths): + if not width: + continue + line += f"| {str.ljust(entry, width)} " + line += f"|" + padded_table.append(line) + + return padded_table + + +def make_table(sub): + table = [] + table.append("| | | |") + table.append("|----|----|----|") + for package in sorted(set(sub.index.get_level_values(0))): + vers = sub.loc[[package]]["version"] + minv, maxv = min(vers), max(vers) + rels = sub.loc[[package]]["release"] + rel_min, rel_max = min(rels), max(rels) + version_range = str(minv) if minv == maxv else f"{minv} to {maxv}" + rel_range = ( + str(rel_min.strftime("%b %Y")) + if rel_min == rel_max + else f"{rel_min.strftime('%b %Y')} and {rel_max.strftime('%b %Y')}" + ) + table.append(f"|{package:<15}|{version_range:<19}|released {rel_range}|") + + return pad_table(table) + + +def make_adopt_table(sub): + table = [] + table.append("| | | |") + table.append("|----|----|----|") + for package in sorted(set(sub.index.get_level_values(0))): + vers = sub.loc[[package]]["version"] + minv, maxv = min(vers), max(vers) + support_bys = sub.loc[[package]]["support_by"] + support_by_min, support_by_max = min(support_bys), max(support_bys) + version_range = str(minv) if minv == maxv else f"{minv} to {maxv}" + support_by_range = ( + str(support_by_min.strftime("%b %Y")) + if support_by_min == support_by_max + else f"{support_by_min.strftime('%b %Y')} and {support_by_max.strftime('%b %Y')}" + ) + table.append(f"|{package:<15}|{version_range:<19}|support by {support_by_range}|") + + return pad_table(table) + + +def make_quarter(quarter, dq_drop, dq_support_by): + table = ["#### " + str(quarter).replace("Q", " - Quarter ") + ":\n"] + + # Add new versions adoption schedule if not empty + if quarter in dq_support_by.index.get_level_values(0): + table.append("###### Adopt support for:\n") + adopt_sub = dq_support_by.loc[quarter] + adopt_table = make_adopt_table(adopt_sub) + table.extend(adopt_table) + + table.append("\n###### Can drop support for:\n") + sub = dq_drop.loc[quarter] + table.extend(make_table(sub)) + + return "\n".join(table) + + +with open("schedule.md", "w") as fh: + # we collect package 6 month in the past, and drop the first quarter + # as we might have filtered some of the packages out depending on + # when we ran the script. + tb = [] + for quarter in list(sorted(set(dq_drop.index.get_level_values(0))))[1:]: + tb.append(make_quarter(quarter, dq_drop, dq_support_by)) + + fh.write("\n\n".join(tb)) + fh.write("\n") + ``` # Rejected Ideas -[NEP 29](https://numpy.org/neps/nep-0029-deprecation_policy.html)'s more lenient 42-month support timeline was originally considered instead of [SPEC 0](https://scientific-python.org/specs/spec-0000/)'s 36 months, but it was ultimately decided to follow SPEC 0 because it supersedes NEP 29. + - [NEP 29](https://numpy.org/neps/nep-0029-deprecation_policy.html)'s more lenient 42-month support timeline was originally considered instead of [SPEC 0](https://scientific-python.org/specs/spec-0000/)'s 36 months, but it was ultimately decided to follow SPEC 0 because it supersedes NEP 29. + - The scope of this PHEP was originally limited to Python version support. However, it was decided that including the upstream package support policy from SPEC 0 would better promote PyHC package interoperability and avoid the need for a future separate PHEP. # Open Issues -1. What should go in the "How to Teach This" section? -2. Should we adopt the 2-year core package support policy from SPEC 0 in a separate PHEP? (`numpy, scipy, matplotlib, pandas, scikit-image, networkx, scikit-learn, xarray, ipython, zarr`) +1. What should go in the "How to Teach This" section? Should we expand on the ideas already there or take it a different direction? # Footnotes diff --git a/pheps/phep-0003/dependency-support-window.svg b/pheps/phep-0003/dependency-support-window.svg new file mode 100644 index 0000000..0eef800 --- /dev/null +++ b/pheps/phep-0003/dependency-support-window.svg @@ -0,0 +1,3 @@ + + +01 / 202101 / 202201 / 202301 / 202401 / 202501 / 20263.9 3.10 7.29.0 0.20.0 3.5.0 7.30.0 0.19.0 1.22.0 7.31.0 8.0.0 1.4.0 0.21.0 1.8.0 2.11.0 7.32.0 8.1.0 2.7 2022.3.0 8.2.0 2.8 7.33.0 8.3.0 1.1.0 7.34.0 8.4.0 1.23.0 2.12.0 2022.6.0 1.9.0 8.5.0 3.6.0 1.5.0 2.13.0 2022.9.0 2022.10.0 3.11 8.6.0 2022.11.0 8.7.0 2022.12.0 1.2.0 1.24.0 1.10.0 8.8.0 3.0 2023.1.0 8.9.0 2023.2.0 8.10.0 2.14.0 3.7.0 0.20.0 8.11.0 2023.3.0 8.12.0 2.0.0 3.1 2023.4.0 8.13.0 2023.5.0 0.21.0 8.14.0 2.15.0 1.25.0 2023.6.0 1.11.0 1.3.0 2023.7.0 2.16.0 2023.8.0 2.1.0 8.15.0 3.8.0 1.26.0 2023.9.0 8.16.0 3.12 0.22.0 3.2 2023.10.0 8.17.0 2023.11.0 8.18.0 2023.12.0 8.19.0 8.20.0 2024.1.0 1.4.0 1.12.0 2.2.0 8.21.0 2.17.0 2024.2.0 8.22.0 2024.3.0 8.23.0 1.13.0 3.3 0.23.0 8.24.0 2.18.0 2024.5.0 3.9.0 1.5.0 8.25.0 2024.6.0 2.0.0 0.24.0 1.14.0 8.26.0 pythonnumpyscipymatplotlibpandasscikit-imagenetworkxscikit-learnxarrayipythonzarrSupport Window \ No newline at end of file diff --git a/pheps/phep-0003/python-support-window.svg b/pheps/phep-0003/python-support-window.svg deleted file mode 100644 index cdb5967..0000000 --- a/pheps/phep-0003/python-support-window.svg +++ /dev/null @@ -1 +0,0 @@ - 01 / 2021 01 / 2022 01 / 2023 01 / 2024 01 / 2025 01 / 20263.9 3.10 3.11 3.12 python Python Version Support Window \ No newline at end of file From d26e3b5ed4d64600305b9b867dd2c75c928db3cb Mon Sep 17 00:00:00 2001 From: sapols Date: Wed, 17 Jul 2024 15:59:35 -0600 Subject: [PATCH 16/20] One sentence per line; clarify SPEC 0 adoption; clarify OS/arch support; remove "indirectly" & "GitHub"; no pinning outdated deps --- pheps/phep-0003.md | 39 ++++++++++++++++++++++++++++----------- 1 file changed, 28 insertions(+), 11 deletions(-) diff --git a/pheps/phep-0003.md b/pheps/phep-0003.md index 3b2939e..2523c28 100644 --- a/pheps/phep-0003.md +++ b/pheps/phep-0003.md @@ -8,12 +8,13 @@ Status: Draft Type: Standards Track Content-Type: text/markdown; charset=UTF-8; variant=CommonMark Created: 06-Jun-2024 -Post-History: 06-Jun-2024, 11-Jun-2024, 02-Jul-2024 +Post-History: 06-Jun-2024, 11-Jun-2024, 02-Jul-2024, 17-Jul-2024 ``` # Abstract -This PHEP recommends that all projects across the PyHC ecosystem adopt a common time-based policy for support of dependencies, similar to [SPEC 0](https://scientific-python.org/specs/spec-0000/). Specifically, for Python versions and the upstream Scientific Python packages covered by SPEC 0, it recommends that projects: +This PHEP recommends that all projects across the PyHC ecosystem adopt a common time-based policy for support of dependencies, inspired by [SPEC 0](https://scientific-python.org/specs/spec-0000/). +Specifically, for Python versions and the upstream Scientific Python packages covered by SPEC 0, it recommends that projects: 1. Support Python versions for at least **36 months** (3 years) after their initial release. 2. Support upstream Scientific Python packages for at least **24 months** (2 years) after their initial release. 3. Adopt support for new versions of these dependencies within **6 months** of their release. @@ -24,32 +25,45 @@ This policy will replace the current standard [#11](https://github.com/heliophys # Motivation -The current PyHC standard [#11](https://github.com/heliophysicsPy/standards/blob/main/standards.md#standards), which mandates compatibility with Python 3, is outdated. Python 3 support is virtually universal now, so it would be more beneficial to replace this standard with a policy for how to support new minor Python versions and key upstream dependencies. [SPEC 0](https://scientific-python.org/specs/spec-0000/) provides a structured support timeline that balances stability and progress, essential for software in the heliophysics community. Adopting a similar policy ensures consistency and predictability in support timelines. Additionally, limiting the scope of supported versions is an effective way for packages to limit maintenance burden while promoting interoperability. +The current PyHC standard [#11](https://github.com/heliophysicsPy/standards/blob/main/standards.md#standards), which mandates compatibility with Python 3, is outdated. +Python 3 support is virtually universal now, so it would be more beneficial to replace this standard with a policy for how to support new minor Python versions and key upstream dependencies. +[SPEC 0](https://scientific-python.org/specs/spec-0000/) provides a structured support timeline that balances stability and progress, essential for software in the heliophysics community. +Adopting a similar policy ensures consistency and predictability in support timelines. +Additionally, limiting the scope of supported versions is an effective way for packages to limit maintenance burden while promoting interoperability. # Rationale -Following [SPEC 0](https://scientific-python.org/specs/spec-0000/)'s 24/36-month support timeline keeps PyHC in better sync with the broader Scientific Python community, maintaining compatibility with newer Python features and key upstream dependencies, while providing adequate time for package maintainers to adapt. Allowing 6 months to adopt new versions ensures packages stay current with development cycles while providing a reasonable timeframe for testing and integration. +Following [SPEC 0](https://scientific-python.org/specs/spec-0000/)'s 24/36-month support timeline keeps PyHC in better sync with the broader Scientific Python community, maintaining compatibility with newer Python features and key upstream dependencies, while providing adequate time for package maintainers to adapt. +Allowing 6 months to adopt new versions ensures packages stay current with development cycles while providing a reasonable timeframe for testing and integration. # Specification This PHEP refers to feature releases of dependencies (e.g., Python 3.12.0, NumPy 2.0.0; not Python 3.12.1, NumPy 2.0.1). -This PHEP specifies that all PyHC packages should: +This PHEP adopts Scientific Python's [SPEC 0](https://scientific-python.org/specs/spec-0000/) and specifies that all PyHC packages should: 1. Support Python versions for at least **36 months** (3 years) after their initial release. 2. Support upstream Scientific Python packages for at least **24 months** (2 years) after their initial release. 3. Adopt support for new versions of these dependencies within **6 months** of their release. The upstream Scientific Python packages are: `numpy, scipy, matplotlib, pandas, scikit-image, networkx, scikit-learn, xarray, ipython, zarr`. -Since new minor Python versions are released annually every October ([PEP 602](https://peps.python.org/pep-0602/)), this effectively means that PyHC packages should be supporting about three minor Python versions at any given time. Upstream packages have more varied release schedules, but several recent versions should typically be supported concurrently. Providing ongoing support for older versions beyond the specified support periods is optional. +Since new minor Python versions are released annually every October ([PEP 602](https://peps.python.org/pep-0602/)), this effectively means that PyHC packages should be supporting about three minor Python versions at any given time. +Upstream packages have more varied release schedules, but several recent versions should typically be supported concurrently. +Providing ongoing support for older versions beyond the specified support periods is optional. ![Dependency Support Window](phep-0003/dependency-support-window.svg) -PyHC packages should clearly document their dependency version policy (e.g., like [PlasmaPy](https://docs.plasmapy.org/en/stable/contributing/coding_guide.html#python-and-dependency-version-support) and [SpacePy](https://spacepy.github.io/dep_versions.html)) and be tested against the minimum and maximum supported versions. Testing with CI against release candidates is encouraged, too, as a way to stay ahead of future releases. Packages that use semantic versioning should consider using their version number to indicate versions that drop support for older dependencies. There is no expectation that a package "deprecate" an older dependency before dropping support for it. However, there is an expectation that maximum or exact requirements (e.g., `numpy<2` or `matplotlib==3.5.3`) be set only when absolutely necessary (and that GitHub issues be immediately created to remove such requirements). +PyHC packages should clearly document their dependency version policy (e.g., like [PlasmaPy](https://docs.plasmapy.org/en/stable/contributing/coding_guide.html#python-and-dependency-version-support) and [SpacePy](https://spacepy.github.io/dep_versions.html)) and be tested against the minimum and maximum supported versions. +Testing with CI against release candidates is encouraged, too, as a way to stay ahead of future releases. +Packages that use semantic versioning should consider using their version number to indicate versions that drop support for older dependencies. +There is no expectation that a package "deprecate" an older dependency before dropping support for it. +However, there is an expectation that maximum or exact requirements (e.g., `numpy<2` or `matplotlib==3.5.3`) be set only when absolutely necessary (and that issues be immediately created to remove such requirements), and packages must not require versions of any dependency older than 24 months. +Additionally, if a package has been supporting specific OS versions and CPU architectures (e.g., releasing binary [wheels](https://packaging.python.org/en/latest/discussions/package-formats/#what-is-a-wheel)), this support should continue for new OS versions and architectures to maintain the same level of support as before. This new policy will replace the current standard [#11](https://github.com/heliophysicsPy/standards/blob/main/standards.md#standards) in the PyHC standards document with the following new text: -> **11. Python and Upstream Package Support:** All packages should support minor Python versions released within the last 36 months (3 years) and upstream core Scientific Python packages released within the last 24 months (2 years). Additionally, packages should support new versions within 6 months of their release (see [PHEP 3](https://github.com/heliophysicsPy/standards/pull/29)). +> **11. Python and Upstream Package Support:** All packages should support minor Python versions released within the last 36 months (3 years) and upstream core Scientific Python packages released within the last 24 months (2 years). +Additionally, packages should support new versions within 6 months of their release (see [PHEP 3](https://github.com/heliophysicsPy/standards/pull/29)). Lastly, if there is a Python 4 or other significant changes in dependencies, this policy will have to be reviewed in light of the community's and projects' best interests. @@ -59,7 +73,8 @@ This policy potentially introduces backwards incompatibilities by enforcing a ne # Security Implications -There are no direct security implications of this policy. However, ensuring packages are updated to newer dependency versions may indirectly improve security by incorporating fixes and improvements from newer releases. +There are no direct security implications of this policy. +However, ensuring packages are updated to newer dependency versions may improve security by incorporating fixes and improvements from newer releases. # How to Teach This @@ -68,7 +83,8 @@ There are no direct security implications of this policy. However, ensuring pack # Reference Implementation -Multiple PyHC packages already follow this version support policy. One notable example is PlasmaPy which currently [documents their SPEC 0-based policy](https://docs.plasmapy.org/en/stable/contributing/coding_guide.html#python-and-dependency-version-support) and even mentions it in comments inside their [pyproject.toml](https://github.com/PlasmaPy/PlasmaPy/blob/main/pyproject.toml) file. +Multiple PyHC packages already follow this version support policy. +One notable example is PlasmaPy which currently [documents their SPEC 0-based policy](https://docs.plasmapy.org/en/stable/contributing/coding_guide.html#python-and-dependency-version-support) and even mentions it in comments inside their [pyproject.toml](https://github.com/PlasmaPy/PlasmaPy/blob/main/pyproject.toml) file. ## Code to generate support and drop schedules: ```python @@ -325,7 +341,8 @@ with open("schedule.md", "w") as fh: # Rejected Ideas - [NEP 29](https://numpy.org/neps/nep-0029-deprecation_policy.html)'s more lenient 42-month support timeline was originally considered instead of [SPEC 0](https://scientific-python.org/specs/spec-0000/)'s 36 months, but it was ultimately decided to follow SPEC 0 because it supersedes NEP 29. - - The scope of this PHEP was originally limited to Python version support. However, it was decided that including the upstream package support policy from SPEC 0 would better promote PyHC package interoperability and avoid the need for a future separate PHEP. + - The scope of this PHEP was originally limited to Python version support. + However, it was decided that including the upstream package support policy from SPEC 0 would better promote PyHC package interoperability and avoid the need for a future separate PHEP. # Open Issues From be78dfd59ae1b73641f6a4595b7998c1bf3dfc85 Mon Sep 17 00:00:00 2001 From: sapols Date: Tue, 23 Jul 2024 13:06:40 -0600 Subject: [PATCH 17/20] Refine "How to Teach This" ideas --- pheps/phep-0003.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/pheps/phep-0003.md b/pheps/phep-0003.md index 2523c28..26e5a22 100644 --- a/pheps/phep-0003.md +++ b/pheps/phep-0003.md @@ -8,7 +8,7 @@ Status: Draft Type: Standards Track Content-Type: text/markdown; charset=UTF-8; variant=CommonMark Created: 06-Jun-2024 -Post-History: 06-Jun-2024, 11-Jun-2024, 02-Jul-2024, 17-Jul-2024 +Post-History: 06-Jun-2024, 11-Jun-2024, 02-Jul-2024, 17-Jul-2024, 23-Jul-2024 ``` # Abstract @@ -78,8 +78,8 @@ However, ensuring packages are updated to newer dependency versions may improve # How to Teach This - - A new web page under the PyHC Projects page detailing the support schedule (similar to the Gantt chart in SPEC 0)? - - Automated email reminders sent quarterly and/or near upcoming drop/support dates? + - A new web page on the PyHC website will detail the support policy and include a graphical timeline of the schedule (similar to the Gantt chart above). + - Automated email reminders will be sent via the PyHC mailing list quarterly and near important drop/support dates to remind package maintainers of the schedule. # Reference Implementation @@ -347,6 +347,7 @@ with open("schedule.md", "w") as fh: # Open Issues 1. What should go in the "How to Teach This" section? Should we expand on the ideas already there or take it a different direction? +Or leave it if it is sufficient already? # Footnotes From f12d556020bf09f637d4a68e3edf19f6da54d56d Mon Sep 17 00:00:00 2001 From: sapols Date: Thu, 5 Sep 2024 22:43:07 -0600 Subject: [PATCH 18/20] Incorporate latest feedback from comments --- pheps/phep-0003.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/pheps/phep-0003.md b/pheps/phep-0003.md index 26e5a22..eb48e6e 100644 --- a/pheps/phep-0003.md +++ b/pheps/phep-0003.md @@ -16,12 +16,12 @@ Post-History: 06-Jun-2024, 11-Jun-2024, 02-Jul-2024, 17-Jul-2024, 23-Jul-2024 This PHEP recommends that all projects across the PyHC ecosystem adopt a common time-based policy for support of dependencies, inspired by [SPEC 0](https://scientific-python.org/specs/spec-0000/). Specifically, for Python versions and the upstream Scientific Python packages covered by SPEC 0, it recommends that projects: 1. Support Python versions for at least **36 months** (3 years) after their initial release. -2. Support upstream Scientific Python packages for at least **24 months** (2 years) after their initial release. +2. Support upstream core Scientific Python packages for at least **24 months** (2 years) after their initial release. 3. Adopt support for new versions of these dependencies within **6 months** of their release. -The upstream Scientific Python packages are: `numpy, scipy, matplotlib, pandas, scikit-image, networkx, scikit-learn, xarray, ipython, zarr`. +At the time of writing, the upstream [core Scientific Python packages](https://scientific-python.org/specs/core-projects/) are: `numpy, scipy, matplotlib, pandas, scikit-image, networkx, scikit-learn, xarray, ipython, zarr`. -This policy will replace the current standard [#11](https://github.com/heliophysicsPy/standards/blob/main/standards.md#standards) which simply mandates Python 3 support. +This policy replaces the current standard [#11](https://github.com/heliophysicsPy/standards/blob/main/standards.md#standards) which simply mandates Python 3 support. # Motivation @@ -42,10 +42,10 @@ This PHEP refers to feature releases of dependencies (e.g., Python 3.12.0, NumPy This PHEP adopts Scientific Python's [SPEC 0](https://scientific-python.org/specs/spec-0000/) and specifies that all PyHC packages should: 1. Support Python versions for at least **36 months** (3 years) after their initial release. -2. Support upstream Scientific Python packages for at least **24 months** (2 years) after their initial release. +2. Support upstream core Scientific Python packages for at least **24 months** (2 years) after their initial release. 3. Adopt support for new versions of these dependencies within **6 months** of their release. -The upstream Scientific Python packages are: `numpy, scipy, matplotlib, pandas, scikit-image, networkx, scikit-learn, xarray, ipython, zarr`. +At the time of writing, the upstream [core Scientific Python packages](https://scientific-python.org/specs/core-projects/) are: `numpy, scipy, matplotlib, pandas, scikit-image, networkx, scikit-learn, xarray, ipython, zarr`. If their core packages are updated, this policy applies to the updated list instead. Since new minor Python versions are released annually every October ([PEP 602](https://peps.python.org/pep-0602/)), this effectively means that PyHC packages should be supporting about three minor Python versions at any given time. Upstream packages have more varied release schedules, but several recent versions should typically be supported concurrently. @@ -60,7 +60,7 @@ There is no expectation that a package "deprecate" an older dependency before dr However, there is an expectation that maximum or exact requirements (e.g., `numpy<2` or `matplotlib==3.5.3`) be set only when absolutely necessary (and that issues be immediately created to remove such requirements), and packages must not require versions of any dependency older than 24 months. Additionally, if a package has been supporting specific OS versions and CPU architectures (e.g., releasing binary [wheels](https://packaging.python.org/en/latest/discussions/package-formats/#what-is-a-wheel)), this support should continue for new OS versions and architectures to maintain the same level of support as before. -This new policy will replace the current standard [#11](https://github.com/heliophysicsPy/standards/blob/main/standards.md#standards) in the PyHC standards document with the following new text: +This new policy replaces the current standard [#11](https://github.com/heliophysicsPy/standards/blob/main/standards.md#standards) in the PyHC standards document with the following new text: > **11. Python and Upstream Package Support:** All packages should support minor Python versions released within the last 36 months (3 years) and upstream core Scientific Python packages released within the last 24 months (2 years). Additionally, packages should support new versions within 6 months of their release (see [PHEP 3](https://github.com/heliophysicsPy/standards/pull/29)). @@ -78,7 +78,7 @@ However, ensuring packages are updated to newer dependency versions may improve # How to Teach This - - A new web page on the PyHC website will detail the support policy and include a graphical timeline of the schedule (similar to the Gantt chart above). + - The PyHC Tech Lead will maintain a new web page on the PyHC website detailing the support policy and include a graphical timeline of the schedule (similar to the Gantt chart above). - Automated email reminders will be sent via the PyHC mailing list quarterly and near important drop/support dates to remind package maintainers of the schedule. # Reference Implementation @@ -87,6 +87,7 @@ Multiple PyHC packages already follow this version support policy. One notable example is PlasmaPy which currently [documents their SPEC 0-based policy](https://docs.plasmapy.org/en/stable/contributing/coding_guide.html#python-and-dependency-version-support) and even mentions it in comments inside their [pyproject.toml](https://github.com/PlasmaPy/PlasmaPy/blob/main/pyproject.toml) file. ## Code to generate support and drop schedules: +The following code can be used to generate support and drop schedules, including the Gantt chart above. ```python import requests import collections @@ -346,8 +347,7 @@ with open("schedule.md", "w") as fh: # Open Issues -1. What should go in the "How to Teach This" section? Should we expand on the ideas already there or take it a different direction? -Or leave it if it is sufficient already? +There are no remaining open issues. # Footnotes From c5f97340c9d05c020a4be13b319296d67e00e14a Mon Sep 17 00:00:00 2001 From: sapols Date: Thu, 5 Sep 2024 22:52:01 -0600 Subject: [PATCH 19/20] Update Post-History --- pheps/phep-0003.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pheps/phep-0003.md b/pheps/phep-0003.md index eb48e6e..7ccea43 100644 --- a/pheps/phep-0003.md +++ b/pheps/phep-0003.md @@ -8,7 +8,7 @@ Status: Draft Type: Standards Track Content-Type: text/markdown; charset=UTF-8; variant=CommonMark Created: 06-Jun-2024 -Post-History: 06-Jun-2024, 11-Jun-2024, 02-Jul-2024, 17-Jul-2024, 23-Jul-2024 +Post-History: 06-Jun-2024, 11-Jun-2024, 02-Jul-2024, 17-Jul-2024, 23-Jul-2024, 05-Sep-2024 ``` # Abstract From 56d9e1001b2d56ebfc4b9317014ea19267129d71 Mon Sep 17 00:00:00 2001 From: sapols Date: Mon, 9 Sep 2024 09:41:30 -0600 Subject: [PATCH 20/20] Incorporate remaining feedback from comments --- pheps/phep-0003.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/pheps/phep-0003.md b/pheps/phep-0003.md index 7ccea43..dea0331 100644 --- a/pheps/phep-0003.md +++ b/pheps/phep-0003.md @@ -8,7 +8,7 @@ Status: Draft Type: Standards Track Content-Type: text/markdown; charset=UTF-8; variant=CommonMark Created: 06-Jun-2024 -Post-History: 06-Jun-2024, 11-Jun-2024, 02-Jul-2024, 17-Jul-2024, 23-Jul-2024, 05-Sep-2024 +Post-History: 06-Jun-2024, 11-Jun-2024, 02-Jul-2024, 17-Jul-2024, 23-Jul-2024, 05-Sep-2024, 09-Sep-2024 ``` # Abstract @@ -51,6 +51,7 @@ Since new minor Python versions are released annually every October ([PEP 602](h Upstream packages have more varied release schedules, but several recent versions should typically be supported concurrently. Providing ongoing support for older versions beyond the specified support periods is optional. +The following shows the dependency support window as of this PHEP's adoption: ![Dependency Support Window](phep-0003/dependency-support-window.svg) PyHC packages should clearly document their dependency version policy (e.g., like [PlasmaPy](https://docs.plasmapy.org/en/stable/contributing/coding_guide.html#python-and-dependency-version-support) and [SpacePy](https://spacepy.github.io/dep_versions.html)) and be tested against the minimum and maximum supported versions. @@ -344,6 +345,7 @@ with open("schedule.md", "w") as fh: - [NEP 29](https://numpy.org/neps/nep-0029-deprecation_policy.html)'s more lenient 42-month support timeline was originally considered instead of [SPEC 0](https://scientific-python.org/specs/spec-0000/)'s 36 months, but it was ultimately decided to follow SPEC 0 because it supersedes NEP 29. - The scope of this PHEP was originally limited to Python version support. However, it was decided that including the upstream package support policy from SPEC 0 would better promote PyHC package interoperability and avoid the need for a future separate PHEP. + - It was considered making this a requirement rather than a recommendation (i.e., using "must" instead of "should" language) but it was decided that this policy is better suited as a recommendation. # Open Issues