Summary
When logged into a wiki, users should be able to see notifications from Wikimedia Space's Discourse instance alongside their on-wiki notifications. This would be integrated into the existing MediaWiki notification extension (aka Echo). The following requirements are described as ideal. Actual development must happen within the capabilities of the Discourse API.
Requirements
These notifications would include the following classifications.
- Mentions - where another user on Space mentions your username in a post.
- Replies - where another user replies to one of your comments.
- Likes - where another user has given one of your comments a 'like" action.
- New posts - when a new post is added in a category or tag that you are watching in Wikimedia Space.
- New replies in specific topics - where a user can opt-in to be notified of every new post in a given topic.
- Private messages - where another user on Space sends you a private message.
The user will be able to change their user preference for Space notifications on-wiki at Special:Preferences. There they can enable or disable these notifications. Notifications can be sent via the "web interface" where they appear alongside existing notifications in the Echo interface. Users can also be sent a notification via email from this new extension.
Mentions, replies, and private messages will appear in the "Alerts" section of notifications. Likes and new posts will appear in the "Notices" section. This is consistent with existing notification types.
Notices of new posts and replies will be determined by what topic, categories, or tags the user is subscribed to. In Discourse there are three levels of following items – Watching FIrst Post, Tracking, and Watching. (Normal and Muted settings exist, but would not trigger a notification under the classification of 'New posts").
Developer note: The Discourse API provides an endpoint to get notifications for a user. It identifies the type of notification in the response, but the list of notification types is not enumerated in the documentation, so some research would be necessary to see if it matches this list. Since the API only supports a pull interface, not an event-based interface, it would need to be determined when notifications would be retrieved. There would be a performance penalty for retrieving notifications from Discourse at wiki page load, so it may be necessary to create a service that would poll Discourse for new notifications and update MediaWiki.
Features
Notifications in Echo should display the following information:
- User performing the action.
- A description of the location on Space where the action took place.
- If possible or relevant, a short extract from Space from the action.
- A link to the Space profile of the user who took the action.
- A link to the location on Space where the action took place.
- The relative time when the action was taken.
Examples
- Mentions:
- <user> mentioned you in the <topic title> on Wikimedia Space.
- <excerpt of the first 150 characters from the topic>
- Replies:
- <user> replied to your comment in the topic <topic title> on Wikimedia Space.
- <excerpt of the first 150 characters from the topic>
- Likes:
- <user> liked your comment on <topic title> on Wikimedia Space.
- <excerpt of the comment>
- New posts:
- A new topic created in <category or tag>: <topic title> on Wikimedia Space
- <excerpt of the new topic>
- New replies in specific topics:
- A new reply in the topic <topic title> on Wikimedia Space
- <excerpt of the new reply>
- Private messages:
- <user> send you a private message
- <subject of private message>
Notifications should persist in the interface until acted upon or dismissed as "marked as read". Users should be able to toggle notifications as read or unread.
Users should be able to see all their notifications at Special:Notifications and filter by view status.
Users should be able to set their preferences at Special:Preferences#mw-prefsection-echo
Developer note: Discourse has different notification semantics than Mediawiki's Echo; notifications can be unseen, seen and read (seen meaning that the user has seen the title of the notification in the popdown, but has not clicked through). Seen notifications do not count into the unread notification number. There appears no way to mark Discourse notifications unread. Removing MediaWiki notifications when the Discourse equivalent is read seems nontrivial. It would require some event feed of Discourse notification actions.
Benefit (who would use this and why is that important)
All users who primarily work on-wiki will benefit from having notifications in the space where the majority of their work happens. Specifically movement organizers who are using Space to coordinate and collaborate with cohorts, events, and targeted groups (liek newcomers to a hackathon).
Acceptance Criteria
A MVP is one where the following actions can happen. Users can see a notification, click a link to Space, and mark as read. Users must be able to configure Space notification settings in Special:Preferences.
A complete, stable extension can do the above as described with compatibility with all major browsers, functionality with javascript disabled, aria compliant, and with support for RTL languages.