Help:Good edit comments
When you edit OpenGeofiction, the editor you are using will give you a chance of entering a changeset comment which should describe your edit. This is also known as a commit message.
The comment you enter will be saved to the database. It will be shown alongside your edit in a number of situations, for example if someone browses the history of an object or looks at all changes affecting an area.
The iD editor requires that an edit description is added before allowing a changeset to be 'closed' (saved and uploaded) to the OGF servers, and will not let you save the changeset until you do so. JOSM does not have this restriction/requirement, but will warn you before uploading edits that you should add a changeset description.
Why should I use Changeset Comments?
There are many reasons why you should make use of the changeset comment to describe your edit, these are especially relevant in free edit blue countries and collaborative purple countries:
- 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".
- To avoid misunderstandings and get mistakes fixed quickly – if an edit with a changeset comment of "added residential area" just deletes 10 highways then it is immediately clear that this must have been a mistake, whereas a changeset comment of "removing roads" makes it clear that you really meant to delete these highways for a good reason.
- To increase the value of your edit and prevent edit wars by explaining why you did something.
- 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.
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 Duds Close to Rovey Way"
- "Updated Allogin Park boundary"
- "Adding suburb NE of Gobras City"
- "Improve coastline realism: added a few tidal inlets to the coastline of Gobrassanya"
- "Added houses and house numbers"
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.
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.