My proposal for a deprecation message:
trigger_error('Using $noWSOL as second parameter will be removed, use your custom database query for it', E_USER_DEPRECATED);
trigger_error('Configuration option XYZ will be removed, use ABC instead,', E_USER_DEPRECATED);
trigger_error('Configuration option XYZ will be removed. See Breaking-12345.rst', E_USER_DEPRECATED);
For a method this should be the rule:
trigger_error('getUserObj() will be removed, use GeneralUtility::makeInstance() instead.', E_USER_DEPRECATED);
Where the method comments should have a @deprecated information with more information because this is not logged anymore.
@deprecated will be removed in TYPO3 v10.0, if still necessary, rebuild it on your own by copy over the code in your function. See Breaking-12345.rst for more details.
- “has been deprecated” and especially “since TYPO3 v8.2” should not be used anymore AT ALL.
- “will be removed” does not contain a version in the trigger_error call.
- deprecating a method should have trigger_error() and @deprecated, and trigger_error should contain the method name (although we could get this through the backtrace as well)