Help:Notifications/Document a new notification type

It is possible to add a new notification type to Notifications on Wikimedia projects. However, that is possible regarding certain conditions.

Is Notifications the best tool for your need?
Notifications have been created to inform users about new activity in a unified way. People can choose which Notifications they want to receive.

However, Notifications are not the new way to communicate. A new notification have to address a specific need which can't be well addressed by other tools. Sometimes, Notifications may not be the best tool.

Example: A new service provides resources to Wikipedia users hen they have reached a certain number of edits. That way, Notification can keep a clear scope.
 * To inform all users of that new service, Notifications are not the best tool. Messages on Village Pumps and blog post are the best communication tools.
 * To inform users that they are eligible to that service, Notifications can be a good tool. That may be grouped with a more general Notification tool to inform people of what they have access to.
 * To inform eligible users that there is new resources available, Notifications are not the best tool. Messages on talk pages would be preferred.

If you have any doubts, please contact the Collaboration team.

How-to
Create a task on Phabricator and tag it with  tag.

Information required
Describe your Notification type on the Phabricator task.

Elements bolded needed. They are followed by examples.

Basic information

 * notification name: flow-post-reply
 * what triggers notification?: someone posts in a Flow topic you are watching
 * "Notice" or "Alert"?: Notice
 * will this be a bundled notification?: yes

Wording
single message
 * header: Username replied in "Topicname".
 * body: Excerpt of the message.

Bundled Messages

 * main, bundling message: 5 new replies in "Topicname".
 * subsidiary, bundled message: Username: "Excerpt of the message..."

Links

 * primary link target: The "reply" (i.e. the new post)]
 * primary link label: View message


 * #1 secondary link target: the user page of the user who did the action
 * #1 secondary link label: the username of the user who did the action


 * #2 secondary link target: null
 * #2 secondary link label: null

Icon

 * icon name: User talk

Develop the new notification
Follow technical instructions at Extension:Notifications/Create a new notification type

Document new notification type
Add it to the Help page.

Where to place the documentation

 * if that new notification is used on all WMF wikis as a "core" extension (like "Thanks" extension is), it can be integrated in the Default notifications section.
 * If that new notification is used on some WMF wikis as an optional extension or Beta feature, it can be integrated in the Notifications from optional extensions section.
 * If an extension tested as a Beta feature or active only on certain wikis changes something on a Default notifications, it can be documented on the Default notifications section, as a separated paragraph, with all necessary details.
 * If that new notification is not used on WMF wikis, it has to be on a separate page, with all user documentation for the extension to avoid. A link can be created from the notifications type page to that documentation.

When to do that
It is possible to do that before merging the task. In that case, please follow some recommandations:
 * create a section labelled "future features", like on Help:Notifications/Special:Notifications
 * descriptions must be written in the present tense to avoid extra work for translators. They will be moved to the appropriate sections when the feature is available.