Core Platform Team/Initiatives/Reduce Extension Interface Surface Area

Reduce Extension Interface Surface Area

Product Owner:	Cindy Cicalese
Technical Contact:	Daniel Kinzler
Status:	Planning
Initiative Vision:
Initiative Description:	Read Edit
Epics, User Stories, and Requirements:	Read Edit
Time and Resource Estimates:	Read Edit
Open Questions:	Read Edit
Documentation Links:	Read Edit

Initiative Description

< Initiatives

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:

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.
Extension code can directly call any public core function to which it has access.
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:

Analyze current usage
Propose improved interfaces with reduced surface area (RFCs, as necessary)
Create deprecation and migration plan
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

Epics, User Stories, and Requirements

< Initiatives

Develop the product plan
Analysis and Design:
- Action and filter hooks:
  - Approve RFC for action and filter hooks
  - Enumerate all current hook points, and analyze their usage in extensions
  - Categorize current hooks as action and/or filter hooks and map parameters (identify any parameters that need to change/create new parameter types)
  - Develop deprecation and migration plan
- Access to core:
  - Define acceptable access to global state
  - Analyze which core code is called by extensions
  - Analyze what global state is accessed by extensions
  - Analyze which core classes are subclassed by extensions
  - Identify areas of core code that extensions should not access and identify alternatives
  - For each area of improvement identified:
    - Make proposal for improvement (possible RFC)
    - Collect feedback from stakeholders
    - Develop deprecation and migration plan
Create development plan
Development:
- Implement the action and filter hook interfaces dictated in the RFC
- Provide developer facing documentation for migration of for new hooks
- Migrate extensions to new hooks
- Implement new core interfaces per each proposal for improvement
- Mark core code that is internal and may not be accessed by extensions (may require tool support)
- Mark core classes that may be subclassed by extensions (may require tool support)
- Provide developer facing documentation for migration to new core interfaces
- Migrate extensions to new core interfaces
- Deprecate then remove old hooks and interfaces

Time and Resource Estimates

< Initiatives

Estimated Start Date

FY1819 Q4 - FY1920 Q1

Actual Start Date

None given

Estimated Completion Date

None given

Actual Completion Date

None given

Resource Estimates

Once RFC: MediaWiki 2018 extension interfaces is approved, the following tasks will need to be resourced:

Implement action hook and filter hook interfaces in core

1 engineer for 1 week

Analyze current hooks and their usage

There are roughly 680 hooks in core. These hooks and their usage in extensions are of various levels of complexity. Therefore, the hooks will be ranked by the frequency of their usage in actively maintained gerrit hosted extensions. 3 staff months will be allocated to analyzing hook usage in rank order. At the end of this period, re-estimation will be necessary to prioritize the remaining less frequently used hooks.

The analysis will answer the following questions for each hook by examining all extensions that implement the hook:

Is it an action hook?
- If so, what parameters does it need to do its job?
Is it a filter hook?
- If so, what parameters does it need to do its job?

Collaborators

None given

Open Questions

< Initiatives

How should an extension expose a web API?
How do we annotate source code so that code is public or private to extensions?
Should Wikimedia and third party extensions have the same interface into core?
How close can we come to killing all global state, replacing it by using service locators?
Should there be a restricted service locator that extensions are forced to use?
Can the internal tag be used to mark certain classes as internal without making it difficult to work within core

Documentation Links

< Initiatives

Phabricator

RFC: MediaWiki 2018 extension interfaces

Plans/RFCs

None given

Other Documents

Best_practices_for_extension_points

Subpages