encode
Add deprecation policy
@tomchristie Should we present the deprecation policy as this PR proposes, or should we also include the versioning policy we aim to follow, and maybe discuss the branch strategy?
I'm mentioning the branch strategy in case we want to backport security patches to previous major versions.
In any case, what do you think about this PR?
Thanks @kludex. I think my main suggestion here would be to highlight that we use SEMVER, and then to clarify what that means in the context of python versions, pre-1.0, and deprecation warnings.
The bits which I think are obviously what we want here are then...
- We use SEMVER. https://semver.org
- With some further additional constraints...
- While we are pre-1.0, we treat any SEMVER changes requiring a "major" bump as a change requiring a "minor" bump. We treat any SEMVER changes requiring a "minor" bump as a SEMVER change requiring a "patch" bump.
- We'll support Python versions until they are EOL. Dropping a Python version is considered a backward incompatible change, and so requires a major version bump. (Or a "minor" version bump while we're still pre-1.0)
Less obvious to me is exactly what we would like wrt. warnings. Possibly the least confusing wrt. to SEMVER, would be...
- Where possible we will warn of any upcoming backwards incompatible changes. Introducing a new warning requires a "minor" version bump. (Or a "patch" version bump while we're still pre-1.0).
That last one is not quite what we've talked about in the past, but actually I think it'd align more simply?
We'll support Python versions until they are EOL. Dropping a Python version is considered a backward incompatible change, and so requires a major version bump. (Or a "minor" version bump while we're still pre-1.0)
I don't think this statement is a consensus on the Python community. Packages like coverage bump minor when dropping Python versions: https://coverage.readthedocs.io/en/6.4.1/changes.html#version-6-3-2022-01-25. I'd also prefer to bump minor here.
That last one is not quite what we've talked about in the past, but actually I think it'd align more simply?
Sure.
Also, I've been thinking... Maybe we can agree to not remove code that is deprecated before we are ready to 1.0 i.e. when we are about to release 1.0 we remove all code with warnings. What do you think? :thinking:
I've applied comments, and applied what the policy states on all warning statements.