Deprecation Policy

[danieleades]

This project doesn't have a visible deprecation policy.

• there is code commented as 'deprecated' through the codebase. when should that get removed? would something like deprecation be welcome here?
• when should old python versions be dropped? It's nice to support as wide a version range as possible, but it's getting more and more common to use python in isolated environments that allow users to have the latest packages (pyenv, poetry, pdm, pipenv, etc). On top of that, it means you miss out on new features that have the potential to streamline the codebase. dataclasses spring to mind, and they're not supported until python 3.7
• this project supports python 3.5, which is now 'end of life'. can this be dropped?
• this project doesn't actually test python 3.6 support, presumably because it's a nightmare trying to find a compatible combination of dependencies (i know from experience in migrate to Poetry #154!). can this also be dropped? if not, when should it be dropped?

[danieleades]

i guess i'm talking about two different things here

1. deprecating APIs
2. interpreter version

the first is easier. sphinx-needs is <1.0.0, which implies that you can freely make breaking changes on minor version bumps. A slightly aggressive approach would be to add a deprecation warning in 0.x.* and the remove in 0.x+1.*
Once sphinx-needs hits 1.0.0, this would become- add warning in x.*, remove in x+1.*

interpreter version is harder. Officially, each interpreter version is supported for 5 years from release

• python 3.5 was end of life 5/9/2020
• python 3.6 will be end of life 23/12/2021 (in 10 months)

in practice however, I don't know of any distributions that are now shipping with python <3.8

If an older interpreter version can be supported without any additional pain, then why not? On the other hand, I don't see much value in supporting an interpreter version which is 3-5 years old if that restricts you from using language features which can benefit the project (*cough* dataclasses).
It's also worth considering the environment in which this package is going to be used. How likely is it really that an engineering company using Sphinx-needs to generate documentation is going to be unable to use a version of python released in the last 5 years? Development machines, CI servers, and, increasingly, isolated build environments (through the use of package managers like Poetry, pipenv, pyenv) mean that developers generally have access to bleeding edge packages and interpreter versions.

The way semver handles interpreter version bumps seems to vary between languages. Rust for example seems to be arriving at a consensus that bumping the minimum compiler version is a 'minor' change to a project (a >=1.0.0 project, that is). That seems reasonable to me.

If someone really can't upgrade to a more recent interpreter version, then they have access to older versions of Sphinx-Needs. If they want the latest version and features, they need to upgrade. That's pretty standard.

I guess what i'm saying is i think bending over backwards to support old versions is great practice, but after a point it becomes far more trouble than its worth.

All of this deprecation policy belongs in a CONTRIBUTING.md (or I guess .rst could be more appropriate for this project!)

[danwos]

Nice write up and good points overall.
Thanks for this input 👍

Have not much time, but one additional argument / basement on how to decide which Python versions to support, is the upstream project.
So in this case Sphinx itself.
E.g. if Sphinx 3.1 support Python 3.5, we need to support Python 3.5 for Sphinx 3.1 as well.
So Python and Sphinx-versions are fixed coupled, defined by Sphinx team only.

Not really sure if this would makes things easier. Have to think about it :)

[danieleades]

i'm not sure that logic follows. It makes sense for the upstream project to be the most permissive, in order to support the widest possible ranges of plugins, some of which may no longer be well-maintained (and makes little sense for any downstream project to be more permissive than the upstream project!), but i don't believe that the converse is true.
Since Sphinx doesn't depend on sphinx-needs, there's no reason that sphinx-needs needs to target the same compatibility range as sphinx.

It's desirable, obviously. But I fail to see that they're 'coupled'. The compatibility range of Sphinx simply places an upper bound on the compatibility range of sphinx-needs, no?

but even if the conclusion is that "sphinx-needs targets the same python version as the latest release of sphinx" then that could be captured somewhere.

[danieleades]

Heads up, sphinx has dropped python 3.5 support in the 4.0 release - sphinx-doc/sphinx#7264