Automated Edits code of conduct

From OpenStreetMap Wiki
Jump to: navigation, search
Available languages
English français português

The Automated Edits code of conduct should always be followed when performing Automated edits to the OpenStreetMap database. These rules apply both to people using bots, making scripted imports and making large-scale edits by other means, including when using a standard editor such as JOSM. This policy places strict rules on such automated edits because they have the potential to cause harm, to damage the work of others, or to unilaterally override their opinion. Failure to comply with these guidelines may create difficulties for the community, result in a referral to the data working group and in extreme cases to being banned from OSM.

Scope

Generally, this policy covers all edits where an individual change to an object is not performed by a human being. This includes:

  • changes made by Bots;
  • Imports, no matter whether the import is fully automated or using files that are uploaded through an editor without a manual review of each object.
  • search-and-replace operations using an editor or XAPI service where the individual changes are not reviewed individually;
  • any other programatic changes made to the database.

Guidelines

Be cautious!

Automated edits are able to change a large number of objects in large area and affect the work of many other mappers. Beware that even if 99% of your edits are genuine typos, 1% of "false positive" (edits that harm the works of others) can make a bot unpopular. They should be planned diligently and executed in a professional manner

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, if is clearly acceptable for you to correct these using an automated process

Problematic usage:

  • Asserting policy, or your own interpretation of policy, where you start judging their work and modifying it according to what you think is right then you might actually break something that someone has put in there on purpose. Mapper might well feel a little bit offended by "some guy with a script lording it over" - especially if the mapper is outgunned because he isn't also a programmer and he cannot make changes the way you can. Use tact and sensitivity when dealing with the work of others.
  • Importing data on top of other data without properly integrating the new content or following the Import guidelines.

Consider submitting proposed changes to quality assurance tools like Keep Right where someone with local knowledge can investigate.

Discuss your plans

If you plan to make an automated edit, outline it beforehand and discuss it on a suitable mailing list (a regional, national or international list depending on the scope of your planned change). For edits that will affect a large amount of data, you should expect to discuss the change thoroughly with input from at least ten or fifteen people. The discussion must take place in:

  • Either the international, English-language list
  • or the international, English-language imports list, for fixing of previous imports
  • or if your edit affects only a small number of countries, the national-language mailing lists, forums, or other standard communication methods for the countries or areas affected by the change

If you find that your plan is widely accepted but there are a few people opposing it, then try to get them on board by offering to make an exception for their area or for any objects last edited by them. OpenStreetMap can handle a bit of diversity; we will rather keep those people happy and contributing than overrule them and give them a reason to leave.

OpenStreetMap is very much built on consensus. A majority of voices on a mailing list does not give you the right to do whatever you please to the data created by the minority. Also, things that you may read in the Wiki are not a carte blanche for you to change everything so that it fits the Wiki "rules". Individual mappers have every right to tag things differently from what is stated in the Wiki, and it is not OK for anybody to turn the suggestions contained in the Wiki into strict rules that are applied automatically.

Document thoroughly

In general you should document your proposed edit at an English-language wiki page named "Mechanical 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 added to the category "Mechanical Edits". It is also a good idea to present your idea to the appropriate list, and forums if appropriate; if people generally agree, create wiki page with details and discuss in earnest, then proceed - or don't. If you run some kind of regular automatic change mechanism (a "bot"), then each configuration change (e.g. adding a new misspelled tag to correct) requires new community approval; you cannot get blanket approval for some unspecific "I am fixing misspelled tags".

If your changes only affect one country, then it is fine to work in the local language. If, for example, your change affects only Spain then it is ok to discuss this on lists and the wiki in Spanish.

You must write documentation that covers the following:

  • Who is making the change (real name and how to contact, ideally e-mail address)
  • What the change is about, with a detailed description of the algorithm used to decide which objects are changed how (i.e. it is not enough to write "fix misspelled tags" but you will have to provide a full explanation on how exactly you are fixing what)
  • Details about the discussion that was held, 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"
  • The www.openstreetmap.org user page for your bot account
  • A wiki page that has the name of your bot

This documentation must be available on a wiki page named "Mechanical Edits/username" (where username is the OSM user name of the account used to perform the changes). It is suggested to place a link to that page on the OSM user page of the account. Look at Mechanical Edits/example for how this page should look like.

Execute with caution

You should:

  • 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.

Engage constructively if challenged

If someone should revert your changes, do not start a tit-for-tat reversal of edits. This only annoys everyone and blows the database history out of proportion. Seek a dialogue with the people involved, and get someone else to mediate if you cannot find a solution. This applies to everyone who edits OpenStreetMap, including people who are "combating" automated editing.

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.

See also