Good changeset comments

Why should I use Changeset Comments?

There are many reasons why you should make use of the changeset comment to describe your edit:

Out of courtesy to your fellow mappers, since it makes it easier for them to understand what you have done and why. Not using a changeset comment has the air of "it's none of your business what I did here and why" and doesn't fit well with a project where we're all working on the same thing!
To avoid misunderstandings and get mistakes fixed quickly – if an edit with a changeset comment of "traced a couple houses from Bing" deletes 50 restaurants then it is immediately clear that this must have been a mistake, whereas a changeset comment of "removing restaurants which I found to have closed during last week's survey" makes it clear that you really meant to delete these restaurants for a good reason.
To increase the value of your edit and prevent edit wars by explaining why you did something and what your sources were. If someone finds you have added a house that is not visible on their aerial image they might be tempted to delete it, but if your changeset comment says "added newly erected building" then they will think twice!
As an aide memoire. Changeset comments help you to remember what you did, and why and when. Remember that it may be in 6 months or 1 years time ahead that you want the information in the comments, and it's difficult to predict why you need to find an old edit. In short: Eat your own dogfood!

Some mappers also use the changeset comment to record things they have *not*, or not yet, done ("… but this still needs more work", "… but area west of river still missing" or so).

There are situations where it is evident what a changeset is about – especially if it affects only a single object – but these situations are less common than you might think. If you have fixed a typo, a changeset comment of "fixed typo" still makes it clear that this was indeed what you intended, rather than your cat playing with the keyboard again!

How should I write Changeset Comments?

A good changeset comment should concisely and adequately describe an edit. At the minimum, this includes a verb (how you changed things) and an object (what you changed), and can be further improved by listing the places edited and the sources used.

Please focus your comments on what you have edited on the map. Avoid comments like:

your contact address, e.g. your email address
your good intentions, e.g. "to help people"

Your profile description on "https://openstreetmap.org/user/<your_user_name>" best fits for this information. Anyone by clicking on your username would see who are you, your motivations, and your introduction.

Examples

Real examples of good changeset comments include:

"Added buildings in industrial area."
"Add a footpath link from Donnington Close to Roman Way based on local knowledge"
"Updating Danish street addresses from OSAK (AWS): Bag Hegnet"
"Updated Algonquin Park boundary"
"Add country roads and cycleway SE of Newport"
"Köln: Nicht-Kreisverkehre, 'junction=roundabout' entfernt, Vz 215 nicht vorhanden"
- English: "Cologne: Removed junction=roundabout from non-roundabouts, traffic sign 215 not present"
"added a few tidal inlets to the coastline of Maranhão"
"Added houses and house numbers based on Bing and local knowledge. Some house numbers could sadly not be found."

Some changeset comments are useless and bring none of the benefits that a changeset comment can bring - again real examples:

"BBOX:3.23,41.96,3.23,41.96 ADD:14 UPD:0 DEL:0"
"151005-DE-FUe"
"Edit uploaded via ArcGIS Editor for OpenStreetMap feature service dec20 at 1/13/2012 9:56:00 AM"
"some fixes"
"fix"
"additions to map"
"#hotosm-project-1234 #MissingMaps #Country #redcross"
"--"
"asdf"
"United States"

Please remember that your changeset comments will remain in the database for as long as the project lives; don't use them to vent anger at software or at your fellow mappers who might have prompted you to fix something, or might have questioned your sources.

Caution when adding to an existing Changeset

Try to keep changesets to a manageable size, both in number of changes and geographical scope.

Different editor behaviours:

iD creates a new changeset for every upload. → This section is not relevant for iD.
Potlatch (version 1 and 2) appends your edits to an existing changeset by default, but you can type "C" to close the current changeset.
JOSM creates a new changeset for every upload by default, but you can change that setting from the upload dialog.

When you upload a changeset and specify a changeset description, some editors (with some settings) do not always immediately close the changeset, and subsequent edits may be added to the same changeset and therefore share the same changeset comment.

If you have finished one editing job and are starting something else, make sure to have this "something else" recorded in a separate changeset, with its own appropriate changeset comment.

Re-using old Comments

Most editors will allow you to re-use an older comment by showing them in a drop-down box or by pre-filling the comment text field. This might make sense at times, but don't fall into the "convenience trap" of using too generic comments (e.g. "some fixes") just so that you can re-use them for all your edits. This makes the comments worthless. Also take care not to apply an older comment that doesn't match your edits.

JOSM pre-fills the comment box with the last changeset comment by default (if newer than 4 hours). This can lead to accidentally re-using an old (and wrong) comment. You can disable the pre-fill completely: how to.

Hashtags

Some users have begun using "hashtags" within changeset comments. As hashtags are usually aimed at machines, not humans, there has been some debate about whether hashtags belong in "good changeset comments", and it is not widely agreed. OpenStreetMap allows adding other tags to changesets, and machine-readable keywords would have a better home in a separate tag like "keywords" or "hashtags". As of August 2017, the iD editor supports a separate "hashtags" field with changeset uploads. Despite this, some tools will pre-populate the changeset comments with hashtags, meanwhile other tools will use, or even depend on them for analysing/visualising changesets. Hashtags are simply words within the free-form text field with hash (#) prefix. They can be used alongside, or interspersed within, text composed manually as a human-readable comment, and certainly a good changeset comment should do this rather than only including pre-populated text.

What should I do if someone doesn't use good changeset comments?

Ask them nicely to do so!

If you're commenting on a changeset by another user, always try and be polite

Hello $mapper

or

Hello $mapper and welcome to OpenStreetMap!

☝️if they're a new mapper

If they have been using short or unhelpful comments such as "." you could add this to your changeset discussion comment:

Also, please do use meaningful changeset comments - “.” does not help other mappers understand what you are doing.

If they share the same language as you then obviously write the discussion comment in that language; if they don't then use an online translator such as Google/Microsoft/Deepl to translate it into their language.

Search for changeset comments

OSMCha - Login needed, go to 'Filters', add a comment string and apply
tbc