Wikipedia:Bot policy
 | This page documents a procedural policy of Wikipedia. It documents various processes by which the English Wikipedia operates. |
 | This page in a nutshell: Automated editing processes, known as "bots", must be harmless and useful, have approval, use separate user accounts, and be operated responsibly. This wiki also allows global bots to be run, subject to local requirements. |
The bot policy covers the operation of all bots and automated scripts used to provide automation of Wikipedia edits, whether completely automated, higher speed, or simply assisting human editors in their own work. It also covers the work of the Bot Approvals Group (BAG), which supervises and approves all bot-related activity from a technical and quality-control perspective on behalf of the English Wikipedia community. Other languages may have their own bot policies which differ from this one.
Definitions
- Bots (short for "robots") generally make automated changes or actions. After launching the bot, an assumption can be made that there is no further need for human decision-making.
- Assisted or semi-automated editing covers specifically lower-speed tools and scripts that can assist users to make decisions but leave the actual decision up to the user (see Assisted editing guidelines below).
- Scripts are personalized scripts (typically, but not always, written in JavaScript) that may automate processes, or may merely enhance the existing MediaWiki interface.
- The Bot Approvals Group (BAG) is a group of users with appropriate technical skills and wiki-experience, whose members are approved by the community to oversee and make decisions on bot activity and on-wiki operation for the community. The BAG also determine the classification as bot or assisted editing, in ambiguous cases. Formal work by MediaWiki developers is outside the scope of this policy.
Bot usage
Because bots:
- are potentially capable of editing far faster than humans can; and
- have a lower level of scrutiny on each edit than a human editor; and
- may cause severe disruption if they malfunction or are misused;
the community expects bots to meet high standards before they are approved for use on designated tasks. The operation of unapproved bots, or use of approved bots in ways outside their approved conditions of operation, is prohibited and may in some cases lead to blocking of the user account and possible sanctions for the operator. Note that high-speed semi-automated editing may effectively be considered bots in some cases (see WP:MEATBOT), even if performed by a human editor. If in doubt, check.
Bot accounts
Contributors should create a separate account in order to operate a bot. The account's name should identify the bot function (e.g. <Task>Bot), or the operator's main account (e.g. <Username>Bot). In all cases, it should be immediately clear that the edits are made by an automated account, which is usually achieved by including Bot at the end of the account name. Bots must edit only while logged into their account. Tools not considered to be bots do not require a separate account, but some users do choose to make separate accounts for non-bot but high-speed editing.
The contributions of a bot account remain the responsibility of its operator, whose account must be prominently identifiable on its user page. In particular, the bot operator is responsible for the repair of any damage caused by a bot which operates incorrectly. All policies apply to a bot account in the same way as to any other user account. Bot accounts are considered alternative accounts of their operator. To ensure compliance with WP:BOTCOMM, IP editors wishing to operate a bot must first register an account before operating a bot.
Bot accounts should not be used for contributions that do not fall within the scope of the bot's designated tasks. In particular, bot operators should not use a bot account to respond to messages related to the bot. Bot operators may wish to redirect a bot account's discussion page to their own.
The "bot" flag
Bot accounts will be marked by a bureaucrat as being in the "bot" user group upon BAG request. This flag reduces some of the technical limits imposed by the MediaWiki software. Edits by such accounts are hidden by default within recent changes. Bot accounts may also be added to the "copyviobot" user group upon BAG request; this flag allows use of the API to add metadata to edits for use in the new pages feed.
Activity requirements
Bot accounts that have had no logged actions or edits for two years, where the listed operator has also had no logged actions or edits for two years, will be deauthorized. Following a one-week notification period on the bots noticeboard, and the operator's talk page, prior task approvals will be considered expired and bot flags will be removed. Should the operator return and wish to reactivate the bot, a new request for approval (BRFA) must be completed.
Bots directed to edit by other users
Some bots allow other editors to direct the bot to make an edit or other action. It is recommended and preferable to use OAuth to make the edit on the user's account directly. However, it can be permissible to instead make these edits via a bot account (particularly if necessary due to the actions being privileged), provided the following conditions are met:
- Disclosure: The identity of the Wikipedia user directing the edit/action must be publicly disclosed, typically by linking the username in the edit summary.
- Verification: The identity of the Wikipedia user must be reliably verified to the bot in a manner not easily faked, bypassed or avoided. Suitable methods include a non-trivial password, IP restrictions, wiki login or IRC hostname. If the bot is used to make sensitive actions, stronger methods of verification may be required.
- Competence: All users directing a bot must have the required skill and knowledge to ensure their actions are within community consensus.
Bot requirements
In order for a bot to be approved, its operator should demonstrate that it:
- is harmless
- is useful
- does not consume resources unnecessarily
- performs only tasks for which there is consensus
- carefully adheres to relevant policies and guidelines
- uses appropriate, informative wording in all edit summaries and messages left for users
The bot account's user page should identify the bot using the {{bot}} tag. On both the bot account's userpage and in the approval request, the following information should be provided:
- Details of the bot's task(s)
- Whether the bot is manually assisted or runs automatically
- Whether it runs continuously, intermittently, or at specified intervals, and at what rate
Performance
While performance is not generally an issue, bot operators should recognize that a bot making many requests or editing at a high speed has a much greater effect than the average contributor. Operators should be careful not to make unnecessary Web requests, and be conservative in their editing speed. Sysadmins will inform the community if performance issues of any significance do arise, and in such situations, their directives must be followed.
- Bots in trial periods, and approved bots performing all but the most urgent tasks, should be run at a rate that permits review of their edits when necessary.
- Unflagged bots should edit more slowly than flagged bots, as their edits are visible in user watchlists.
- The urgency of a task should always be considered; tasks that do not need to be completed quickly (for example, renaming categories) can and should be accomplished at a slower rate than those that do (for example, reverting vandalism).
- Bots' editing speed should be regulated in some way. The generally-accepted norm has been that a bot's maximum edit rate should not exceed twenty edits per minute without explicit community consensus.
- Bots' editing speed may also be adjusted based on replica database server lag; this allows bots to edit more quickly during quiet periods while slowing down considerably when server load is high. This can be achieved by appending an extra parameter to the query string of each requested URL; see mw:Manual:Maxlag parameter for more details.
Bots that download substantial portions of Wikipedia's content by requesting many individual pages are not permitted. When such content is required, download database dumps instead. Bots that require access to run queries on Wikipedia databases may be run on Wikimedia Toolforge; such processes are outside the scope of this policy.
Good communication
Users who read messages or edit summaries from bots will generally expect a high standard of cordiality and information, backed up by prompt and civil help from the bot's operator if queries arise. Bot operators should take care in the design of communications, and ensure that they will be able to meet any enquiries resulting from the bot's operation cordially, promptly, and appropriately. Issues and enquiries are typically expected to be handled on the English Wikipedia. Pages reachable via unified login, like a talk page at Commons or at Italian Wikipedia could also be acceptable, so long at it is clear on both the bot page and the bot's talk page that this is where comments should be directed, and that the landing page is not confusing to an English speaker. External sites like Phabricator or GitHub (which require separate registration or do not allow for IP comments) and email (which can compromise anonymity) can supplement on-wiki communication, but do not replace it. At a minimum, the operator should ensure that other users will be willing and able to address any messages left in this way if they cannot be sure to do so themselves. This is a condition of operation for all bots.
Note that you can enable email notifications of pings and talk page messages in the notification section of your bot account's preferences.
Configuration tips
Bot operators may wish to implement the following features, depending on the nature of the bot's tasks:
- Bots which deliver notices and newsletters are encouraged to provide a method of opting out of non-critical messages, especially when posting on user talk pages. Instructions for opting out can then be advertised both on the bot user page (example) and on the message delivered (example).
- Bots which edit many pages, but may need to be prevented from editing particular pages, can do so by interpreting {{Bots}}; see the template page for an explanation of how this works.
- Bots which "clean up" in response to non-vandalism user edits may honor {{in use}} to help avoid edit conflicts, either by checking for the presence of that template (and redirects) or the category Category:Pages actively undergoing a major edit. The template's documentation states that a bot that honors {{in use}} may ignore the template if it has been more than 2 hours since the last edit.
- Providing some mechanism which allows contributors other than the bot's operator to control the bot's operation is useful in some circumstances – the bot can be enabled or disabled without resorting to blocks, and could also be configured in other ways. For example, the bot could check the contents of a particular page and act upon the value it finds there. If desired, such a page could then be protected or semi-protected to prevent abuse. Bot operators doing this should bear in mind that they retain all responsibility for their bot account's edits.
- To avoid unnecessary blocks, the bot may use assertion to prevent editing if it is logged out. New bots, and bots which have previously edited while logged out, are required to use assertion.
Authors of bot processes are encouraged, but not required, to publish the source code of their bot.
Restrictions on specific tasks
Categorization of people
Assignment of person categories should not be made using a bot. Before adding sensitive categories to articles using a bot, a human should manually check the list of potentially affected articles (see Wikipedia:Categorization of people).
Context-sensitive changes
Unsupervised bot processes should not make context-sensitive changes that would normally require human attention, as accounting for all possible false positives is generally unfeasible. Exceptionally, such tasks may be allowed if – in addition to having consensus – the operator can demonstrate that no false positives will arise (for example, a one-time run with a complete list of changes from a database dump), or there is community consensus to run the task without supervision (for example, vandalism reversion with a community-accepted false positive rate).
Examples of context-sensitive changes include, but are not limited to:
- Correcting spelling, grammar, or punctuation mistakes.
- Converting words from one regional variation of English to another.
- Applying context-sensitive templates, such as {{weasel word}}.
- Changing HTML entities to Unicode characters whenever the Unicode character might be difficult to identify visually in edit-mode, per the Manual of Style.
Cosmetic changes
Cosmetic changes to the wikitext are sometimes the most controversial, either in themselves or because they clutter page histories, watchlists, and/or the recent changes feed with edits that are not worth the time spent reviewing them. Such changes should not usually be done on their own, but may be allowed in an edit that also includes a substantive change.
Changes that are typically considered substantive affect something visible to readers and consumers of Wikipedia, such as
- the output text or HTML in ways that make a difference to the audio or visual rendering of a page in web browsers, screen readers, when printed, in PDFs, or when accessed through other forms of assistive technology (e.g. removing a deleted category, updating a template parameter, removing blank lines from lists formatted in wikicode);
- the "user-facing interfaces" of Wikipedia, such as category listing or on-wiki and external search engine results (e.g. changing category sort keys, noindexing, search engine summaries/snippets, or page images);
- the "administration of the encyclopedia", such as the maintenance of hidden categories used to track maintenance backlogs (e.g. changing
{{citation needed}}to{{citation needed|date=September 2016}}); or - egregiously invalid HTML such as unclosed tags, even if it does not affect browsers' display or is fixed before output by RemexHtml (e.g. changing
<sup>...</sub>to<sup>...</sup>)
while changes that do not are typically considered cosmetic. Minor edits are not usually considered cosmetic but still need consensus to be done by bots.
Consensus can, as always, create exceptions for particular cosmetic edits. For example, the community frequently determines that a particular template should be substituted so it can be deleted, even though the substitution does not change the output of the page. Consensus for a bot to make any particular cosmetic change must be formalized in an approved request for approval.
Keep in mind that reverting a cosmetic edit is also a cosmetic edit. If the changes made in a cosmetic edit would otherwise be acceptable as part of a substantive edit, there is no reason to revert them. Report the issue to the bot operator instead.
While this policy applies only to bots, human editors should also follow this guidance if making such changes in a bot-like manner.
Interwiki links
Interwiki bots should add interwiki links on Wikidata, rather than on the English Wikipedia, unless the task cannot be performed on Wikidata (such as linking to a section). Interwiki bots may remove interwiki links from English Wikipedia articles only if already present on Wikidata. Globally-approved interwiki bots are permitted to operate on English Wikipedia, subject to local requirements. Interwiki bots running in the Template namespace must ensure links are not transcluded on all pages using the template by placing them in the appropriate documentation subpage section, or non-included portion of the template if no documentation subpage exists. (Bots running on Wikidata need to comply with Wikidata's bot policy.)
Mass page creation
Any large-scale automated or semi-automated content page creation task must be approved at Wikipedia:Bots/Requests for approval. This requirement initially applied to articles, but has since been expanded to include all "content pages", broadly meaning pages designed to be viewed by readers through the mainspace. These include articles, most visible categories, files hosted on Wikipedia, mainspace editnotices, and portals. While no specific definition of "large-scale" was decided, a suggestion of "anything more than 25 or 50" was not opposed. It is also strongly encouraged (and may be required by BAG) that community input be solicited at WP:Village pump (proposals) and the talk pages of any relevant WikiProjects. Bot operators must ensure that all creations are strictly within the terms of their approval.
Per a 2022 RfC, all mass-created articles (except those not required to meet WP:GNG) must cite at least one source which would plausibly contribute to GNG, that is, which constitutes significant coverage in an independent reliable secondary source.
Alternatives to simply creating mass quantities of content pages include creating the pages in small batches or creating the content pages as subpages of a relevant WikiProject to be individually moved to public facing space after each has been reviewed by human editors. While use of these alternatives does not remove the need for a BRFA, it may garner more support from the community at large.
Note that while the WP:MEATBOT-like creation of non-content pages (such as redirects from systematic names, or maintenance categories) is not required to go through a formal BRFA by default, WP:MEATBOT still applies.
Approval process
Requests for approval
| “ | You can more or less think of a BRFA as being a driving license. If you drive without one, you can get in trouble even if your driving skills are fine. And if you have a license, it still doesn't give you the right to run over people or drive 200 km/h in a 50 km/h zone. BAG gives out these driving licenses. If they are abused, they can be (and are) revoked, and bots are blocked accordingly. | ” |
| — Headbomb | ||
All bots that make any logged actions (such as editing pages, uploading files or creating accounts) must be approved for each of these tasks before they may operate. Bot approval requests should be made at Wikipedia:Bots/Requests for approval (BRFA). Requests should state precisely what the bot will do, as well as any other information that may be relevant to its operation, including links to any community discussions sufficient to demonstrate consensus for the proposed task(s). In addition, prospective bot operators should be editors in good standing, and with demonstrable experience with the kind of tasks the bot proposes to do.
During the request for approval, a member of the Bot Approvals Group (BAG) will typically approve a short trial during which the bot is monitored to ensure that it operates correctly. The terms and extent of such a trial period may be determined by the BAG. Bots should be supervised during trial periods so that any problems may be addressed quickly. The bot operator is responsible for reviewing the edits and repairing any mistakes caused by the bot. The BAG may also approve extended trials should problems arise with the initial trial and until community is confident the bot will function correctly.
The request will generally be open for some time during which the community and BAG members may comment or ask questions, and give feedback on the trial. The decision to approve or decline a request should take into account the requirements above, relevant policies and guidelines, and discussions of the request. Consensus formed by a small group on a low-traffic talk page has frequently resulted in controversy when it comes to the attention of the wider community. Bot operators are encouraged and often asked to notify the relevant noticeboards whose areas may be affected or whose expertise in the area could provide useful comments and insight into the proposed task.
Once the request has demonstrated its conformance with the community standards and correct technical implementation, the BAG may approve the task. The BAG may also decline a request which fails to demonstrate community consensus to perform the task. Occasionally, the operator may wish to withdraw the task or the BAG may mark a stale request as expired. Closed requests are archived and preserved for future reference. Should the task be approved, the "bot" user group flag will be assigned by any bureaucrat and the operator may run the bot as intended.
The BAG may also occasionally speedily approve or decline BRFAs without having a trial period. Non-controversial, technically-simple tasks or duplicates of existing tasks, especially if performed by trusted bot operators, can be speedily approved. Similarly, controversial or commonly declined tasks, especially by new editors, may be speedily declined.
Valid operations without approval
Operators may carry out limited testing of bot processes without approval, provided that test edits are very low in number and frequency, and are restricted to test pages such as the sandbox. Such test edits may be made from any user account. In addition, any bot or automated editing process that affects only the operator's or their own userspace (user pages, user talk pages, user's module sandbox pages and subpages thereof), and which are not otherwise disruptive, may be run without prior approval.
Should bot operators wish to modify or extend the operation of their bots, they should ensure that they do so in compliance with this policy. Small changes, for example to fix problems or improve the operation of a particular task, are unlikely to be an issue, but larger changes should not be implemented without some discussion. Completely new tasks usually require a separate approval request. Bot operators may wish to create a separate bot account for each task.
Accounts performing automated tasks without prior approval may be summarily blocked by any administrator.
Bots with administrative rights
Bots with administrator rights (a.k.a. "adminbots") are also approved through the general process. The bot operator must already be an administrator. As with any bot, the approval discussion is conducted on two levels:
- Community approval for the bot's task. This discussion should take place at an appropriate forum, such as the Administrators' noticeboard or the Village Pump, prior to the BRFA. Without a demonstrated need/want for such an adminbot, the BRFA will either be put on hold until this is demonstrated, or the bot will be denied approval.
- The technical assessment of the bot's implementation. It is recommended that the source code for adminbots be open, but should the operator elect to keep all or part of the code not publicly visible, they must present such code for review upon request from any BAG member or administrator.
To demonstrate the implementation, adminbots should either be run "dry" without a 'sysop' bit (if practical), or be run on the operator's main account, with its edits clearly marked as such. When BAG is satisfied that the bot is technically sound, they will approve the bot and recommend that it be given both 'bot' and 'sysop' rights. The bureaucrat who responds to the flag request acts as a final arbiter of the process and will ensure that an adequate level of community consensus (including publicity of approval discussion) underlies the approval.
As adminbots have much more destructive potential than regular bots, their operators are expected to monitor them closely during development and trials, including after code updates. Adminbots should be immediately shut down at the first sign of incorrect behavior. Administrators are allowed to run semi-automated admin tools on their own accounts but will be held responsible if those tools go awry. Neglect while running adminbots and tools constitutes tool misuse.
If an administrator responsible for one or more adminbots is desysopped, their bots should be immediately desysopped at the same time (except if the administrator voluntarily stepped down in uncontroversial circumstances).
Appeals and reexamination of approvals
Requests for reexamination should be discussed at Wikipedia:Bots/Noticeboard. This may include either appeal of denied bot requests, or reexamination of approved bots. In some cases, requests for comment may be warranted.
Such an examination can result in:
- Granting or revoking approval for a bot task;
- Removing or placing the account into the bot user group;
- Imposing further operational conditions on the bot to maintain approval status.
BAG has no authority on operator behavior, or on the operators themselves. Dispute resolution is the proper venue for that.
Dealing with issues
Minor malfunctions, complaints, and improvements
If you have noticed a problem with a bot, have a complaint, or have a suggestion to make, you should contact the bot operator directly via their user talk page (or via the bot account's talk page). Bot operators are expected to be responsive to the community's concerns and suggestions, but please assume good faith and don't panic. Bugs and mistakes happen, and we're all here to build an encyclopedia.
Minor changes and tweaks to the bot behavior usually do not need to be reviewed by the community at large, so long as they do not exceed a reasonable interpretation of the bot's original mandate/BRFA and have consensus. For instance, a bot approved to archive discussions on a specific WikiProject's page does not need another BRFA to change the details of the archiving (e.g. thread age or activity requirements). However, to begin archiving another projects' page the operator should probably submit another BRFA, which might be speedily approved. As another example, a bot originally approved to remove deleted categories from articles would need approval to expand its scope to remove deleted files.
Major malfunctions and complaints
If the bot is causing a significant problem, or the bot operator has not responded and the bot is still causing issues, several mechanisms are available to prevent further disruption. Many bots provide a stop button or means to disable the problematic task on their bot user page. This should be tried first, followed by a discussion of the issue with the bot operator. If no such mechanism is available (or if urgent action is needed), leave a message at the administrators' noticeboard requesting a block for a malfunctioning bot. Per the noticeboard's guideline, you are required to notify the bot operator of the discussion taking place at the noticeboard.
If you are concerned that a bot is operating outside the established consensus for its task, discuss the issue with the bot operator first, or try other forms of dispute resolution (BAG members can act as neutral mediators on such matters). If you are concerned that a bot no longer has consensus for its task, you may formally appeal or ask for re-examination of a bot's approval.
Bot-like editing
Human editors are expected to pay attention to the edits they make, and ensure that they do not sacrifice quality in the pursuit of speed or quantity. For the purpose of dispute resolution, it is irrelevant whether high-speed or large-scale edits that a) are contrary to consensus or b) cause errors an attentive human would not make are actually being performed by a bot, by a human assisted by a script, or even by a human without any programmatic assistance. No matter the method, the disruptive editing must stop or the user may end up blocked. However, merely editing quickly, particularly for a short time, is not by itself disruptive.
Editors who choose to use semi-automated tools to assist their editing should be aware that processes which operate at higher speeds, with a higher volume of edits, or with less human involvement are more likely to be treated as bots. If there is any doubt, you should make a bot approval request. In such cases, the Bot Approvals Group will determine whether the full approval process and a separate bot account are necessary.
Purely cosmetic changes performed by a human editor in a bot-like fashion may also be considered disruptive.
Blocking a bot
Administrators may block bot accounts that operate without approval, operate in a manner not specified in their approval request, or operate counter to the terms of their approval or the bot policy. A block may also be issued if a bot operates without being logged in to an account, or is logged in to an account other than its own. Bots which are known to edit while logged out should have assertion, or a similar function, added to them. Operators can be notified with {{Bot block message}} (for approved bots that are broken) or {{Uw-botblock}} (after blocking unapproved bots).
Administrators blocking a user account suspected of operating an unapproved bot or an approved bot in unapproved ways should soft-block indefinitely.
Bot Approvals Group
Members of the group are experienced in writing and running bots, have programming experience, understand the role of the Bot Approvals Group (BAG) in the BRFA process, and understand Wikipedia's bot policy. Those interested in joining the group should make a post at WT:BAG explaining why they would be a good member of the team and outlining past experience, and then should advertise the discussion at WP:AN, WP:VPM, WT:BOTPOL and WP:BOTN. After seven days, an uninvolved bureaucrat will close the discussion.
After two years without any bot-related activity (such as posting on bot-related pages, posting on a bot's talk page, or operating a bot), BAG members will be retired from BAG following a one-week notice. Retired members can re-apply for BAG membership as normal if they wish to rejoin the BAG.
Assisted editing guidelines
Assisted editing, also known as semi-automated editing, covers the use of tools which assist with repetitive tasks, but do not alter Wikipedia's content without some human interaction. Examples of this include correcting typographical errors, fixing links to disambiguation pages, cleaning up vandalism, and stub sorting.
Contributors intending to make a large number of assisted edits are advised to first ensure that there is a clear consensus that such edits are desired. Editors may wish to indicate consensus for the task, if it is not already clear, in edit summaries and/or on the user or talk page of the account making the contributions. Contributors may wish to create a separate user account in order to do so; such accounts should adhere to the policy on multiple accounts. A bot account should not be used for assisted editing, unless the task has been through a BRFA.
While such contributions are not usually considered to constitute use of a bot, semi-automated processes that operate at higher speeds, with a higher volume of edits, or with less human involvement are more likely to be treated as bots. If there is any doubt, you should make an approval request. In such cases, the Bot Approvals Group will determine whether the full approval process and a separate bot account are necessary. Note that any large-scale semi-automated content page creation requires a BRFA.
Authors of assisted editing tools are permitted to create their own approval mechanism for that tool; if bot approval is required for use of the tool, this is in addition to, not instead of, the normal approval request process. AutoWikiBrowser is an example of a tool with such a mechanism. Release of the source code for assisted editing tools is, as with bots, encouraged but not required.
User scripts
The majority of user scripts are intended to merely improve or personalize the existing MediaWiki interface, or to simplify access to commonly used functions for editors. Scripts of this kind do not normally require BAG approval.