MediaWiki:XTools-AutoEdits.json/Instructions

Guidelines

• Remember that only tools that are regularly and widely used should be included. Every addition here slows down the queries a tiny bit more. We cannot include any and every tool ever made. Also note that very similar tools can be combined to improve performance; for example the "delsort" tool for en.wikipedia includes multiple tools. You make the judgement call, but feel free to ask for help from other maintainers here if you are unsure.
• Test your changes before saving. Do this by first updating MediaWiki:XTools-AutoEdits.json/sandbox with the desired changes. Then, login to XTools and append ?usesandbox=1 to any XTools AutoEdits result page to force it to use the sandbox. The easiest way is to test against accounts that have made edits using the tool you're trying to add, and look for contributions using only that tool. The requester should have shared example diffs.

  For example, if you wanted to add the tool "My Fun Tool" to de.wikipedia, which you know has been used by User:Example: Add the definition to the sandbox config, then load the contributions page for just that user and tool, as with:

  https://xtools.wmflabs.org/autoedits-contributions/de.wikipedia.org/Example?tool=My+Fun+Tool&usesandbox=1

  From here you can see if the qualifying edits show up. Compare with production (without ?usesandbox=1) as necessary. While you can use the sandbox on a normal /autoedits result page, loading just /autoedits-contributions is significantly faster.

  Note also that the ?usesandbox=1 option will bypass caching, so any changes to the sandbox should take effect immediately. Changes to the production configuration are cached for up to 20 minutes, so be patient for them to take effect.

• If you need help with testing regex itself, there are some external tools for this such as regex101.com (just make sure to test against the PCRE flavor, which is the default).

Performance tips

• Try to keep the regex simple and short without allowing it to be too broad. For example, Huggle edits in English contain ([[WP:HG|HG]]) in the summary but the regex we use is \(\[\[WP:HG, since the piped part of the link isn't needed to safely conclude it is a Huggle edit.
• Use tags wherever possible as they are significantly more efficient to query. Sometimes you have to include regex to account for edits made before the tag was introduced, in which case you should include both regex and the tag.
• Restrict to applicable namespaces where possible, especially if the tool is not used in the mainspace or other popular namespaces.

Documentation

Layout of MediaWiki:XTools-AutoEdits.json

Please try to keep the definitions in the following order, with the entries sorted alphabetically:

• Global list (nested the key "global")
  • List tools that are used extensively on multiple medium or large wikis. If only used on small wikis, it may be more efficient to list each of those individually for those wikis. Keep in mind any tools added under "global" are run for all wikis, and may unnecessarily slow down XTools on wikis that don't use those tools.
  • These tool definitions may include regular expressions, but should probably also include tags because the regex may not apply to non-English wikis.
  • You can also set wiki-specific regex that will get merged into the global regex (to override for each language, for example).
  • Other local values such as 'link', 'tag' and 'revert' are overridden, not merged into the global value.
  • See "Huggle" under "global" and "en.wikipedia.org" for an example.
• Per-language list (such as "fr")
  • Key should match the ISO language code. All tools defined here will get ran for projects using that language.
  • These tool definitions generally only include native MediaWiki actions. For these, link to mediawiki.org documentation (e.g. mw:Special:MyLanguage/Help:Moving a page for the "Page move" tool).
  • The key should match the local name of the tool, and translations set using "label", along with the language-specific "regex" that goes with that tool.
• Per-wiki list (such as "de.wikipedia.org")
  • Some definitions are only included to override values of global or per-language definitions.

Format for individual tool definitions

Either beneath "global", the language list (such as "fr") or under a wiki (such as "de.wikisource"), use any the following (only "regex" or "tag" are required):

• Tool name (such as "Twinkle")
  • "regex" – Regular expression to match against edit summary. This follows PCRE format. Don't forget to escape regex literals using two backslash characters. For instance, to look for the link [[COM:FR|File renamed, you would use \\[\\[COM:FR\\|File renamed. Also shorten regex as much as possible. For example, the edit summary for "Undo" has changed over time – It could start with "undid", "undone" or "[[WP:UNDO|Undid]]", so our regex ends up looking like:

  ^(Undid|Undo|\\[\\[WP:UNDO\\|Undid\\]\\]) revision \\d+ by \\[\\[Special:(Contribs|Contributions)\\/.*?\\|.*?\\]\\]

  • "tags" – Names of tags applied to edits made using the tool, if applicable. See Special:Tags on the applicable wiki for full list.
  • "tag_excludes" – Don't count edits that also use this tag. This is used for example to hide Huggle edits when viewing Rollback edits. There are some known bugs, see phab:T191133. Please be careful using this option and test your changes thoroughly.
  • "link" – Wiki link to tool documentation. Full URLs or external links do NOT work, but interwiki do. Prefer official, multilingual documentation where possible (e.g. mw:Special:MyLanguage/Help:Moving a page instead of local documentation on moving pages). If no link exists, linking to the source code may be enough. If there's nowhere to link, it probably shouldn't be listed.
  • "label" – Text to use as the label for the tool, defaults to the tool's key. Use this for translations.
  • "revert" – If the tool is used only to revert edits (and not also issue talk page notifications, etc.), set this to true. If the tool is merely capable of reverting edits, set 'revert' to regex that would only account for such reverts. See the "Twinkle" entry for an example. The revert-only regex is necessary for the ArticleInfo and elsewhere in XTools, so as to differentiate edits that added content from edits that restored content.
  • "contribs" – Set to true to include edits with the given tool in lists of non-automated contributions. For example, this is done for en.wikipedia's "ProveIt", because that tool often includes prose that was added by the user, and not entirely a semi-automated edit.
  • "namespaces" – The namespace IDs of where the tool is used. This is used to speed up the queries, so please use it where possible. Omit if the tool applies to all or most namespaces.
  • "talk_namespaces" – Set to only target talk namespaces.

For each tool definition, either "regex" or "tag" are required. In some cases you might want to include both, say if older versions of the tool did not add tags to the edits.

Responding to requests

1. Ensure the tool meets the criteria outlined in the above guidelines.
2. Test your changes first in the sandbox
3. Make the changes to the production config.
4. Mark the request as {{done}}

Notes