Changeset
A changeset is a group of edits to the database by a single user over a short period of time (see also editing).
For example, if you want to add some new houses to the map you can use a single changeset to:
- Add a new way (e.g. the new residential road)
- Delete an area (e.g. forest removed for the houses)
- Change the tags on an existing element (e.g. add a new speed limit on an existing road).
Geographical size of changesets
General recommendation: changesets should be local.
Thousands of volunteers review hundreds of contributions a day (for example using osmcha.org) to maintain the quality of mapping in their area and to provide guidance to new mappers. Some archaic or primitive review tools have limited filtering capabilities: While they allow filtering for changesets that overlap specific areas, the size of each changeset's Bounding Box is defined by the two modified objects that are the farthest apart. When making changes that span a large geographical area, this leads to these changesets being included in many mappers' review filters, which makes it cumbersome for them to focus on changesets that actually touch objects within their local area of interest. As a result, some reviewers flag (otherwise good) changesets as bad because of the size alone.
There is no community-wide consensus on optimal changeset size. Some mappers argue that a changeset should not span more than one continent, while others prefer changesets no larger than a single city.
To avoid conflicts and as a courtesy to reviewers, it is recommended to:
- Combine changes in a small geographical area within a (city, district or province)
- Keep changes within the same (country)
- Upload/Save changes before moving on to map in a different area.
NB: The JOSM editor permits splitting changes done across a larger area in saves of smaller parts to follow the above guidelines and recommendations.
 | Each country may have different OSM wiki rules you may not be aware of. Smaller changesets make it easier to review and revert in case of conflicts. |
