Originally a follow-up tobut expanded to cover the more general case.
Drupal 8 has numerous deprecated functions and class methods.
There is at least one deprecated function argument.
Additionally there is deprecated functionality such as theme functions (which boils down to a deprecated info.yml key).
A few things to figure out:
1. We have no convention for documenting @deprecated for parameters. http://phpdoc.org/docs/latest/references/phpdoc/tags/deprecated.html does not help.
2. For some things like theme functions, we'd have completely removed support for them if we'd had time to it between removing core usages and the release candidate, and we'd like to actively discourage people from using them at all due to security concerns. E_USER_DEPRECATED could work for this.
3. For things that are just deprecated, we might also want to use E_USER_DEPRECATED - as part of the process of helping people get their modules ready for 8.x (i.e. if you can run all your tests without any E_USER_DEPRECATED, you know you're up to date with the bleeding edge of 8.x, rather than having to look through docs etc.).
Document the following (draft) as policy, https://www.drupal.org/node/2856615. This policy is based on Symfony's deprecation practices and will allow us to implement testing for deprecations.
Proposed GDO post
Updated deprecation process for Drupal 8 code
In Drupal 8, minor updates can introduce new APIs and features. When a new API is added, the old API will be deprecated in favor of the new one. We cannot remove the old API in a minor release because Drupal 8 makes a backwards compatibility promise, but it will usually be removed in the next major version (Drupal 9).
Contributed project developers, as well as those maintaining custom integrations, should follow the deprecations when possible and use the latest APIs available. This means that when Drupal 9 is released they will have to make fewer changes to be compatible.
From Drupal 8.3.0 onwards, in order to make the deprecation process as simple as possible for developers and users, we have created a new deprecation policy that details what can be deprecated and how.
* @todo Enforce the deprecation of each method once * https://www.drupal.org/node/2578361 is in.
(This issue is duplicate of that one.)
User interface changes
Data model changes