User:Crazycomputers/WatchlistBot

WatchlistBot is an XMPP bot that will allow users to maintain a watchlist that is similar to (but separate from) their watchlist on Wikipedia. The key difference is that when a page on a user's WatchlistBot watchlist is changed, they are immediately notified of the edit through their IM client.

If you like using WatchlistBot, you can put User:Crazycomputers/Userbox/WatchlistBot on your userpage to let others know about this project.

Watchlist entry types

 * Article : You will be alerted whenever the article is edited.
 * User : You will be alerted whenever the user performs an edit.
 * Network : You will be alerted whenever any IP address in the network performs an edit.
 * Whitelist : Edits performed by a whitelisted user will never be reported to you, and override all other types of watchlist entries.

Watchlist entry specification
All watchlist entries can be specified with a common syntax, with slight variations for each type of entry:


 * For articles, users, and networks: A bare name, for example "Wikipedia:Sandbox". This will watch the specified item on your default wiki, according to your variables.
 * For articles, users, and networks: A wiki-qualified name, for example "{en.wikipedia}Wikipedia:Sandbox". This will watch the specified item on the specified wiki.
 * For articles: A URL to the article to watch. The wiki name will be extracted from the URL.  (Note that this syntax can, but should not be used for watching users, because the user namespace will not be stripped.  Thus, attempting to watch the user "http://en.wikipedia.org/wiki/User:Crazycomputers" will end up watching the user "User:Crazycomputers" (who does not exist) instead of the intended target "Crazycomputers".)

Networks must be specified as a CIDR block (the notation xxx.xxx.xxx.xxx/nn). As indicated above, you can specify the wiki on which to watch edits by this network using the "{language.project}" prefix. As a safeguard, the bot will not permit networks with a network identifier less than 16 bits in length to be watched.

