I like how Elixir deals with deprecation in its stdlib:
-
soft deprecation in version X:
- warning in docs
- no compilation warning
-
hard deprecation in version X+n:
- removed from docs
- compilation warning
It gives some time to adapt software without being annoyed.
For example libraries can wait for the hard deprecation and not care about backward compatibility with Elixir < X yet still be compatible with the latest n releases.