Deprecation policy

[Kludex]

I think we should create a deprecation policy. Today, the way we deprecate code is too ambiguous.

Things we need to answer:

• For how long a code is supposed to be deprecated? Based on version, or time?
• How should we format the deprecation message?
• Anything else?

cc @encode/maintainers

[Kludex]

For how long a code is supposed to be deprecated? Based on version, or time?

I think this is not as important as having the policy itself. I'd be in favor of having it, either by time or version. Something like 3 minors, or 4 months... I guess there's no ideal number here.

How should we format the deprecation message?

I think it should mention the time it will be removed. Example:

"GraphQL support is deprecated since version 0.1.0, and it will be removed in version 0.4.0."

We can include the PR/issue as context on the deprecation message as well...

[adriangb]

This sounds good to me.
I think having the target version in the warnings helps a lot, and gives us a bit of room to wiggle based on "how breaking" the change is.

[Kludex]

Also, we should think about the deprecation of Python versions.

[Kludex]

All current code that is deprecated will be removed in 1.0.