Help:Notifications/Document a new notification type

Translate this page

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 when they have reached a certain number of edits.

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.

That way, Notification can keep a clear scope.

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

Create a new notification type

How-to

Create a task on Phabricator and tag it with #Notifications tag. A version of the form below, styled for proper Phabricator display, has been created for your convenience. On the Phabricator page for the blank form, click "Edit Task," to see the code; copy the code and paste it into your new task.

Information required

Describe your new Notification type on the Phabricator task by providing all the information in the example form below. The elements in bold are required; the non-bold text shows sample answers that should give you a better idea of how to answer. See the glossary for explanations of unfamiliar terms.

Basic information

Purpose of the notification - Enable users to more easily follow topics on a Flow board.
notification name - flow-post-reply
what triggers notification? - someone posts in a Flow topic you are watching
"Notice" or "Alert"? - Notice
Notification type (standard, bundled, expandable bundle) - Expandable bundle

Wording

For a single message
- header: Username replied in "Topicname".
- body: Excerpt of the message.
for 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

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

Icon

icon name: User talk

Develop the new notification

Follow technical instructions at Extension:Echo/Creating a new notification type

Document new notification type

Where to place the documentation

If that new notification is used on all Wikimedia Foundation hosted wikis as a "core" extension (like "Thanks" extension is), it can be integrated in the Default notifications section in the Help page.
If that new notification is used on some Wikimedia Foundation hosted wikis as an optional extension or Beta feature, it can be integrated in the Notifications from optional extensions section in the Help page.
- 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 Wikimedia Foundation hosted wikis, it has to be documented on the extension's documentation page. A link can be created from the notifications type page to that documentation to inform communities that that Notification exists.

When to do that

It is possible to do that before merging the task. In that case, please follow some recommendations:

create a section labelled "future features", like on Help:Notifications/Special:Notifications#Future_features
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.