Deprecations: break out multiple deprecations into multiple files

[glendaviesnz]

What problem does this address?

1. Currently block deprecations are all contained in a single file, and within that file each deprecation is declared as an object literal within an array. This presents the following issues as the number of deprecations for blocks increases (eg. Cover and Gallery have 6+ deprecations):

• When debugging deprecation issues it is hard work going through the likes of a 500+ line Object[] definition working out where one deprecation starts and another finishes
• For devs new to deprecations there is no indication in this structure that the newest deprecation is the first in the array and the oldest is last, and this ordering is of reasonable importance in order to optimise deprecation performance

2. As well as the manageability of the single file the other potential issue with deprecations is the fact that shared utils imported and used by the block save method continue to be imported from the main block code by the deprecation save methods. This can lead to tricky to find bugs with deprecations when those shared methods are changed. In order for deprecations to be successfully applied and their save method to return a valid block all the methods used by the save function need to continue to return the same output as when that version was the current one.

What is your proposed solution?

The above issues could be mitigated by:

• Breaking deprecations up into separate files within a deprecations/ folder once more than a single deprecation is added
• Naming each deprecation object as the version of the block it applies to, and then adding this to the deprecation array, which gives an indication of the required order, eg. const deprecations = [v3, v2, v1];;
• In the deprecations folder include a shared.js file to which the local imports used by the deprecation can be added to ensure they remain static.
• As new deprecations are added that use different versions of a shared local method it can be added to this file directly under the existing one with V2, etc. added to the method name.

Using this approach, standard IDE functionality can be used to easily identify which version of methods is used by which deprecation, eg.

There is an example PR here which shows how this approach would look with the Cover block.

An alternative to this approach is to follow the structure adopted by Jetpack which is to have each deprecation in its own sub folder, which might allow better isolation of any additional utility code used by a specific deprecation's save method.

It would be good to hear what others think, eg.

• Is this a problem that we should be looking to fix?
• If so are the above suggested fixes feasible?
• Or, is there a better way to improve the usability/maintenance of deprecations?

[Mamaduka]

Thanks for the proposal, @glendaviesnz. I agree this would make deprecation management more straightforward.

allow better isolation of any additional utility code used by a specific deprecation's save method.

Those can be inlined in the version desperation file itself. That being said, I don't have strong opinions about the directory structure.