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.

Scope

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 each object individually;
• manually changing tags without adequate review;

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 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 in the OpenStreetMap Wiki? Discussing in advance reduces the probability that you get upset and discuss reverting your changes.

Guidelines

Be cautious!

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 made a systematic mistake, then you may correct this systematically using an automated process. Do however be aware of the risk that your process changes data beyond the scope you intended. Correcting the work of another individual, at their express request is acceptable as well.
• Useful edits that would be tedious to do manually, only after approval by the community and appropriate discussion.

Problematic usage

• Using a tool to assert 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 the Import guidelines.

Other approaches

As an alternative to automated edits, consider submitting proposed issue to quality assurance tools like Keep Right or osmose 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 platform like the Community forum.

If a local community is particularly active on some other platform, for example Slack workspaces or Signal groups, we advise to raise your proposal for an automated edit there for maximum community visibility. However, there should be a permanent record of a community discussion and decision on the Community forum or this Wiki.

• either the OpenStreetMap Community Forums;
• or talk (a general-purpose mailing list);
• or if your edit affects only one country or territory, then standard communication methods for the territory affected by the change - typically national-language mailing lists or forums;
• 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 you are doing import, you must also follow Import/Guidelines requirements, including discussing your plans on imports mailing list. It applies also to issues with previous imports;
• and if your edit affects a specialist subject, such as public transport which has its own list (https://lists.openstreetmap.org/listinfo/talk-transit), then you should also discuss your plans on that mailing list;
• and if the activity qualifies as organized, it might also need to follow the Organised Editing Guidelines, and so on.

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 username 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

You should:

• Execute only a small number of edits with a new bot at beginning 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. Such a practice would also be considered gaming the system if done by a human, since it gives the impression of more map changes than were actually made. If your bot creates one changeset for a bunch of changes covering the whole planet, that, too, becomes hard to read, and pollutes the history in places nowhere near the changes. 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). You must link to the wiki page or user page documenting your changes from changeset, for example using description=* changeset tag (e.g. description=https://wiki.openstreetmap.org/wiki/Mechanical Edits/John Doe#Tag Fixup January 2013).
• Respect "opt out" requests, 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.

Dispute resolution

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.

See also

• What's the problem with mechanical edits?
• Import/Guidelines
• Wikipedia's bot policy – a good reference even if it has no jurisdiction here.