Notifications

'''This document is a work in progress. Comments are appreciated but this is not a final draft.'''

This document describes the design of a notifications system, code-named Echo. This feature is designed to replace and augment existing notification systems as well as providing significantly more control to both users and developers as to how their notifications are handled, read, and deleted.

Recent Changes
https://gerrit.wikimedia.org/r/gitweb?p=mediawiki/extensions/Echo.git&a=rss

Values
For the User:
 * Being aware
 * Getting an aggregate sense of activity
 * Confusion Reduction
 * Quick action I can take at a glance

For the Foundation
 * Promotion awareness through community
 * Driving Engagement for new users
 * Eventually promote a user's interest graph

Rationale
The central tracking bug, "MediaWiki needs a sane notification system", can be found at 32281. Currently, notifications within MediaWiki are ambiguous and replicative. Multiple extensions and functions will fire off notifications and very few utilize the same system. This creates massive user confusion. For example, the following systems utilize their own, distinct methods of user notifications:
 * Standard "user talk" and watchlist notifications
 * LiquidThreads replies and postings (Special:NewMessages)
 * Feedback Dashboard responses

Primary Reasons are "providing a unified experience for the user" and "providing ease for developer implementation."

Unified UX: On the user end of the issue, notifications are presented to the user is many different forms. For example: orange bar at the top of the page, LiquidThreads notifications in the form of a number in the top right corner, or a watchlist notification via email. Each type is implemented differently and presents the event in a different manner, making the system confusing to users. A user should be able to easily maintain what notifications he/she wants to receive as well as be able to look at and act upon those notifications. With the current spread-out and differentiated notifications system, this is impossible, especially in cases where there are multiple wikis on a farm and notification events occur on each individual wiki.

Ease of Developer Implementation: The notifications system also presents a development issue. Should the need arise to create a new type of notification or a new vector for delivering notifications, it would require numerous code changes in various modules of MediaWiki depending on what notification is being changed and how it is being changed. A centralized system would necessitate only one or two changes in code, usually in the form of an event registration hook or additional method in the notification system. This issue becomes amplified for extension developers because there is no infrastructure to work off of for sending notifications, so making a new type of notification would require either changes to the core, which causes issues when upgrading, or writing custom code, which only furthers the issue at hand. See the Echo Functional Requirements here

Hypothesis
A well-designed and useful notifications system will:


 * Promote editor retention by:
 * Providing users with a modern experience that is similar to other sites
 * Providing a sense of activity within the various projects
 * Reducing the clutter on user talk pages
 * Providing an easier mechanism for displaying 360 interaction processes (as opposed to things like "talk back" templates), thus "centralizing" the discussion
 * Promote better software development by
 * Making it easier for extension developers to plug notifications into their code as needed
 * Making it easier for core developers to add new notification vectors
 * Providing a stable and platform-native interface pattern
 * Improve performance and efficiency by
 * Having all notifications stored in one location, thus requiring fewer database queries
 * Allowing wikis to push notifications to users at the system's convenience

Product/Design Principles

 * 1) Notifications will be a function of user engagement
 * 2) Notifications directed at you will be of most importance
 * 3) You can customize what actions get reflected in your notifications.

Nomenclature

 * Service - the central notification service.
 * Publisher - in this document, a publisher is a feature or extension that is a consumer of the publication/service API. Examples: LiquidThreads, Feedback Dashboard, Talk page edits
 * Event or Notification Event - A specific type of notification. Publishers must define and register notification events with the Service as well as the acceptable back-end pluggables they can use
 * Client - a single user viewing notifications from a single device. Users may have multiple devices.
 * Device - any system where the notification may be seen. Devices can include but are not limited to: user email, MediaWiki "in web" notifications, sms messages, etc.

Core Notification Categories

 * Direct Messages: Talk Page Messages | Wiki-Love | Someone responded to your feedback | Teahouse Answers
 * System Messages: Welcome | Admin Rights | Confirmations
 * Article Contributions: Patrolled | Reverts | Deletion Nominations | Notify me when article rating changes | Actions related to File Uploads |
 * Helpdesk: Teahouse | Helpdesk
 * Commons: File nominated for deletion | Promoted to featured image

Clients
The Clients (Web/mobile/ Tablet) on which notifications will be available are WIP.

Additional documents

 * Echo Technical Architecture
 * Echo User Experience
 * Extension page including installation instructions