The suggestion is to establish a pattern of adding the following code to deprecated functions:
// This is just an example. Write whatever -- something to point people in the right direction.
$sMessage = 'save() has been deprecated in favour of using the usage of repositorties, and the deferral of persistence to the persistence layer. See https://h.dev.magento.com/repositories for further details'
@trigger_error($sMessage, E_USER_DEPRECATED);
This can be introduced harmlessly to the stack, and does not actually change any error behaviour, or make the deprecated methods more fragile. However the error handler indicated by set_error_handler() will be called; allowing the surfacing of the deprecated methods.
This is useful in a couple of ways:
- Tests can stub the error handler such that it propagates these error messages and fails tests. This clearly indicates that the code is no longer valid.
- The error handling function can be modified such that in developer mode these errors are surfaced to the user, and either halt execution or are simply logged to the debug log
- State of "known violations" can be tracked (perhaps simply with a try_catch in tests, with a skip or the like). This means that any new code must either violate the deprecation intentionally (picked up in review) or fail tests (picked up in CI)
This pattern has been previously established by Symfony[2][3] and appears to work as expected there. Such work will allow enforcement of deprecation; something that has proved problematic in the past (particularly in code review where it's not apparent that used functions are deprecated)