Proposing a New Module

Do you have an idea for a new performance-related feature for WordPress coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress.? Excellent! The Performance Lab plugin is a great way to implement and share the feature early on so that it can be tested on live sites and refined prior to an eventual WordPress core merge.

Proposed or upcoming WordPress core features are also called “feature projects.” In the Performance Lab pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party, every feature project is implemented as a module within the plugin, so that end users can individually enable or disable them. Creating a module within the Performance Lab plugin is very similar to the way that you would create a standalone plugin. For more information about the coding requirements for a module, see the Writing a module section below. This guide is focused on how to propose your module so that it can become part of the Performance Lab plugin.

Lifecycle of a performance module

  1. Module proposal: This is where the module is proposed, by opening a new module proposal issue on the Performance Lab plugin’s GitHub repository. Following the requirements around feature projects, the issue should briefly explain why the project is important to WordPress and how it fits in with the values and philosophies of WordPress. During this stage, the module purpose and scope, as well as basic information like module name, slug, and ownership are defined. The Performance Team then discusses the proposal in one of the weekly SlackSlack Slack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/. meetings and eventually makes a decision whether the module proposal is accepted or needs to be refined.
  2. Exploration and definition: This is where the primary module’s future implementation is being fully defined, after the module proposal issue has been accepted. This phase should begin with research and discovery around the feature, which then leads to a design doc and/or a proof-of-concept pull request for the module’s foundation. Most modules will require multiple issues and pull requests to be completed, but it can help to build a solid foundation through the initial pull request, so that a first version of the module can be reviewed and tested.
  3. Core feature proposal: This is where the feature gets proposed for eventual inclusion in WordPress core. After the initial definition phase for the feature, the next step is to formally propose it as a core feature project and share it beyond just the Performance Lab plugin users. This is done by publishing a feature proposal post on the Make WordPress Core blog as well as creating a ticket on Core Trac. The post should reference the module in the Performance Lab plugin as the recommended way to follow along, contribute, and test the feature. This stage is where many more WordPress community members will become aware of their project – expect a lot of additional feedback at this point!
  4. Module implementation: This is where the module is primarily being developed and eventually completed for its intended scope. Based on the feedback on the feature proposal, the initially envisioned approach may require a few adjustments. If a proof of concept was already created during the definition phase, it can now be iterated on, or alternatively the implementation can begin from scratch. As the enhancements to the module are merged into the Performance Lab plugin, users of the plugin will continuously be able to test the latest version of the feature.
  5. Core merge proposal: This is where the completed module implementation is proposed for a near-future merge into WordPress core. This is done by publishing a merge proposal post on the Make WordPress Core blog. This post should go a bit more into depth on the feature implementation eventually decided on, explaining some of the decisions made and referencing back to the original feature proposal post as applicable.
  6. Core patch: This is where the module implementation is ported into a WordPress core patch or pull request. Depending on the complexity of the feature, it may see more or less feedback after the merge proposal, and in most cases, a few refinements will be necessary to further improve the implementation based on contributor feedback. There is no fixed recommendation on when to create the core patch. It can be started before publishing the merge proposal, but it may be a good idea to wait for the initial merge proposal feedback in order to avoid having to do duplicate work (since preferably any necessary refinements would need to go into the Performance Lab module and the core patch).
  7. Core merge: This is where the feature actually gets merged into WordPress core. Once there is consensus among the core developer community that the core patch is good to go, it can be committed to WordPress core. It will then be included in the upcoming WordPress release. 🎉
  8. Dev note: This is where the finished implementation is described in detail, with a technical focus on any customization or extension capabilities. This is done by publishing a dev note post on the Make WordPress Core blog. It does not need to happen right after the core merge, but it should happen any time between the merge and the RCRelease Candidate A beta version of software with the potential to be a final product, which is ready to release unless significant bugs emerge. release of the version in which it ships.

It is important to understand and think through these stages when proposing a module, as getting a module into the Performance Lab plugin should be a temporary state that is a stepping stone to getting the feature into WordPress core. Every proposed module should have at least one defined owner that takes responsibility for eventually moving the module forward.

It is understandable that this can feel like quite the tedious task – however, rest assured that the rest of the Performance Team is there to help. If you have never posted anything on the Make WordPress Core blog, don’t worry – there are people on the team who can get you access and review your post drafts. If you have never contributed to the WordPress core codebase, don’t worry – there are people on the team who can review your code for core best practices. If you have never committed anything to WordPress core, don’t worry – there are people on the team who can do that for you. You can always ask any questions you have in the #core-performance Slack channel or, even better, during the open floor segment of the weekly chats in that channel.

Top ↑

Requirements for a new module

Based on the above lifecycle for a module, there are a few initial requirements for proposing a new module. The Performance Team would like to ensure that modules inside the Performance Lab plugin keep moving forward over time, and the requirements outlined here help set the foundation.

Other than outlining the purpose and scope of the module, every module proposal issue should define the following by using the new module proposal issue template:

  • The module name, i.e. what users see as the name for the feature inside the Performance Lab plugin. It is a good idea to use something that eventually can also act as the name for the feature project for WordPress core.
  • The module slug, i.e. the internal identifier for the module. Usually, this can be based on the module name, “slugified” (e.g. “My Module” becomes my-module).
  • The focus area the module belongs to. See the perflab_get_focus_areas() function for the currently available focus areas.
  • One or more owners for the module (via GitHubGitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/ usernames), to take responsibility for the module on its path towards WordPress core, also to be added as code owners for the module.

Every module proposal issue must have the “[Type] Module” label to indicate it as such. The New module proposal issue template should be used when opening such an issue.

Top ↑

Technical requirements

Implementing the foundation for the module’s key functionality as part of the initial module proposal PR can be useful (even just as proof of concept), but is not necessary.

However, as a minimum requirement for the module proposal, a pull request should add the new directory for the module (with a .gitkeep file in it) and amend the CODEOWNERS file to include the new module’s directory and the GitHub usernames of the module owners.

In addition to that, a new label for the module like “[Module] My Module” (where “My Module” should be the actual module name) should be created on GitHub and assigned to the initial module proposal issue and later any other issues related to the module.

Last updated: