From f53caa357ecd45a4f93779da2751f950d0f7eb10 Mon Sep 17 00:00:00 2001 From: Alex Kaszynski Date: Mon, 24 Jan 2022 09:06:37 -0700 Subject: [PATCH 1/6] add notes regarding python EOL --- doc/source/guidelines/index.rst | 1 + doc/source/guidelines/version_support.rst | 38 +++++++++++++++++++++++ 2 files changed, 39 insertions(+) create mode 100644 doc/source/guidelines/version_support.rst diff --git a/doc/source/guidelines/index.rst b/doc/source/guidelines/index.rst index 51030f4b2..2868a284d 100644 --- a/doc/source/guidelines/index.rst +++ b/doc/source/guidelines/index.rst @@ -14,6 +14,7 @@ Table of Contents :maxdepth: 2 dev_practices + version_support app_interface_abstraction data_transfer_and_representation logging diff --git a/doc/source/guidelines/version_support.rst b/doc/source/guidelines/version_support.rst new file mode 100644 index 000000000..af38cf1d3 --- /dev/null +++ b/doc/source/guidelines/version_support.rst @@ -0,0 +1,38 @@ +Python Version Support +====================== + +When writing Python libraries, plan on supporting the oldest actively supported +version of Python. For a quick reference, visit `Python EOL +`_ summarized (as of 2022) here: + ++---------+-------------+-----------------------+ +| Version | Released | Security Support Ends | ++---------+-------------+-----------------------+ +| 3.10 | 04 Oct 2021 | 04 Oct 2026 | ++---------+-------------+-----------------------+ +| 3.9 | 05 Oct 2020 | 05 Oct 2025 | ++---------+-------------+-----------------------+ +| 3.8 | 14 Oct 2019 | 14 Oct 2024 | ++---------+-------------+-----------------------+ +| 3.7 | 27 Jun 2018 | 27 Jun 2023 | ++---------+-------------+-----------------------+ + +Expect these to be the most commonly used Python versions. Note that recently dropped versions (Python 3.6) will no longer have wheels built for popular libraries like `numpy `_. Users can still install the older version from PyPI via ``pip``, and version support tends to gradually "drop off" rather than fall immediately when security support exits. + +You can enforce a minimum required python version within ``setup.py`` with: + +.. code:: python + + from setuptools import setup + + [...] + + setup(name="my_package_name", + python_requires='>3.6', + [...] + ) + +This helps the package manager ``pip`` to know which versions of your library +support which versions of Python. You can also impose an upper limit if you're +sure you don't support certain versions of Python. For example, if you only +support Python 3.6 - 3.9: ``python_requires='>=3.6, <3.10'``. From 8beecde5c6a5e3491e160c72de2004ca0434c135 Mon Sep 17 00:00:00 2001 From: Alex Kaszynski Date: Mon, 24 Jan 2022 09:24:16 -0700 Subject: [PATCH 2/6] Apply suggestions from code review Co-authored-by: Kathy Pippert <84872299+PipKat@users.noreply.github.com> --- doc/source/guidelines/version_support.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/source/guidelines/version_support.rst b/doc/source/guidelines/version_support.rst index af38cf1d3..899978697 100644 --- a/doc/source/guidelines/version_support.rst +++ b/doc/source/guidelines/version_support.rst @@ -1,9 +1,9 @@ Python Version Support ====================== -When writing Python libraries, plan on supporting the oldest actively supported +When creating Python libraries, plan on supporting the oldest actively supported version of Python. For a quick reference, visit `Python EOL -`_ summarized (as of 2022) here: +`_. Here is 2022 summary: +---------+-------------+-----------------------+ | Version | Released | Security Support Ends | @@ -17,9 +17,9 @@ version of Python. For a quick reference, visit `Python EOL | 3.7 | 27 Jun 2018 | 27 Jun 2023 | +---------+-------------+-----------------------+ -Expect these to be the most commonly used Python versions. Note that recently dropped versions (Python 3.6) will no longer have wheels built for popular libraries like `numpy `_. Users can still install the older version from PyPI via ``pip``, and version support tends to gradually "drop off" rather than fall immediately when security support exits. +Expect these to be the most commonly used Python versions. Note that recently dropped versions (Python 3.6) will no longer have wheels built for popular libraries like `numpy `_. You can still install the older version from PyPI via ``pip`` since version support tends to gradually "drop off" rather than cease entirely when security support exits. -You can enforce a minimum required python version within ``setup.py`` with: +You can enforce a minimum required Python version within ``setup.py`` with: .. code:: python @@ -33,6 +33,6 @@ You can enforce a minimum required python version within ``setup.py`` with: ) This helps the package manager ``pip`` to know which versions of your library -support which versions of Python. You can also impose an upper limit if you're +support which versions of Python. You can also impose an upper limit if you're sure you don't support certain versions of Python. For example, if you only -support Python 3.6 - 3.9: ``python_requires='>=3.6, <3.10'``. +support Python 3.6 through 3.9: ``python_requires='>=3.6, <3.10'``. From 5cad2c3b2ef83b3f177775b723f652c98d109f08 Mon Sep 17 00:00:00 2001 From: Alex Kaszynski Date: Mon, 24 Jan 2022 09:29:30 -0700 Subject: [PATCH 3/6] add notes regarding dropping python support; fix link --- doc/source/guidelines/version_support.rst | 40 +++++++++++++++++++++-- 1 file changed, 37 insertions(+), 3 deletions(-) diff --git a/doc/source/guidelines/version_support.rst b/doc/source/guidelines/version_support.rst index 899978697..364fed474 100644 --- a/doc/source/guidelines/version_support.rst +++ b/doc/source/guidelines/version_support.rst @@ -2,8 +2,8 @@ Python Version Support ====================== When creating Python libraries, plan on supporting the oldest actively supported -version of Python. For a quick reference, visit `Python EOL -`_. Here is 2022 summary: +version of Python. For a quick reference, visit `Status of Python Branches +`_. Here is 2022 summary: +---------+-------------+-----------------------+ | Version | Released | Security Support Ends | @@ -17,7 +17,13 @@ version of Python. For a quick reference, visit `Python EOL | 3.7 | 27 Jun 2018 | 27 Jun 2023 | +---------+-------------+-----------------------+ -Expect these to be the most commonly used Python versions. Note that recently dropped versions (Python 3.6) will no longer have wheels built for popular libraries like `numpy `_. You can still install the older version from PyPI via ``pip`` since version support tends to gradually "drop off" rather than cease entirely when security support exits. +Expect these to be the most commonly used Python versions. Note that some +libraries like `numpy `_ drop support for older versions of +Python earlier than the Python versions end of life (EOL) as outlined in `NEP 29 +`_. Realize +that users can still install the older version from PyPI via ``pip`` as the +package manager will download and install the most recent version of that +library that supports your version of Python. You can enforce a minimum required Python version within ``setup.py`` with: @@ -36,3 +42,31 @@ This helps the package manager ``pip`` to know which versions of your library support which versions of Python. You can also impose an upper limit if you're sure you don't support certain versions of Python. For example, if you only support Python 3.6 through 3.9: ``python_requires='>=3.6, <3.10'``. + +Verifying Support +----------------- +The best way to validate support of a Python library's support of a version of +Python is to validate it via GitHub Actions. An example GitHub workflow testing +Python 3.6 through Python 3.10 on Windows and Linux would would start with:: + + jobs: + unittest: + name: Unit Testing + runs-on: ${{ matrix.os }} + strategy: + matrix: + os: [windows-latest, ubuntu-latest] + python-version: ['3.7', '3.8', '3.9', '3.10'] + + steps: + - uses: actions/checkout@v2 + + - name: Set up Python ${{ matrix.python-version }} + uses: actions/setup-python@v2 + with: + python-version: ${{ matrix.python-version }} + + - name: Unit testing + run: | + ... + From c14f9c783412f4182e9026482dc63c572d3d8279 Mon Sep 17 00:00:00 2001 From: Alex Kaszynski Date: Mon, 24 Jan 2022 09:32:32 -0700 Subject: [PATCH 4/6] improve readability --- doc/source/guidelines/version_support.rst | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/doc/source/guidelines/version_support.rst b/doc/source/guidelines/version_support.rst index 364fed474..4d4a46db2 100644 --- a/doc/source/guidelines/version_support.rst +++ b/doc/source/guidelines/version_support.rst @@ -3,7 +3,8 @@ Python Version Support When creating Python libraries, plan on supporting the oldest actively supported version of Python. For a quick reference, visit `Status of Python Branches -`_. Here is 2022 summary: +`_. Here is a summary as +of 2022: +---------+-------------+-----------------------+ | Version | Released | Security Support Ends | @@ -18,14 +19,14 @@ version of Python. For a quick reference, visit `Status of Python Branches +---------+-------------+-----------------------+ Expect these to be the most commonly used Python versions. Note that some -libraries like `numpy `_ drop support for older versions of +libraries like `NumPy `_ drop support for older versions of Python earlier than the Python versions end of life (EOL) as outlined in `NEP 29 -`_. Realize -that users can still install the older version from PyPI via ``pip`` as the -package manager will download and install the most recent version of that -library that supports your version of Python. +`_. -You can enforce a minimum required Python version within ``setup.py`` with: +Realize that users can still install the older version from PyPI via ``pip`` as +the package manager (``pip``) will download and install the most recent version +of that library that supports your version of Python. You can enforce a minimum +required Python version within ``setup.py`` with: .. code:: python @@ -43,11 +44,13 @@ support which versions of Python. You can also impose an upper limit if you're sure you don't support certain versions of Python. For example, if you only support Python 3.6 through 3.9: ``python_requires='>=3.6, <3.10'``. + Verifying Support ----------------- The best way to validate support of a Python library's support of a version of -Python is to validate it via GitHub Actions. An example GitHub workflow testing -Python 3.6 through Python 3.10 on Windows and Linux would would start with:: +Python is to validate it via unit testing within CI/CD. An example +GitHub workflow testing Python 3.6 through Python 3.10 on Windows and Linux +would would start with:: jobs: unittest: From 287c237b647e1e1b17fd56b6bc9db595d64af5f0 Mon Sep 17 00:00:00 2001 From: Alex Kaszynski Date: Mon, 24 Jan 2022 10:07:12 -0700 Subject: [PATCH 5/6] Apply suggestions from code review Co-authored-by: Kathy Pippert <84872299+PipKat@users.noreply.github.com> --- doc/source/guidelines/version_support.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/source/guidelines/version_support.rst b/doc/source/guidelines/version_support.rst index 4d4a46db2..d0f6949e7 100644 --- a/doc/source/guidelines/version_support.rst +++ b/doc/source/guidelines/version_support.rst @@ -20,12 +20,12 @@ of 2022: Expect these to be the most commonly used Python versions. Note that some libraries like `NumPy `_ drop support for older versions of -Python earlier than the Python versions end of life (EOL) as outlined in `NEP 29 +Python earlier than their end of life (EOL) as outlined in `NEP 29 `_. Realize that users can still install the older version from PyPI via ``pip`` as -the package manager (``pip``) will download and install the most recent version -of that library that supports your version of Python. You can enforce a minimum +the package manager (``pip``). When ``pip`` is used, it downloads and installs the most recent version +of THE library that supports your version of Python. You can enforce a minimum- required Python version within ``setup.py`` with: .. code:: python @@ -39,7 +39,7 @@ required Python version within ``setup.py`` with: [...] ) -This helps the package manager ``pip`` to know which versions of your library +This helps ``pip`` to know which versions of your library support which versions of Python. You can also impose an upper limit if you're sure you don't support certain versions of Python. For example, if you only support Python 3.6 through 3.9: ``python_requires='>=3.6, <3.10'``. @@ -47,7 +47,7 @@ support Python 3.6 through 3.9: ``python_requires='>=3.6, <3.10'``. Verifying Support ----------------- -The best way to validate support of a Python library's support of a version of +The best way to validate whether a Python library supports a version of Python is to validate it via unit testing within CI/CD. An example GitHub workflow testing Python 3.6 through Python 3.10 on Windows and Linux would would start with:: From b9192777e300056f2c20784dc13dddccdb1fdfe5 Mon Sep 17 00:00:00 2001 From: Alex Kaszynski Date: Mon, 24 Jan 2022 10:52:33 -0700 Subject: [PATCH 6/6] Update doc/source/guidelines/version_support.rst Co-authored-by: Kathy Pippert <84872299+PipKat@users.noreply.github.com> --- doc/source/guidelines/version_support.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/guidelines/version_support.rst b/doc/source/guidelines/version_support.rst index d0f6949e7..b9a990f2e 100644 --- a/doc/source/guidelines/version_support.rst +++ b/doc/source/guidelines/version_support.rst @@ -25,7 +25,7 @@ Python earlier than their end of life (EOL) as outlined in `NEP 29 Realize that users can still install the older version from PyPI via ``pip`` as the package manager (``pip``). When ``pip`` is used, it downloads and installs the most recent version -of THE library that supports your version of Python. You can enforce a minimum- +of the library that supports your version of Python. You can enforce a minimum- required Python version within ``setup.py`` with: .. code:: python