Define basic module specification

[felixarntz]

Before starting to write code for any modules, we will need to define exactly what a module should look like. Some ideas for this were already mentioned in the plugin proposal doc, so let's use this issue to expand on those.

The performance plugin should eventually include a settings page that lists all available modules, where the user can individually toggle them on/off.

The proposal is the following:

• Every module should have its production code located in a /modules/{moduleSlug} directory.
• Every module should have its tests (PHPUnit and potentially Jest etc., as applicable) code located in a /tests/modules/{moduleSlug} directory.
• Every module should have a /modules/{moduleSlug}/load.php file that should be the "initialization" file of that module. Simply requiring that file in other PHP code should trigger that module's functionality - i.e. it should be similar to how WordPress plugins work.
• Every module should work fully standalone and neither rely on any external dependencies nor on any code that is in a central location of the performance plugin (i.e. it should not require any PHP code from outside its own module directory).
• Every module should have a PHP comment header that is somewhat similar to how plugin headers or module headers in some other plugins (such as Jetpack) work. More specifically, the following fields should be specified:
  • Module Name: The title of the module (comparable to Plugin Name for plugins). This should be displayed on the performnace plugin's settings page.
  • Module Description: Brief description of the module (comparable to Description for plugins). This should be displayed next to the module name on the performance plugin's settings page.
  • Module Focus: Identifier of a single focus area (e.g. images, or javascript, or site-health). This should correspond to a section on the performance plugin's settings page.
  • Experimental: Either Yes or No. If Yes, the module will be marked as explicitly experimental on the performance plugin's settings page. While all modules are experimental to a degree (since they are like feature plugins), for some this may apply more than others. For example, certain modules we would encourage limited testing in production for, where we've already established a certain level of reliability/quality, in other cases modules shouldn't be used in production at all.
• Other than the above, a module can be implemented in pretty much any way, there are no architectural requirements. However, it needs to be considered that, since modules should eventually target a WordPress core merge, it is encouraged to not diverge too much from coding patterns that are already established in WordPress core.

Here's a sample module header based on the above:

/**
 * Module Name: My Performance Module
 * Module Description: Optimizes x by doing y.
 * Module Focus: images
 * Experimental: No
 */

Let's discuss here. Once we've decided on the approach, a good takeaway from this issue would be to create a PR where we put the resulting specification into either README.md or another (documentation) markdown file in the repository.

[tillkruss]

Should we add GitHub and WP.org usernames maybe as well to indicate code ownership?

[felixarntz]

@tillkruss Maybe, although to my knowledge this isn't an established approach for WordPress and may seem somewhat "gatekeeper-ish". But I agree it would be useful for example to have certain folks automatically be assigned as PR reviewers. With all that said, I think this would be better off in its own issue, to go into some sort of CODEOWNERS file rather than the module header. Would you mind opening an issue for that?

[ThierryA]

Proposed module specification LGTM. Perhaps we should have a skeleton example as starting point for new modules.

[felixarntz]

I just opened #26 with documentation defining this. It follows what I outlined in the issue description above and includes a skeleton example.

The only change I made compared to the description above is renaming/shortening the module header fields Module Description to Description and Module Focus to Focus. The prefix here is unnecessary, and not having it is in line with plugins, which only use the Plugin ... prefix for the Plugin Name field, but not others.