KR 5.2 impacts: Simplifying feature development through iterative platform architecture

A high level summary of the impact and lessons learned from the work on Notifications and Domain events for the MediaWiki Platform, as part of KR5.2 of the FY24-25 Annual Plan.

Author: Moriel Schottlender
Context: Annual Planning FY24-25
Status: Published June 2025

Introduction

As part of KR 5.2 (FY24-25) of the MediaWiki Platform Evolution objective, the MediaWiki Engineering Group set out to explore how small, targeted architectural improvements could ease feature development across the ecosystem, and contribute to a sustainable evolution of the platform. The goal was clear: make it easier to build, ship, and maintain features—without overhauling the system or introducing unnecessary risk.

This work centered on a critical question: Can we introduce evolutionary changes that improve developer experience and platform sustainability—without destabilizing the system or making premature decisions?

Key takeaways (TL;DR)

Key Result 5.2 of the MediaWiki Platform Evolution objective explored how small, targeted architectural improvements could simplify feature development and support sustainable platform evolution. Instead of large-scale redesigns, the team focused on iterative changes that directly addressed developer pain points.

The project focused on two key areas: notifications and domain events—each chosen for their clear architectural and developer experience challenges. The notification system was selected due to duplicated business logic between MediaWiki core and the Echo extension, and a fragmented implementation that relied on multiple hooks. The domain events work introduced an asynchronous listener pattern as an alternative to hooks. Events support decoupled, distributed system behavior with clear data structures and interfaces. The team introduced an event system into MediaWiki core and began mapping technical domains to guide future development with clearer boundaries and ownership.

Beyond technical gains, the effort emphasized stewardship over code ownership, iterative development, and solving concrete problems based on evidenced user needs—providing a repeatable model for evolving MediaWiki responsibly and effectively.

Methodology: Intentional, iterative architecture

The team followed a pragmatic, iterative approach to introduce small but impactful architectural improvements without disrupting the platform. We used three focused stages:

Investigate (Q1): focused on understanding the current system, the patterns that are used within it, and what an idealized future could look like.
Identify (Q2): identified two major candidates for intervention (Notifications and Domain Events) and conducted user research.
Implement (Q3-Q4): focused on implementing the patterns and enabling other teams to adopt and build on the work while kickstarting necessary migrations and deprecations

This staged approach helped the team to stay within scope, deliver immediate value, and lay the groundwork for continued evolution.

Key impacts

This section outlines some tangible outcomes of the project—new patterns, capabilities, and interfaces that directly improve developer experience and platform maintainability. These changes not only address current pain points but also establish scalable foundations for future development across the MediaWiki platform.

Simple notification interface

The new NotificationService::notify() method allows developers to trigger simple notifications without having to understand and use multiple hooks. This drastically simplifies implementation and lowers the barrier to entry for new feature work.

Unified notification system

Watchlist notifications are now managed by the core notification system, replacing the separate Enotif functionality. This consolidation reduces fragmentation, enables consistent behavior, and allows the deprecation of several brittle hooks. We also simplified how notifications are sent to users. Notifications can now be sent directly to a list of users, eliminating complexity and indirection where it isn't needed, and improving both MediaWiki core and Echo. This change addressed common developer pain points, made Echo development simpler, and supports both backward and forward compatibility.

Middleware pattern for notifications

A new middleware layer standardizes how notifications are processed, allowing developers to override, deduplicate, and modify notifications in a controlled and consolidated way. This replaces the former approach of relying on an unintuitive and tangled set of fragmented hooks.

The middleware pattern directly supports the goal of simplifying feature development by offering a clear, repeatable way to consolidate fragmented hooks. Beyond notifications, it can be applied in other parts of the platform to reduce complexity, improve maintainability, and streamline extensibility.

Domain events as platform standard

The introduction of asynchronous domain events enables more modular and flexible development. This has the potential to reduce tight coupling between components and allows clearer boundaries for data flows—useful both internally within the platform and for downstream services like Wikimedia Enterprise.

We modeled and implemented Domain Events to cover page state changes, and updated several extensions to use the new event system. This helped demonstrate the pattern’s value and gather feedback from teams across the organization. As adoption grows, these events will allow us to deprecate brittle hooks and reduce boilerplate code throughout the system.

Emergence of MediaWiki domains

To support architectural clarity, the team began mapping technical “domains” in MediaWiki. These help define boundaries, ownership, and responsibilities in the codebase, drawing from domain-driven design principles to shape a future-oriented platform model.

Lessons learned

As we navigated architectural evolution within MediaWiki, several themes emerged around platform stewardship, iterative design, and maintaining focus on product-led development. These lessons can inform how future platform work can balance sustainability, clarity, and impact.

Treat the platform as a product

Design choices were guided by developer usability—not just technical elegance. This made it easier to explain and justify the need for the architectural patterns other than “just” platform evolution on its own, and provided actual immediate benefit to what is otherwise long-term evolution.

Focus on known pain points

Instead of building for theoretical future use cases, the team solved specific, well-documented challenges, while thinking about the future needs. Balancing the outlook of the future with a clear deliverable allowed us to keep the scope manageable, avoid overengineering, and deliver real value quickly.

Iterate with care

Iterative platform development can be difficult, but it is an essential part of delivering continuous value. This project forced us to experiment with ways to iterate safely within a system used by many teams and volunteers. The methodology and results showcase that it's possible to ship incremental work safely by investing in good boundaries, product-led development, communication, and testing.

Balance generalization and specificity

Designing long-term patterns in a short-term project meant finding the right balance between solving specific problems and creating reusable solutions. By focusing on real use cases, we avoided overgeneralizing too early—yet still delivered patterns, like middleware and domain events, that can be applied more broadly across the platform. This kept the work grounded, useful, and future-friendly.

Redefine platform ownership as stewardship

Rather than trying to “own” all the code or resolve all bugs, platform teams should consider stewardship: defining direction, enabling others, and creating guardrails for sustainable contributions. This mindset is essential for a platform of MediaWiki’s scale and community, allowing for diverse and robust contributions while keeping the direction of the platform well defined and conceptually maintained.

Conclusion

This project demonstrated how targeted, evolutionary changes can meaningfully improve MediaWiki’s architecture without large-scale rewrites. By aligning technical patterns with developer needs and product goals, the platform is better positioned for sustainable, scalable growth. It also provided a repeatable model for future architectural interventions—one rooted in stewardship, iterative progress, and practical outcomes.

MediaWiki Product Insights/Artifacts/Simplifying feature development through iterative platform architecture