Zh-hant:Good changeset comments
變更組合是由單一一位使用者在相對短的時間做的一組編輯。當你上傳一個變更組合，你使用的編輯器會讓你有機會輸入變更組合註解用以描述你的編輯。
- dialogue boxes of some editors
The comment you enter here will be saved to the database as a tag (with the key:comment) of our changeset. 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.
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"
- "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" (German for "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 knowlege. 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"
- "--"
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.
See also
- Proposed features/changeset tags
- Template:UserAppreciatesGoodChangesetComments - to use this template, put {{UserAppreciatesGoodChangesetComments}} on your user page.