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!

Is using Changeset Comments mandatory?

As described above, using changeset comments is a very good habit and not using them may be considered impolite, especially if you are a long-time mapper or if you are mapping a lot. The Data Working Group has the authority to enforce the use of changeset comments and will frequently do that in cases where other community members complain about someone's edits.

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."
"Added Trees"
"Add a footpath link from Donnington Close to Roman Way based on a survey"
"Updating Danish street addresses from OSAK (AWS): Bag Hegnet"
"Updated Algonquin Park boundary"
"Add country roads and cycleway SE of Newport"
"Added Suffragist Memorial area and updated paths/parking nearby"
"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 a survey. Some house numbers could sadly not be found."
"Adding Business Name to Driveway. Source = Owner"

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

"some fixes"
"fix"
"additions to map"
"--"
"added details"
"Update"
"misc. improvements"
"asdf"
"United States"

The following examples may have been automatically generated, and while they appear to be conveying some information they do not really describe anything useful about the "what" and "why" of a change:

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

The following examples have been automatically generated by popular tools. These are a little better because they at least allow us to find more information elsewhere about the "what" and "why" of a wider project, but they are not a replacement for a (preferably human-written) description of the specific edit that lets a reviewer understand the intent without consulting external sources:

"https://maproulette.org/browse/challenges/17994"
"#hotosm-project-1234 #MissingMaps #Country #redcross"

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.

As part of the OSMF Organised Editing Guidelines, it is suggested to include a unique hashtag in changeset comments, the hashtag should also be clearly stated on the wiki page of the Organised Editing activity. It however unclear if this hashtag should be inserted before or after a human-readable text that actually describes the changeset.

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

Write to the mapper

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.

Write to the relevant author of software

In some cases users of some software systematically make for example edits without changeset comment at all. In such case it is useful to check whether this software does try to stop them.

For example, editor should ask user to fill changeset comment if missing.

In case where editing software is not asking user to fix very common mistakes, it would be useful to open an issue requesting change (if not open already). Maybe also sending patch implementing such feature.

Search for changeset comments

OSMCha - Login needed, go to 'Filters', add a comment string and apply
Filtering OSM Changesets by a Specific Comment by Pascal Neis
tbc

External links

RfC: deprecate hashtag-only changeset comments