This will contain links to results, documents, or any updates for the exploration to find architectural patterns that simplify feature development in MediaWiki platform. Please add this page to your watchlist if you’re interested in this exploration, and feel free to engage us in the talk page.

Hypothesis 5.2.1: classification of the types of hooks and extension registry properties

Hypothesis: If we make a classification of the types of hooks and extension registry properties used to influence the behavior of MediaWiki core, we will be able to focus further research and interventions on the most impactful.

Objective

We want to discover patterns in how the ~180 extensions WMF uses in production use hooks and other extension interfaces to implement their business logic. These patterns will allow us to design experiments for making the extension interfaces more expressive and robust which will eventually make extension development easier and more sustainable.

Motivation

Hooks are the primary mechanism for extensions to add to (or modify) MediaWikis behavior. Hooks are essentially callbacks, and there are few restrictions on what they can do. This makes them very powerful and flexible, but it also means they are hard to reason about. Extensions sometimes interact in surprising ways, or rely on assumptions that may be broken even by subtle changes to the MediaWIki platform.

To improve this situation, the interface between extensions and MediaWiki needs to become more expressive and oppinionated. This can be done by changing the signature and contract of hooks, or by replacing hooks by alternative mechanisms like the registry/provider pattern. A survey of the way hooks are currently used by various extensions will help us ground specific improvements in knowledge about the needs of extensions. Forthermore, it will highlight potential difficulties that we may encounter when evolving the interface between extensions and Mediawiki core.

Approach

We will classify the usage of hooks by extensions by analyzing a sample of the ~1400 hook handlers implemented by extensions used by WMF projects along with other extension mechanisms they use.

Once the raw data has been collected, look for common patterns and, based on these, propose changes that would reduce toil and improve maintainability.

Milestones

Hook and handler survey

Generate a spreadsheet listing which extensions uses which hooks [done ✔️] (see sheet)
Generate a ranking of the most-used hooks [done ✔️] (see sheet)
Conduct a co-occurrence analysis describing how often hooks are used together in the same extension. [done ✔️] (see sheet)
Define classification criteria for hooks and hook handlers and write instructions for the classification process. [done ✔️] (see below)
Choose an initial set of three extensions for which we want to analyze all hook handlers [done ✔️].
Classify all hooks and hook handlers used by these extensions. [done ✔️].
Choose an initial set of five handlers for each of the ten most used hooks [done ✔️].
Classify all of these hooks and handler implementations. [done ✔️].

Extension registration survey

Generate a spreadsheet listing which extensions uses which registration mechanism (top level key in extension.json) [done ✔️] (see sheet)
Generate a ranking of the most-used hooks [done ✔️] (see sheet)
Define classification criteria for hooks and hook handlers and write instructions for the classification process. [done ✔️] (see below)
Classify all registration key in use [done ✔️] (see sheet)

Hook and handler survey (second batch)

Identify a second batch of hooks and hook handlers [done ✔️] (see sheet).
- We are focussing mostly on hooks defined by the Echo extension.
Classify all hooks and hook handlers in the second batch. (in progress)⚙️

Evaluation

Identify and document patterns in how extensions use hooks and other extension interfaces. (in progress)⚙️
Propose intervention based on these observations. TODO ⚙️

Classification criteria for Hook

Hook Signatures

Based on the hook’s signature and call site

return value: Whether the hook can be used to interrupt normal execution of calling code, and whether a handler can prevent subsequent handlers from running.
mutable params: List any mutable parameters used by the hook. These can be reference parameters or mutable objects.
state mutators: List any parameter objects that can be used to mutate persistent state (that is, update the database).
before/after: Determine whether the hook represents a notification about something that has already happened, or allows for preparation for something to happen (or neither of these).
use case: The broad context of user activity in which the hook is called. Examples include "page views", "edit", "parsing", and "install/update".

Handler Intent

returns: the values the handler method may returns
updates parameter: List any parameters that get updated by the handler.
flat registration: check whether all the hook handler does is update a data structure in an unconditional way.
globals: check whether the handler relies on global state.
local state: check whether the hook handler accesses member variables of the hook handler objects that are also accessed by other handlers.
persistent state: check whether the handler interacts with the database state (directly or indirectly).
deferred/async: check whether the handler schedules a deferred update or async job

Handler Behavior

return: the values the handler method has actually returned
args_modified: reference parameters the handler modified
Database: database reads or writes observed
MediaWikiServices: service container access observed
RequestContext: request context access observed
DeferredUpdates: update scheduling observed
JobQueueGroup: job scheduling observed
HookContainer: calls to other hooks observed

Classification Criteria for Registration Keys

meta: information about the extension, for human consumption or extension management
config: information injected into the MediaWiki configuration system (except for components and resources)
component: registration of one of more PHP software component (a class or callback)
resource: registration of the location of fiels and directories (except for those defining components). Includes JavaScript code.