Add: text on which python version(s) to support to the packaging guide

[lwasser]

make sure in the maintainer section that we include discussions of what versions of python to support. the scientific python spec 00 is what we want to ideally promote here. see comment thread below:

https://github.com/pyOpenSci/peer-review-guide/pull/148/files#r1049888878

[ucodery]

What I'm getting from the earlier thread is that we do want to put forward Python's official EOL timeline (recommend supporting the latest stable version, and no further back than versions still getting security fixes) and we don't want to support NEP-29 (because it's not a community decision, and possibly too specific to recommend generally). I'm confused if we want to recommend SPEC 00 as it is a community guide (and now appears to be accepted) but is also specific to certain requirements graphs. Do we want to recommend this iff the project used one of those deps?

[willingc]

@ucodery As for Python itself, I would recommend latest stable and versions that are still getting bug fixes. If you are on a security fixes only version, then you should consider migrating to a more recent version.

I'm not sure that we want to recommend SPEC 00 beyond making folks aware that it exists.

[lwasser]

thank you both. i'm looking at some of these old issues too - to see if we can close or mark them help-wanted!

i agree with you both -

1. we could (optionally) add a small breakout about the scientific python spec just so people know about it.
2. we could link to that awesome graphic that shows the planned release cycle
3. i think we also would want to explain how someone would look at that graphic and understand which versions are getting updates? i look at it and assume that 3.8-3.11 are ONLY getting security updates? but not bug fixes? 3.12 is actively being worked on for bugs and 3.13 is getting updates/ features. is this correct? even if it isn't i think linking to the graphic via a image link and explaining how to understand it would be valuable!

What do you both think? i'll mark this help wanted and clarify the title

[lwasser]

btw i created this little github project board automation that adds any issues with help-wanted to our project board. it's working so well!!

[lwasser]

also would this be a short new page or a section in the pyproject.toml or dependency page perhaps?

• https://www.pyopensci.org/python-package-guide/package-structure-code/declare-dependencies.html
• https://www.pyopensci.org/python-package-guide/package-structure-code/pyproject-toml-python-package-metadata.html

[ucodery]

I believe you read that diagram exactly right Leah.

Hmm, I don't think this rises to the level of new page (maybe we'll see when it's written). I think it should go in declare-dependencies but it will need a new section. We currently don't mention the requires-python metadata in there at all (it gets a single mention in the pyproject-toml-python-package-metadata page, and is described during the tutorial).

IMHO we should clarify that it is an optional field, that it doesn't need to be set unless you know there are problems using an older version, and that some maximum supported python version should never be set (no <). Maybe a callout saying if you absolutely must and can confirm that the upper limit does in fact break your project.

This might also be a good place to remind authors that classifiers do not in any way influence dependencies and that they are not a replacement for using python-requires. Also that it can nonetheless be very confusing to let python-requires and chosen classifiers get out-of-sync.

Coming back to the question of concretely which versions a project should support (and support is different than python-requires. IMO support is an include-list - these are known to work, probably even tested. If the python version fails a python-requires check it is on an exclude-list - its known to be bad. There can be a lot of grey in between). I think there has already been a mis-communication here. When I first posted

recommend supporting the latest stable version, and no further back than versions still getting security fixes

I was thinking about supporting a library. I think it is reasonable that a library author support all versions also currently supported by CPython - although authors are free to do what they want and can just support bug-fix releases. And certainly if the library only makes sense coupled with newer Python features, that could also exclude otherwise fine-to-use versions.

For an application developer it probably makes more sense to try and stay on the latest version all the time and it is also okay so support a smaller version range; maybe no range, only a single version. If you have got behind enough that you are on a security release then maybe upgrading should be a high priority, but no harm yet, not until the version goes EOL, IMO.

Supporting the beta version of Python is good for the community overall, but can be a lot of extra effort for a maintainer, with maybe little to no benefit to the current work.

[lwasser]

@ucodery i'm going through old issues. I agree - it would be PERFECT in the requires-python section of the guide / metadata etc. We could also use a target in myst to allow for a link that we surface on the home page

(python-version)=
## Python versions

How about this takeaway here:

1. Add a small breakout on the scientific python spec so people are aware of it. And tell them that is a option if they want to follow
2. Use @willingc language which aligns with the core Python ecosystem more closely:

I would recommend latest stable and versions that are still getting bug fixes. If you are on a security fixes only version, then you should consider migrating to a more recent version.

Note: i'm always slow to upgrade to a new version. stravalib just dropped python 3.9. I'm still using 3.10 throughout. So i like the idea of providing options but suggestions they consider supporting versions that are getting bug fixes. but also that users may still be on the versions that are getting security fixes.

Do you both agree with that approach? then someone could work on this if we agree.

[ucodery]

I think this is the best summary of PyOS recommendations