Consider a better way to deprecate JavaScript code

[SergeyBiryukov]

Background: #51123

At the moment, we have some established functions for deprecating PHP functionality:

• _deprecated_function()
• _deprecated_constructor()
• _deprecated_file()
• _deprecated_argument()
• _deprecated_hook()

As well as some files to move deprecated functions to:

• wp-admin/includes/deprecated.php
• wp-admin/includes/ms-deprecated.php
• wp-includes/deprecated.php
• wp-includes/ms-deprecated.php
• wp-includes/pluggable-deprecated.php

We don't, however, have a similar way to deprecate JavaScript functionality, sometimes leading to more breakage than necessary when removing global objects or properties without backward compatibility considerations.

[48923] attempted to improve things a bit introducing deprecatedProperty().

Some ideas previously suggested to further make sure we have a way to deprecate JavaScript code properly:

• Have a clear deprecation policy of when the affected code should be removed.
• Use the ​@wordpress/deprecated package (suggested by @ocean90 in comment:33:ticket:51123).
• Create a deprecated.js file for the code to be moved to (suggested by @desrosj on Slack).

[youknowriad]

In terms of code, I think the deprecated package is the way to go here IMO (available as wp-deprecated script on Core), it was created for this purpose. that said, I'd love a clear strategy about when code should be removed.

I encourage you to bring this as a topic to #core-js meetings.