Automated Edits code of conduct
The Automated Edits code of conduct must be followed at all times when performing Automated edits to the OpenStreetMap database. These rules apply both to people using bots, scripts used or created to import new data and to make other systematic edits to the database by other means without consideration of each change. This policy also applies to substantial changes made using 'find and replace' or similar functions within standard editors such as JOSM.
The purpose of this policy is to avoid the database being damaged. Be very aware that it can be hard or impossible to revert or 'roll back' inappropriate edits, particularly where further edits have been made to features touched by the changes and careless automated edits can therefore create considerable work for other parties to repair the damage. Ignoring this policy will be treated as vandalism and will be responded to as such if it persists.
A talk about mechanical edits was given at SOTM 2016, giving a useful overview of the issues.
Generally, this policy covers all edits where changes are made to objects in the database without review individually by the person controlling the edits. This includes:
- changes made by Bots, which by definition act autonomously from human intervention.
- data imports, including both fully automated imports and ones where a standard editor is used;
- other scripted changes made to the database;
- use of find-and-replace functionality using a standard editor such as JOSM or finding using services such as Overpass API and changing without reviewing cases individually;
Even if you are going to change tagging of a large number of objects systematically and don't think that it is an automated edit which is falls under this code of conduct, it is still a good idea to discuss your changes in advance. Maybe there is a consensus among the local community about the current tagging you are not aware of? Or you misunderstood a page at the OpenStreetMap Wiki? Discussing in advance reduces the probability that you get upset and discuss reverting your changes.
OpenStreetMap is built on consensus, rather than a majority voting and you should therefore be sensitive to proceeding with major changes even where the great majority support the change. Note also that documentation of tagging on the Wiki is not the final arbiter of 'correct' tagging.
The edits that you propose may change or modify the work of many other mappers in places you are not familiar with, and indeed in cultures of which you have no knowledge. It is therefore important that you research and plan your work diligently and executed with caution in a professional manner.
If challenged at any stage of the process remain civil, listen and certainly avoid edit warring. If the issue can not be resolved then seek help from someone to mediate.
- Acceptable usage
- Correcting obvious typos, for example changing "hihgway=residential" to "highway=residential".
- Correcting your own work. If you know that you make a systematic mistake then you may correct this systematically using an automated process. Do however be aware to the risk that your process changes data beyond the scope you intended.
- Problematic usage
- Using a tool to asserting a policy, or your own interpretation of policy, when there may be justifiable reasons for other interpretations or where the policy does not reflect common practice. It is particularly an issue where a person, or small group of people work up a coding policy and then used automated processes to assert this within the database without consulting appropriately. Be aware that the Wiki should not be used as the definition of sole correct way of tagging, and that it is not acceptable to cite using the wiki as justification for widespread changes to the data without appropriate consultation.
- Importing data on top of other data without properly integrating the new content with what is already there or adhering to other Import guidelines.
- Other approaches
As an alternative to automated edits, consider submitting proposed issue to quality assurance tools like Keep Right where problematic data can be offered for review by someone with time and local knowledge to consider the change more carefully.
Document and discuss your plans
If you plan to make any automated edit, you should discuss and document your plans beforehand. Documentation should be placed on the wiki and the proposal should then be discussed on a suitable mailing lists:
- Either talk (a general purpose mailing list)
- or imports, when discussing imports or issues with previous imports
- or if your edit affects only one country or territory then the national-language mailing lists, forums, or other standard communication methods for the territory affected by the change
- or if your edit affects only a town or small region, the local mailing list, forums, or other standard communication methods of the area affected by the change.
- and if your edit affects a specialist subject, such as oil rigs or public transport which has its own list then you should also discuss your plans on that mailing list.
If you find that your plan is widely accepted except for a few dissenters, then work with those people to understand their reasons for objecting. If you can not find accommodation then consider making an exception for their edits or area. If there is broader resistance then possibly you should reconsider your plans.
Note that any later modification or extension to the scope of changes you propose to make should also be discussed in the same way and requires new community approval. It is not possible to get blanket approval for some unspecific "I am fixing misspelled tags".
You should normally document your proposed edit at an English-language wiki page named "Automated edits/username" (where username is the OSM user name of the account that you will be using to perform the edits - think about this now so that you don't have to rename the page later), and add it to Category:Automated edits log.
Your documentation should state:
- Who is making the change (preferably your real name and how to contact you, ideally e-mail address)
- Your motivation for making the change and why it is important
- A detailed description of the algorithm you will use to decide which objects are changed how
- Information about any consultation that you have conducted, with links to mailing list/forum posts or Wiki discussion pages
- When the change was made, or how frequently it is going to be repeated
- Information on how to "opt out"
- Approved Bots should have a wiki page that with the name of your bot as the title. They should also have a user account of the same name with clear links between the user account and the wiki page.
Execute with caution
- Execute only a small number of edits with a new bot before requesting and waiting for feedback before proceeding with larger edits.
- Ensure that you only update based on the current dataset. Ensure that you will never accidentally overwriting something that has been just modified by someone else by using a earlier planet file.
- Ensure that you keep all data you need in case you have to revert your change when something goes awry.
- Plan your changesets sensibly. If your bot creates one changeset for each edit, that becomes extremely hard to read for people. If your bot creates one changeset for a bunch of changes covering the whole planet, that, too, becomes hard to read. Changes grouped into small regions are easiest to digest for human mappers (e.g. "fixed highway tags in Orange County").
- Make sure that there is some way of identifying that a certain change has been made by your script. You could create a special user account for the script, or you could add a "source", created_by", or "note" tag or something.
- A "comment" tag to the changeset that describes the changes made in this changeset in a human-readable way. You must also add the tag "mechanical=yes" (or "bot=yes"), and you must link to the wiki page or user page documenting your changes from the "description" tag (e.g. "description=http://wiki.openstreetmap.org/wiki/Mechanical Edits/John Doe#Tag Fixup January 2013").
- Provide a means for mappers to "opt out" of your changes, i.e. if someone contacts you and asks you to stop making automated edits to things that they have edited, you must comply with that wish, and you must modify your software or procedure to leave those objects untouched in the future.
- For major changes (in the six-digit range or more), check with the admins (try IRC) to ensure that there your change will not interfere with any other operations at a sys admin level, or check the Munin graphs to find out at which time the servers are not busy.
It is always possible that people will be unhappy with the edit, even after extensive discussion. So be ready for this, and handle all user complaints seriously and politely. If you have followed this policy then this means your account will not be blocked right away when someone complains, but you might still have to change or stop what you're doing if people dislike your actions and / or their side-effects.
Your edit may be reverted even if you have followed this policy; this doesn't guarantee your edit will be accepted. The Data Working Group will investigate and act on issues which cannot be resolved through the above course of action and may either block the account immediately or send out a warning message (depending on how intense the editing activity is). All automated edits not following this policy are liable to being quickly reverted when they are discovered. In cases where edits that are in violation of this policy are so closely mixed with "normal" edits that it is difficult to tell them apart, it is possible that reverting the problematic edits will also cause some collateral damage among the "normal" edits.