Add deprecation policy

[Kludex]

@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?

[tomchristie]

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?

[Kludex]

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? 🤔

[Kludex]

I've applied comments, and applied what the policy states on all warning statements.

[adriangb]

From meeting: let's add info about when we add warnings.

[Kludex]

This is the "when". Should the wording be changed? @adriangb

[adriangb]

I think this is saying when we will deprecate the feature, the question was when do we put in deprecation warnings. Can users expect deprecation warnings to show up at any time, only in minor releases or only in major releases?

[Kludex]

The act of deprecating a feature is adding a deprecation warning. At least, this is how I understand.

[adriangb]

How about:

Suggested change

	Starlette will deprecate a feature in the next minor release after the feature is marked as deprecated.
	Starlette will deprecate (completely remove or break) a feature in the next major release after the feature is marked as deprecated (via a deprecation warning). Features can be marked as deprecated in any minor release.

[Kludex]

I'll apply something on that line.

[Kludex]

• Closed in favor of Version 1.0.0 #1888