Consider renaming lib/compat PHP files and directories for evergreen overrides of core WordPress

[andrewserong]

What problem does this address?

Following on from a couple of comments on #38883 and related PRs.

One of the things that we've bumped into while making overrides to theme.json support in the lib/compat directory, is the potential confusion between which changes belong in the wordpress-5.9 and wordpress-6.0 directories (for backwards and forwards compatibility), and which overrides we'll need to maintain in perpetuity due to Gutenberg being the main place for development of global styles related features.

One way of looking at it is that the files in the lib/compat directory serve the following purposes:

• Maintain backwards compatibility with the current + previous WordPress versions
• Maintain compatibility with the current trunk of wordpress-develop
• Maintain evergreen overrides for core WordPress, that should always point to Gutenberg functions / implementations, to preserve the development environment (and experimentation of features that might not make it to core) in Gutenberg

What is your proposed solution?

1. Can we split out those evergreen overrides that we need to have to a separate directory, and add more documentation at the top of each file instructing how to use it?
2. If there are any files that we should not modify when making changes, is it worth adding additional linting to prevent accidental changes?
3. If we settle on a consistent layout that we'd like to go with (or if we have one already), is it worth us updating the backward-compatibility.md documentation to provide guidance on how we use this area?

The overall goal for this issue is to see what changes we can make to improve the developer experience on making updates to theme.json / global settings and styles, to hopefully make it easier for new contributors to contribute to or slot into development work in these areas.

[Mamaduka]

cc @WordPress/gutenberg-core

[oandregal]

👋 The general approach for any code is this:

• lib/compat/5.9 contains code that has been backported to WordPress and, therefore, its behavior can't be modified. It should behave the same as the code in the wordpress-develop repo for WordPress 5.9 (see for comparison). When the plugin updates its minimum WordPress version to 5.9 we remove this folder entirely.

• likewise, lib/compat/wordpress-6.0 is code that will be shipped in 6.0 and that we'll need to backport at some point. Having there only the deltas we need to modify (new functions, modifications to classes and existing functions, etc), helps with the backporting process.

Said this, backporting and maintaining two codebases in sync is one of the major struggles, especially for PHP code. There're other people with more experience than I have that can comment on the trade-offs and other approaches that have been tried, so I'll let them share their thoughts.

[gziolo]

For the full picture, there is #33810 where we discussed initial ideas for streamlining the process. As the first step, we should document the way things work today. It looks like people raise the same questions in other places so having one place to use as a reference would be great.

Edit: I found my last comment on the same topic where things get complex while backporting changes targeting a minor WordPress release. See #38681 (comment).

[andrewserong]

Just linking a PR from @noisysocks that will address documenting the current project structure for PHP files: #39603. Thanks Rob! 🙇