To address the second question, here's a relevant comment about the wl_notificationtimestamp column for the watchlist table:
"Timestamp used to send notification e-mails and show "updated since last visit" markers on history and recent changes / watchlist. Set to NULL when the user visits the latest revision of the page, which means that they should be sent an e-mail on the next change."

Note: Wikidata currently appears on other projects' watchlists; we can talk to them as one avenue of investigation.

See http://addshore.com/2016/05/refactoring-around-watcheditem-in-mediawiki/

I looked at the watchlist code in MediaWiki. It was scattered over several files and it's still not entirely clear to me why this is so. My best guess is backward compatibility. It's also possible this is so because there are several ways to add a page to your watchlist: by creating it, checking watch button when editing or clicking the star on top right. I found watchlist related code in:

• /includes/actions
  • WatchAction.php
  • UnWatchAction.php
• /includes/user/User.php
• /includes/specials/SpecialEditWatchlist.php

However all of the above make use of WatchedItemStore.php for performing DB related actions which is the storage layer class for WatchedItems. WatchedItem class represents a simple watched object (user, page (LinkTarget object), notification timestamp). Most functions in this class are deprecated and used as wrappers for WatchedItemStore functions.

WatchedItemStore takes care of:

• Adding a page/list of pages to watchlist
• Removing a page from watchlist
• Counting watched items
• Counting number of unread notifications
• Checking if a page is watched
• Set/Reset/Update notification timestamp

etc.

SpecialWatchlist class is executed when the watchlist special page is called.

How a page is added to a watchlist:

1. User requests to add a page to their watchlist. This can happen in the following ways
   • Clicking the star
   • Creating a page
   • Checking "Watch this page" after editing
   • Editing Special:Watchlist/edit or Special:Watchlist/raw
2. The page and talk-page are added to the "watchlist" table for the user.

What happens when a page is edited:

1. A page is edited.
2. A hook runs, which calls updateNotificationTimestamp function from WatchedItemStore. This updates the notification timestamp for the page for each of the watcher's watchlist page except for the editor. (This is done by joining the page with the watchlist table for the users).
3. The notification timestamp for the user's watchlist table is not NULL anymore and thus, it's now an unread notification.

What happens when an unread notification is clicked:

1. User clicks an unread watchlist entry
2. The resetNotificationTimestamp function is called from WatchedItemStore with the user and title as params. This resets the value for that entry back to NULL.

The watchlist has an API whose code comes from APIQueryWatchlist. This class makes heavy use of WatchedItemQueryService class. This class does the complicated queries relating to Recentchanges and Watchlist code. When a user loads Special:Watchlist, the watchlist table is joined on the recent changes table to display entries to the user. This is why we can't have watchlist entries from beyond 30 days.

There are a couple of watchlist options that we need to consider as well:

• Extended watchlist - This is the option in Preferences to "Expand watchlist to show all changes, not just the most recent". When this option is checked, does it still join on the recent changes table?
• Enhanced watchlist - This is the option in Preferences to "Group changes by page in recent changes and watchlist". Does this change the query that is used?

Also, can you talk a bit more about the WatchedItems class? Is this class still used or do most things just interact with WatchedItemStore? Rather than answering here, it would be best to create new Manual pages for them, as they are both missing documentation:

• https://www.mediawiki.org/wiki/Manual:WatchedItemStore.php
• https://www.mediawiki.org/wiki/Manual:WatchedItem.php

For some examples of good class documentation pages:

• https://www.mediawiki.org/wiki/Manual:Title.php
• https://www.mediawiki.org/wiki/Manual:Pager.php

Listing all the functions isn't necessary, but explaining a couple of the most critical functions would be good.

Finally, please add some of the information from your investigation above to Manual:Watchlist as it will be very useful to share with other developers.

In T126639#2455446, @kaldari wrote:

There are a couple of watchlist options that we need to consider as well:

• Extended watchlist - This is the option in Preferences to "Expand watchlist to show all changes, not just the most recent". When this option is checked, does it still join on the recent changes table?

This options shows you all entries for all pages. If you choose not to see the extended version, you see only one (most recent) entry for each page. In both cases it joins on recentchanges but in the latter it only looks at the "page_latest" revision.

• Enhanced watchlist - This is the option in Preferences to "Group changes by page in recent changes and watchlist". Does this change the query that is used?

Doesn't seem so. The formatting is done in JavaScript by EnhancedChangesList class.

Also, can you talk a bit more about the WatchedItems class? Is this class still used or do most things just interact with WatchedItemStore? Rather than answering here, it would be best to create new Manual pages for them, as they are both missing documentation:

I created the pages but to give you a brief - the WatchedItems class mostly contains deprecated function which are now wrappers for functions in WatchedItemStore. The class is still used as a representation for a simple watched object (user, page, notification_timestamp).

• https://www.mediawiki.org/wiki/Manual:WatchedItemStore.php

Done.

• https://www.mediawiki.org/wiki/Manual:WatchedItem.php

Done.

For some examples of good class documentation pages:

• https://www.mediawiki.org/wiki/Manual:Title.php
• https://www.mediawiki.org/wiki/Manual:Pager.php

Listing all the functions isn't necessary, but explaining a couple of the most critical functions would be good.

Finally, please add some of the information from your investigation above to Manual:Watchlist as it will be very useful to share with other developers.

Done.