MediaWiki Product Insights/Artifacts/KR 5.2: Simplify feature development/Hypothesis 5.2.2: Notifications platform in core

Initially, we set out to better understand how developers are interacting with the platform from two perspectives: 1) Examine how core mechanisms support extensions and where those entry points can be improved, and 2) Identify existing feature(s) that would benefit the most from directly redesigning the architecture to make it more modular and flexible. These initiatives were captured in two hypotheses executed in Q1 FY24-25:

• [Complete] Hypothesis 5.2.1: 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.
• [Complete] Hypothesis 5.2.2: If we explore a new architecture for notifications in MW core and Echo, we will discover new ways to provide modularity and new ways for extensions to interact with core.

A report about the work completed for the 5.2.1 hypothesis and the proposed next steps for simplifying extension interfaces is available here.

The remainder of this write-up will focus on 5.2.2 approach, learnings, and proposed next steps.

Motivation

We set out to better understand how developers are interacting with the platform, and explore identifying interventions within MediaWiki core that will move us towards a structure that provides simpler and more sustainable feature development. We’ve identified the notifications feature set as an opportunity to focus and scope this work, because it contains several antipatterns that we believe can be addressed through improved modularity and defining simplified, use-case centric interfaces.

We believe that by creating a unified architecture, we can greatly simplify and streamline feature development, which will result in a more robust and consistent notification experience for end users. Additionally, we believe that by changing how we encapsulate the underlying notification capabilities, we can unlock new notification and engagement opportunities that were not previously possible due to the hard coded nature of delivery methods.

Approach

In the first quarter of fiscal year 2024/25, we explored designing a new architecture for notifications in the MediaWiki core platform. We framed our Q1 work around trying to imagine what a notification platform could look like (and how it could be structured) in a more ideal form. This allowed us to freely explore future use cases through an ideal architecture lens, without the baggage of existing code constraints. Collaboration across principal engineers from MediaWiki and feature teams resulted in defining a high level “ideal” design reflecting the desired notification components and data streams.

In addition to considering an “ideal” design, project leaders deeply explored the current platform to identify its use cases, how it manages notifications, and what the general challenges are across the existing systems. We did this by conducting “event storming” sessions, where we walked through specific workflows to uncover areas of behavioral complexity and entanglement across implementation layers. This deep dive informed and reshaped our “ideal” designs with the real world context, enabling us to design a better (yet still aspirational), generic notification platform that can answer the requirements while addressing some of the antipatterns we found across the existing systems.

What we found

Today’s notification framework presents several challenges, with the most significant being the complexity and overlap within Echo's operations, including duplicated email functionalities in both Echo and Core. Echo also provides hooks for extensions, but some of these hooks introduce unnecessary complexity and inconsistency, and are hard to discover and properly utilize by feature developers.

Image representation of a high-level behavior and interaction between Echo, Core, and the way notifications are created. Note: This image does not represent the entire operation of Echo, but serves to demonstrate some of the complexities in registration of notifications and interaction with Core.

For instance, extensions that register notifications pass an Event type definition via the `BeforeEchoCreateEvent` hook. If a 'bundle' behavior is defined, part of this bundle's definition (such as whether the notification should be bundled for web or email) is included in the original event definition. However, critical elements like the bundle ID—without which a bundle can't be created—are defined via a separate hook.

Similarly, certain internationalization (i18n) message definitions, such as the 'email-subject-message,' are set during the initial Event type registration, while others are managed within the presentation model. Icons can be defined either through the `BeforeEchoCreateEvent` hook or via the `$wgEchoNotificationIcons` global variable.

Complexity in interaction

There’s a significant level of complexity between Core, Echo, and the extensions built on top of Echo that define notification behavior. For example, consider a user editing a talk page, which triggers a notification. The interactions between MediaWiki, the Echo extension, and the DiscussionTools extension demonstrate how intricate this process is. Both Echo and DiscussionTools define notifications based on the same edit action, and each can interfere with the user locator/filter operation to either inject itself into the process or prevent the other from proceeding. This ensures duplicate notifications aren't sent, but it also highlights the overlapping and sometimes conflicting roles in managing notification prioritization.

Image representing the walkthrough of the system’s operation (and interference in between the elements) of a user editing a talk page, and the notifications that are being created

Inconsistent hook behavior

Another aspect of the complexity is the use of hooks in both Echo and Core. Hooks are the primary mechanism for extensions to add to (or modify) MediaWiki's 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 can be overloaded and used in unexpected ways.

