Changes to the deprecation window in 1.8+ #15049
Description
🚀 Augmented deprecation window
Motivation
We currently have the following deprecation pattern:
- Deprecate an API in v1.x and emit a warning.
- Remove the API in v1.(x+2) together with the warning.
This is documented in our API Evolution section in the docs.
We have found that is very common that users don't update their projects very often, but when they do they jump more than two minor versions, for example from v1.4 to v1.8. In such cases, they miss deprecation messages entirely and end up with silent, undocumented behavior that is hard to debug.
Pitch
We propose to implement a new pattern:
- Deprecate API in v1.x with a warning for removal in v1.(x+2). Same as before.
- Remove API in v1.(x+2) and convert warnings to errors.
- Remove errors for removed APIs in v2.0.
This is meant to balance development speed with giving good feedback to users coming from an old version of Lightning.
Here is an example PR that will start this new pattern: #14835
Exceptions
There will likely be exceptions where this pattern can't be followed. As a rule of thumb, we say that this should apply to every API or behavioral deprecation, but on a case-by-case basis we will also evaluate feasibility and decide based on that whether an exception can be made.
TODOs
- Update our docs regarding API Evolution section
- Apply the new pattern to the recently removed APIs in 🚀 Remove deprecated APIs for 1.8 release #14841
Alternatives
None.
Additional context
Work done in #14841 will partially have to be undone.