Article and usernames are normalized using a subset of MediaWiki's own normalization algorithm, with a few exceptions:


 * Namespaces are not understood, so attempting to watch "user:crazycomputers" will result in watching "User:crazycomputers". Obviously, this will never actually yield any results.  Always specify the exact item name.  (This is due to the fact that namespaces vary from project to project and from language to language, and I'm not interested in constantly tweaking this data for the sake of a minor convenience.)
 * The pound sign (#) and all trailing characters will be stripped. This is intended to make it easy to copy and paste URLs, without worrying if a section link was followed.
 * Invalid characters in article names are not stripped, and will generate no errors. You are free to add the article "<>{}:" to your watchlist if you would like.
 * On projects like Wiktionary, where the first letter of titles are not forced to be capitalized, the bot will not perform automatic capitalization either.

Attempting to watch an item on a wiki that does not exist will result in an error.

Usage
To begin using WatchlistBot, send a subscription request to watchlistbot@chrishowie.com in your XMPP client. The bot should immediately approve this request. (Note that this is not an email address.)

Then simply send the message "help" to the bot for a command summary. The available commands are also documented here.

Command parsing
The bot employs a very basic version of the parsing algorithm used by the Bourne shell. Specifically, note that single and double quotation marks ( and  ) are treated as special, and allow for easier embedding of spaces into command arguments (when needed). If you are trying to watch an article whose title contains one of these characters then you will need to escape them by prefixing them with a backslash ( or  ). If you don't, the bot will complain that you didn't match your quotation marks properly, unless it was able to find a matching quotation mark in the title. (And if it did, then it won't be watching the article you wanted to watch.)

For example:


 * : Fails with:.
 * : Watches Don't Let Me Down. The backslash forces the apostrophe to be taken literally.
 * : Also watches Don't Let Me Down. The apostrophe is between a pair of double quotes, and so it is taken literally.
 * : Watches Weird Al Yankovic, which is a redirect to "Weird Al" Yankovic. (The double quotes are consumed by the parser.)
 * : Watches "Weird Al" Yankovic by escaping the quotation marks.
 * : Watches "Weird Al" Yankovic by embedding the quotation marks in a single-quoted string.

These rules may be unfamiliar to you. If they are, consider copying and pasting URLs instead. All browsers will percent-encode single quotation marks, preventing the command parser from treating them specially. Most browsers also encode double-quotation marks, but this is not technically required, so the safest way to watch pages by URL is to wrap the URL in single quote marks. For example:


 * : Watches "Weird Al" Yankovic.

You can also use the "quick add" form on the web interface, which does not apply these parsing rules. (Tell the bot "web" to log in to the web interface.)

about
Display the bot's version and credits.

article
Manages your list of watched articles. The "add" form adds an entry, "modify" will change options for existing entries (such as the comment), "remove" will remove an entry, and "list" will display all of the current entries.

(The action parameter is subject to completion, so "r" will suffice for "remove", for example.)

Syntax:
 * article  [--comment="comment"]
 * article remove
 * article list

editor
Manages your list of watched editors. See the article command for details.

Syntax:
 * editor  [--comment="comment"]
 * editor remove
 * editor list

help
Displays a summary of these commands.

network
Manages your list of watched networks. See the article command for details.

Networks must be specified in CIDR notation. Equivalent networks are treated as a single entry, so attempting to watch the network 127.0.255.255/16 while watching 127.0.0.0/16 will result in an error, since these describe the same network. Likewise, attempting to remove 127.0.255.255/16 while 127.0.0.0/16 is on your watchlist will remove 127.0.0.0/16.

Syntax:
 * network  [--comment="comment"]
 * network remove
 * network list

set
Sets or displays your variables. The following table lists the available variables and describes what they do.

Syntax: set [ ]

stats
Displays some operating statistics:


 * When the bot was last restarted.
 * How many notifications have been sent out since the bot restarted.
 * Whether the IRC connection is currently up, how long it has been up, and how many changes were processed during the current connection, as well as since the bot restarted.
 * How long each notifier has been up. ("Up" in this context usually means "connected to the server."  So if the XMPP notifier is down, that means that the bot isn't connected to its XMPP server.  Which you would never see unless you were running this command from a different chat network, of course.)

Syntax: stats

web
Requests an authentication link to the web-based watchlist management interface. Links will expire after five minutes, and requesting a link will invalidate any previous link. (Note that your session does not expire after five minutes, only the authentication link.)

The web interface allows mass deletion of watchlist items, mass alteration of item comments, single addition of items, and mass addition of items. Item specifiers are parsed according to the same Watchlist entry specification syntax that the bot uses.

whitelist
Manages your list of whitelisted editors. See the article command for details.

Syntax:
 * whitelist  [--comment="comment"]
 * whitelist remove
 * whitelist list

Unavailability
If the bot is not online, reporting the problem to any of my talk pages is unlikely to generate a swift response from me since I won't receive any messages alerting me about your report. The best way to reach me would be via one of my published real-time communication methods.

There is no need to report any downtime to me unless it exceeds a minute or two, since I will frequently restart the bot to apply updates. Usually this only takes a few seconds. If longer downtime is required, I will change the status message at the top of this page.

Bugs
Use this page's talk page to report any bugs. If possible, please include the commit identifier, which you can obtain by running the "about" command or by visiting the web interface. (If the bot is down, the web interface will still usually respond.) This will help me reproduce the problem in my test environment against the specific version you were using at the time.

Note on hounding
The ability to watch users and networks should not be construed as an endorsement of hounding. These features are provided to assist the counter-vandalism force when keeping tabs on problematic users or networks. Misuse of these features may lead to revocation of access to the bot.

Platform

 * OS: Linux 3.9.2 (Debian Wheezy)
 * Database: PostgreSQL 9.1.9
 * Bot runtime: Mono 3.0.10, using:
 * jabber-net for the XMPP connection.
 * SmartIrc4net for the IRC connection.
 * ASP.NET MVC Framework and to provide the web interface, served from nginx with Mono's FastCGI backend.

Privacy
As the bot developer and operator, I necessarily have full access to everyone's watchlist. I will keep this information confidential to the best of my ability. If you are worried about privacy, take note of two things:


 * 1) I have no knowledge of your IP address, unless you make use of the web interface.
 * 2) I don't know your Wikipedia account name unless it's part of your IM handle, or you are watching your userpage (and no other userpages).

Disclaimer
I provide absolutely no guarantee as to the correctness or timeliness of the information delivered by WatchlistBot. You cannot hold me responsible for information that it fails to deliver, or delivers incorrectly. You cannot hold me responsible for damages that occur arising from the use of, inability to use, or malfunctioning of this service. You cannot hold me responsible for any data security breach that may occur, such as the exposure of the contents of your watchlist and/or your IM handle(s).