Hooks allow the manipulation of system actions and states for both MediaWiki and Echo, especially regarding email notifications. However, inconsistencies arise, as demonstrated by the overlapping yet distinct hooks: `AbortEmailNotifications`, `AbortTalkPageEmailNotifications`, `SendWatchlistEmailNotifications`, and `EchoAbortEmailNotifications`. Despite the similarity in naming and intended functionality, there are differences in behavior and timing, which adds further confusion.

Image representing some of the behaviors and differences between `AbortEmailNotifications`, `AbortTalkPageEmailNotifications`, `SendWatchlistEmailNotifications`, and `EchoAbortEmailNotifications`

Impact on Maintenance and Behavior

These architectural issues aren’t just theoretical—they directly impact our ability to maintain and enhance the notification system. For instance, implementing changes in email behavior requires separate adjustments in both Echo and Core email functionalities. Some notifications must leverage Core’s hooks, others Echo’s, and it’s often necessary to delve deeply into the system to determine the origin of specific behaviors before changes can be made.

What we learned

Through the research and design work conducted in Q1, we confirmed that the (split) notifications business logic demonstrates some key challenges that can be addressed through introducing a better structure to the general code – and potentially introduce some patterns that can inform some of the broader similar challenges we encounter and heard from developers utilizing the core platform.

There are two main results that the work produced: A focus on tangible guidelines for patterns in the new implementation of the notifications platform, and an aspirational design for the new structure.

Aspirational design

When thinking about the design of the notification platform we were aiming towards a modular design that is simple, but still allows for future flexibility. The new aspect in this design is attempting to produce a clear separation of concerns and business logic so the maintenance is easier, boundaries are clarified, and the system can be more flexible in general. The operation is similar to Echo’s current operation, but the organization is separated as cleanly as possible into distinct modules that can also answer Core’s notifications needs in a consistent manner.

The most notable change for accounting for these capabilities are the split to three main component proposals: Event registry, Notification Queue management and Delivery method dispatcher.

The event registry transforms the current way notifications are registered through the BeforeCreateEchoEvent hook with a proper registry pattern. This aligns the code with the modern registry pattern we’ve been introducing to core over the decades, and allows us to treat all notifications equally – whether they are in core or any other source. Having a standard registry improves maintenance and increases flexibility in deciding (and changing) what notifications are inherent to the platform. Using a registry pattern also makes it simpler for other tools external to mediawiki to register notifications with less need for touching or knowing about internal mediawiki code patterns or states.

The notification queue management is a new concept as a centralized system, but it will include behavior that generally exists in the current design. Echo already manages a notification queue, and supports batching and bundling, sorting and storing notifications per user, handling the ‘seen time’ of notifications, and managing their read/unread state and the general information required to present them through a presentation model. However, the current extension scatters the implementation across delivery methods and assorted hooks, making it difficult to definitively trace the lifecycle of a given notification. By encapsulating notification queue management into a single component with specific customization options, we can improve the clarity and reliability of notification handling, and even bring in other types of notifications currently handled through the core platform, such as watchlist.

The delivery method dispatcher, provider and registry is a new concept. Today, the ways to deliver any sort of notification to the user is hard-coded into the system, like email and the web UI popup, as distinct features. Email is even messier, is also split in operation both from a feature perspective for immediate vs batch notifications, as well as from an implementation perspective between core and Echo, which creates occasional headaches when the email format or design needs to change. The goal of the new design is to unify the operation of delivering notifications and treat each delivery method more agnostically as a separate downstream module; this will standardize the business logic for common operations while adding flexibility for distinct ways to communicate with users. This can, potentially, extend beyond the notification system specifically, and be used by MediaWiki platform in general whenever a communication needs to be sent to a user through any method.

Next steps

The goal of the subsequent work identified through this exploration is to unify the notifications business logic that is currently split between Echo extension and Core’s Enotif systems.

While we rooted our Q1 design work within the general framework of how the system works today and what our production requirements are, the design is still somewhat aspirational and requires feasibility validation. Initial validation work is planned for Quarter 2 of the fiscal year, where implementing experimental proof of concepts for some of the proposed components will allow us to see whether the proposed design is feasible for implementation within the year, and what aspects of it can produce the most value. We will also validate that the proposed changes will actually make development of notifications on top of the platform easier and streamlined – while preserving the robust feature set that’s required.

We will be committing to a new hypothesis for this work in Q2. Stay tuned for another update with the hypothesis text and additional information about the planned scope!