Page MenuHomePhabricator

Investigation: Learn exactly how the current watchlist works in preparation for working on cross-wiki watchlists
Closed, ResolvedPublic3 Story Points

Description

We need to investigate the technical details of the current watchlist and get a good understanding of it before making a plan for global watchlists.

Acceptance criteria:

  • Add to the documentation at https://www.mediawiki.org/wiki/Manual:Watchlist so that all the relevant details of how watchlists actually work are covered there. In particular: What actually happens when you view your watchlist? What happens when you view a page on your watchlist?

Note: the TCB team has done a lot of watchlist refactoring recently, as preparation for their work on T100508: Watchlist expiry: Watch pages for a specified time frame (2013). I think Adam Shorland (Addshore) was the lead on the refactoring; talk to him for the inside knowledge.

Event Timeline

kaldari created this task.Feb 11 2016, 6:43 PM
kaldari updated the task description. (Show Details)
kaldari raised the priority of this task from to Needs Triage.
kaldari added a project: Community-Tech.
kaldari added a subscriber: kaldari.
Restricted Application added subscribers: StudiesWorld, Aklapper. · View Herald TranscriptFeb 11 2016, 6:43 PM
kaldari updated the task description. (Show Details)Feb 11 2016, 6:48 PM
kaldari set Security to None.

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."

kaldari edited a custom field.Feb 11 2016, 6:50 PM
kaldari triaged this task as Normal priority.
kaldari moved this task from Untriaged to Ready for development on the Community-Tech board.
DannyH renamed this task from Investigation: Learn exactly how the current watchlist works in preparation for working on global watchlists to Investigation: Learn exactly how the current watchlist works in preparation for working on cross-wiki watchlists.Feb 18 2016, 12:21 AM
DannyH added a subscriber: DannyH.Mar 23 2016, 12:14 AM

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

DannyH updated the task description. (Show Details)Jun 7 2016, 12:40 AM
Niharika claimed this task.Jul 6 2016, 10:44 AM
Niharika moved this task from Ready to In Development on the Community-Tech-Sprint board.
Niharika added a subscriber: Niharika.
Niharika added a comment.EditedJul 11 2016, 6:13 PM

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:

For some examples of good class documentation pages:

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.

Niharika added a comment.EditedJul 13 2016, 2:01 PM

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).

Done.

Done.

For some examples of good class documentation pages:

Done.

kaldari closed this task as Resolved.Jul 13 2016, 4:55 PM

Nice job!