#10635 was merged which formalises our policy on deprecation warnings on
internal APIs a little more - those that a plugin may use, not REST APIs.
I've updated the wiki in two places with more info:
http://projects.theforeman.org/projects/foreman/wiki/How_to_Create_a_Plugin#Foreman-compatibility
http://projects.theforeman.org/projects/foreman/wiki/Reviewing_patches#Deprecation-warnings
Essentially, if a deprecation warning is added then the warning and
deprecated method will be shipped for two major releases (e.g. 1.9 and
1.10) and removed in the third (1.11).
If your plugin triggers a deprecation log message, you have quite a
reasonable amount of time to issue updates.
We're tracking removal of the code in tickets such as #10988 and #10989
to be done immediately after branching the last deprecated release, e.g.
immediately after 1.10-stable then we should be deleting it.
Note that it's no guarantee that a deprecation warning will be added and
compatibility maintained, but I think that's getting better as our
internal APIs become clearer.