Nextgen Bootstrap/Load Feature Project

The bootstrapping process of WordPress Core (affectionately called the “Bootstrap/Load” component around here) is a critical piece of the system, and everything else depends on it being reliable and performant. However, developers and system administrators also need it to be flexible enough to adapt to the requirements of their differing projects or environments. Large-scale WordPress installations often require substantial customizations to adjust for scalability and redundancy.

Considering the importance of this component, the documentation is not adequate, and very few people actually know what the exact flow is. More importantly, there isn’t a wide understanding of why specific decisions had been taken, and how later code depends on the bootstrap process.

This proposal aims to launch a feature project to work on the next iteration of the bootstrap component with a set of specific goals in mind.


To be able to guide the design process and have measurable success metrics, clear goals need to be defined.

Here’s an overview of what specific goals the project should aim for:

  1. The component has proper documentation for every step of the process.
    Documentation will include both clear comments in the source as well as an external documentation space that includes reference material, execution flow diagrams, best practices and examples of usage.
  2. The component models a modernized flow which still provides same sane defaults, but enables advanced use cases in a supported way.
    Customizing high-volume sites or specialized applications should be less “hacky”, and all of the major subsystems should provide reliable means of configuration/extension.
  3. The component adapts to differing contexts to optimize both performance and memory consumption where possible.
    The system should be able to intelligently load only the parts of the code that are strictly necessary for the current requests, through means of conditional execution flows, smart routing, proxy objects and autoloading. Special consideration should be given to the WP REST API endpoints to make them as fast and efficient as possible.
  4. The component offers a coherent way of supporting all versions of multisite (networks), reducing some of the idiosyncrasies that currently exist.
    The difference between single sites, networks of sites and networks of networks should be kept as small as possible so that less care needs to be taken to have the code work reliably with all of them.
  5. The component considers both backward compatibility as well as forward compatibility.
    It is of paramount importance that existing sites do not break due to the changes that will be proposed with this project. However, forward compatibility needs to be taken into account just as well, to create a next version of the bootstrap component that can easily grow with future requirements in a controlled way.

Project Phases

The project will have four different phases: Discovery, Design, Execution and Merge Proposal.

1. Discovery

The Discovery Phase aims to properly research and document the status quo. It will be a thorough analysis of source code, trac tickets and contributor discussions to decipher the reasoning behind the current implementation and what the requirements, strengths and weaknesses are. Documentation will be written in parallel, logging all findings and producing a better onboarding process for this component. Characterization tests will be written to be able to detect regressions when making changes in phase 3 later on.

2. Design

The Design phase will examine all the findings from phase one to design a new version of the bootstrap component that meets all the requirements and strengths while reducing some or all of the weaknesses and improving reliability, flexibility and performance.

We want to avoid having yet another component update that just grows organically. There should be strong principles in place that make sure that the new version is not only backward compatible but also forward compatible.

3. Execution

The Execution phase will create a modified fork/branch of WordPress Core, to allow for collaborative work on this new iteration of the bootstrap component.

Through automated tests, refactoring will be guided to implement the design from phase 2. The characterization tests from phase 1 will make sure that compatibility remains a given, even for “compatibility-enforced bugs”. Optional mechanisms to get saner results in such cases will be discussed on a case-by-case basis.

4. Merge Proposal

The Merge Proposal phase will be the final phase of the project, identifying a clean merge process and a proper migration path to merge the new version of the component into Core.

Metrics will need to be defined to have measurable and achievable goals that can objectively tell whether the Component is ready to be merged.


During the initial Discovery Phase, contributions in the following areas will prove to be useful:

Advanced Use Cases

We need lots of data about the types of customizations that people use for their projects: bootstrap modifications (WP-CLI), complex network hierarchies, folder rearrangements, specialized caches, etc.

Problems With Current Code

We need to know about all and any challenges and limitations that you have been experiencing with the current bootstrapping flow: setups that were difficult or impossible to achieve, settings that didn’t yield the expected results, etc.


Documentation will not only need to be written for the way the current code works, but also for all deprecated functionality, buggy behavior and unexpected side-effects. We are going for completeness, not ease-of-use here. Documentation should also cover best practices for modifying the bootstrap process.

Join us in #core-bootstrap to start contributing!

Thanks to Helen Hou-Sandì (@helen), Jeremy Felt (@jeremyfelt) and Aaron Jorbin (@jorbin) for their help in shaping this proposal.

#bootstrap-load, #core