Examples:
- If you're adding/modifying 10 objects in 2 distant cities => make 2 changesets, 1 per city.
- If you're adding/modifying 5 objects in 5 countries => make 5 changesets, 1 per country.
Group similar changes together
If you're making similar kinds of changes in one editing session, in a local area it's best to group them together into a single changeset, as opposed to multiple changesets. This makes it easier for other mappers to review changes and consolidate feedback within a changeset.
Tags on changesets
Changesets have key=value pairs attached (tags). The vast majority of changesets will have these two tags:
- comment=* – describing why a mapper made that group of changes, or what was changed. By some software (e.g. www.osm.org) this tag is not displayed as tag but as changeset summary/headline instead (see the screenshot image here).
While optional, mappers are encouraged to make full use of this tag by setting a meaningful, human-generated description (not an automated message), as it will show up almost everywhere where the changeset is listed, and is likely to be read by fellow mappers to try to understand what has happened. See also Good changeset comments. - created_by=* – specify the editing software or script which made the changes
Some other commonly used tags include:
- imagery_used=* – indicates which imagery was being displayed in the editor
- source=* – specify the source for the edits that have been made in this changeset
- bot=yes – for automated edits, performed by a program (a.k.a. script or bot)
- locale=* – stores the language used by the editor (JOSM for instance uses created_by=JOSM/1.5 (13367 en) with the last letters indicating the language).
- review_requested=yes – allows a user to request someone to review the changeset. iD and JOSM have an option to insert this tag and OSMCha (and other tools) identifies it and makes it possible to find changesets with this tag. See also a blog post about it.
After the 2.4.0 update of iD these tags are added to changesets:
- hashtags=* – Semicolon delimited, e.g. “#MissingMaps;#Tanzania”
- host=* – The internet address of the web editor.
- changesets_count=* – The number of edits the user has made, will be “0” for someone making their first edit
- ideditor:walkthrough_started=yes – If the user started the walkthrough.
- ideditor:walkthrough_progress=* – User's progress
After the 2.13.0 update of iD this tag are added to note related changesets:
- closed:note=* – The note id of closed note / notes [1]
The history of changes to tags is not stored on changesets themselves: this can be inferred from the history as a whole.
Custom changeset tags are also possible. JOSM, Potlatch2, and iD editors allow end-users to specify custom changeset tags (and make up new tags if you like, as when tagging data elements).
Viewing changesets
The History function on www.osm.org shows the changesets of the currently viewed area. The geographical extent of the changeset is shown by an orange rectangle, which surrounds all the changes made. For "bots" that make many small changes across a wide area this can be quite big. (This is why many changesets are shown for an area, even when that changeset seems not to be relevant.[2])
Better tools than the basic orange rectangle are available. Many more advanced changeset viewers (such as OSMCha, Achavi, Changeset by Comparison Visualization) are available through the browser plugin OSM Smart Menu which allows opening a changeset in another tool from the changeset view on www.osm.org. As of December 2023, OSMCha and Achavi often cannot load changesets spanning the size of a middle-sized country (or roughly 350,000 km²) and possibly also changesets smaller than that, while the tool Changeset by Comparison Visualization has no problem opening and viewing even worldwide changesets. Since these tools can have different functionality and use cases though, keeping changesets small allows using a bigger variety of tools.
Changesets can be directly accessed using the following URL schema: https://www.openstreetmap.org/changeset/<Changeset number> Another option is to use the query feature and select a feature which will show the feature details and the last changeset for it.
Time and date of changesets
Each changeset is time-stamped. The web interface at openstreetmap.org gives an approximate date (e.g., 'over a year ago'). Hovering the mouse over the date for a few seconds brings up the exact date and time as a tooltip. You can also view the timestamp in the XML files: in the web interface these are hyperlinked at the very bottom of the panel detailing the changeset.
Changeset Discussions
Changeset Discussions show on the web interface as comments and replies (a discussion!) below the changeset tags. It's a good place to welcome new users and give them tips on their mapping contributions, or to discuss a changeset which seems problematic with the user who added it. Changeset Discussions are public so others in the OpenStreetMap community can contribute and see the reasoning for any further changes agreed. For more details see here: walk-through on the blog.
Some statistics about these discussions are displayed:
- Map area/country specific: https://resultmaps.neis-one.org/osm-discussions
- User specific:
- Discussed changesets: https://resultmaps.neis-one.org/osm-discussion-comments?user=USERNAME
- Changeset discussions comments: https://resultmaps.neis-one.org/osm-discussion-comments?user=USERNAME&commented
Someone commented on my changeset, what should I do?
Other mappers can ask for clarification on your edits, ask you to provide a source for them, or point out mistakes you made.
You should almost always respond, even if that response might be "I don't know" – or if you fixed the mistakes yourself. Public communication between mappers is crucial to building trust. Edits of people who never respond may be treated as less trustworthy.
To respond you need to be logged in. It's most comfortable to use a desktop PC browser to navigate openstreetmap.org – the interface can be tricky to get around on a smartphone.
Please keep in mind you will not be banned just for making mistakes! We understand that it takes time to learn how OpenStreetMap works. Also, we can help you undo any mess your edits might have caused. However, unresponsive users who continue questionable edits despite being contacted multiple times first get a warning (so-called 0-day block), then progressively longer blocks on their account.
I commented on someone's changeset, but they ignored it. What should I do?
If a changeset comment is ignored and it was about the quality of the changes made, for instance a
- request to stop some bad mapping (ideally it had explanation why it was a problem and link to relevant discussion/documentation at OSM Wiki or elsewhere)
- request for explanation why something was edited
- request to fix some problematic edits made by that user
and it was ignored, then further communication attempts can be made.
- Send a private message to the user, requesting them to respond to the specific changeset comment
- write to the DWG – they can send a message in such a way which makes it impossible to make any edits without seeing it (0-hour block, dropped as soon as user has seen the block message).
In case of writing to the DWG, a short message is typically sufficient. See below for an example.
To: Data Working Group <data@openstreetmap.org> Subject: User [username] is ignoring changeset comments I commented on changeset [changeset id] made by user [username], to raise concerns about [brief explanation of why you commented on their changeset]. The user ignored me and continued to make further changes, for example: [another changeset id].
Changeset language
If mappers engage in editing zones larger than their country, covering areas that go across countries with different national languages, please use English. For instance an unusual edit that will create a change set bound box from France to India will show up in dozens of countries in between, it would be appropriate to do the closing edit comments in English. Most all who see the edit in their local history view will understand what was added/changed/deleted without having to resort to an online translating service. If the exampled bound box crosses Italy lying in between, not all speak French nor Hindi. The same goes for mappers who usually map only in their home country but in the instance do an edit in another with a different language. Do the comment in the language of the other country or do it in English. Truly no one in Spain is looking for an edit with a comment in German.
Opening and closing changesets
Changesets are 'opened' at the beginning of an editing session, and 'closed' at the end. A closed changeset is fixed and cannot be edited further. A changeset may be closed either explicitly (see the documentation for the editor you are using), or automatically (after a period of inactivity, currently one hour). The same user can have multiple open changesets at any one time. Changesets have a maximum capacity (currently 10,000 elements), maximum open time (currently 24 hours), and an idle timeout (currently 1 hour).
Technical
For technical details, see the API 0.6 documentation which contains extensive documentation on them. A Get Capabilities API call returns the currently applied limits for changesets.
Changesets were introduced with API v0.6 in April 2009. Changesets were "synthesised" for edits before that date (migration code)
Some tags were initially used on elements only for attaching metadata displayed in map editors or in quality assurance tools (such as completion status, things to do, approximations, source, etc.). Since version 0.6 of the API, map editors and import tools are encouraged to attach these metadata tags instead to the changesets they create (changesets are not data elements) instead of tagging every added or modified data element: these old tags on elements are now documented on this wiki as "discardable", meaning that they may be silently deleted from data elements by editors when they update them (they are still usable in changesets only, and still visible in the history of elements, in the version pointed by their initial changeset, but newer updated or created elements will no longer use these tags, attached now to the changeset linked to each version of elements).
Changeset dump
There is a big bzipped XML file with all the changesets at planet.osm.org.
Download the latest dump via BitTorrent with this command: aria2c --seed-time 0 https://planet.openstreetmap.org/planet/changesets-latest.osm.bz2.torrent
There are a few tools to parse changeset files:
- It can be imported into a postgresql database with ChangesetMD
- ... or with osmchanges-postgres.
- The changeset dump file can be converted to CSV with
osmchangesets2csv
Proposals
Here is a proposal to define more common changeset tags that can be used to describe edits: Proposal:Changeset tags (including the previous)
See also
- JOSM's Wiki explains how to work with changesets.
- Changeset rollback using the reverter plugin for JOSM
- Differencing a survey from armchair mapping (Draft)
- OSM Changeset viewer tools
- {{Changeset}} - Wiki template (Adds the changeset id and links to changeset viewers for this particular changeset); Example: 158665155 (achavi, OSMLab)
References
| ||||||||||||||||||||||||||