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!)