Core Platform Team/Initiative/Reduce Extension Interface Surface Area/Initiative Description

< Reduce Extension Interface Surface Area

Summary

Currently, extension code is very highly dependent upon MediaWiki core code. If a change is made to the parameters passed to a hook or the public interface to any of the core PHP classes, for example, it is likely that extension breakage will occur. Extensions currently rely extensively upon global state, which also introduces fragility.

This project will reduce the level of dependence of extensions upon MediaWiki core code by reducing the breadth of the interface through which extensions access MediaWiki core. This will be done by specifying a limited set of mechanisms by which extensions can access core, reducing the parameters that are passed to extensions to only what is necessary, and eliminating global state. The new interfaces will be documented for extension developers.

There are three mechanisms that have emerged over time by which extension code and core code interact:

1. Extension code can be registered with the Extension Registry so that the extension code will invoked during execution of core code. Code of this type falls into four broad classes: action hooks, filter hooks, handlers, and services.
2. Extension code can directly call any public core function to which it has access.
3. Extension code can call core code through a web API (action API or REST API). This is usually done from JavaScript to add dynamic behavior, but can be done from PHP as well. (This mechanism is out of scope for this project as it is covered by another project.)

This project will examine each aspect of the first two mechanisms listed above to do the following:

1. Analyze current usage
2. Propose improved interfaces with reduced surface area (RFCs, as necessary)
3. Create deprecation and migration plan
4. Incrementally, for each new interface:
   1. implement new interface
   2. document new interface for extension developers
   3. deprecate old interface
   4. migrate extensions to new interface

This work has already begun with RFC: MediaWiki 2018 extension interfaces, which proposes action hooks and filter hooks. Once this RFC is approved, analysis of current hooks will begin to migrate existing hooks to the new hook interfaces. According to mediawiki.org, there are roughly 680 hooks currently defined in MediaWiki core.

Significance and Motivation

This project aims to reduce the surface area of the extension interface so that the scope of changes to core that will affect extensions will be reduced. This will enable core developers to more confidently make changes to and improve core while reducing the need of extension developers to frequently react to changes in core that break their extensions. Constraints put on extensions by this new approach will yield dividends in the increased stability of the interface between core and extensions.

Outcomes

Reduce complexity in core

To measure success, we need to survey extension code and produce reports about the metrics:

• Percentage of hooks used by active gerrit-hosted extensions that are old style hooks
• Count of access to unacceptable global state by active gerrit-hosted extensions
• Count instances of instantiation of core classes

Methodology: code search and static analysis tools where necessary

Baseline Metrics

• Percentage of hooks used by active gerrit-hosted extensions that are old style hooks: 100%
• Count of access to unacceptable global state by active gerrit-hosted extensions: <count>
• Count instances of instantiation of core classes: <instances>

Target Metrics

Project Target

• Percentage of hooks used by active gerrit-hosted extensions that are old style hooks: below 50%
• Count of access to unacceptable global state by active gerrit-hosted extensions: below 50% of <count>
• Count instances of instantiation of core classes: below 50% of <instances>

Optimal Target

• Percentage of hooks used by active gerrit-hosted extensions that are old style hooks: 0%
• Count of access to unacceptable global state by active gerrit-hosted extensions: below 0
• Count instances of instantiation of core classes: 0

Stakeholders

None given

Known Dependencies/Blockers

None given