Contents

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!

Examples

A good changeset comment should concisely and adequately describe an edit. 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"

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

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.