|A description of a changeset primarily for other mappers.|
|Used on these elements|
|Status: De facto|
|Tools for this tag|
The comment tag is used when describing changesets, and was introduced during API 0.6. It's used as a way for a mapper to describe what, or more interestingly, why, they made such changes. For example, when a node tagged with highway=bus_stop is moved, the changeset comment might be either "moved bus stop after recent roadworks" or "moved bus stop, was in wrong place". This can then help explain to other mappers why particular changes were made.
The comment tag is shown in various places on the website, notably in the history tab and other views involving changesets. Changeset comments are not mandatory. A changeset comment is a message to your fellow mappers, telling them what you did and why. Therefore, a meaningful message shows consideration for your fellow mappers.
Not taking the time to add such a message, or adding meaningless comments, is considered rude or disrespectful by some. On the other hand many changeset comments may not even be read and some consider it a waste of time to do something that few if any will ever read and would rather use the time to improve the map data.
See Good changeset comments for best practices.
Other "comment" text within OpenStreetMap
There are various other ways of leaving behind free text within OpenStreetMap as a way of communicating with other mappers.
Other commonly used keys are...
- note=* - for adding notes to yourself and your fellow mappers.
- description=* - for adding text that might be viewable to the end user.
- fixme=* - mark objects and places that need further attention
These are generally used on nodes/ways/relations to describe real-world things like "the busstop is actually here but the signpost was knocked down in september 2009", whereas the comment tag is used on changesets.
Changeset discussions can take place in relation to a particular changeset. Multiple users have a to-and-fro discussion, with the topic of discussion being the changes made in that changeset. Changeset discussions can be confused with changeset comments. A changeset has one comment, written by the person who did the change (or no comment if they left it blank)
Notes are a very simple mechanism allowing anyone (even non-logged-in site visitors) to leaving a bit of freeform text at a particular position on the map, describing a problem with the map or some missing data to be added. Notes are not attached to nodes/ways/relations or changesets. They're just placed at a location.
There are many other contact channels of course. For any extensive discussion with another mapper, you should always move to these more suitable channels. Also note that all opportunities for posting free-form text, also present the opportunity to be polite to each-other! See also Community Code of Conduct (Draft)
Guidance for developers
Especially with respect to changesets:
- Comment tags shouldn't be automatically generated. If a data-consuming project wishes automated data, it can calculate it itself.
- Comment tags are not mandatory - e.g. perhaps an editor's workflow doesn't suit adding comments (c.f. Potlatch (v1.x) live mode). However, meaningful changeset comments are very useful, so it is a good idea for editing tools to make it easy for mappers to add them. If your software makes the adding of comments mandatory, you may find that some mappers react in a negative way and enter "garbage" comments.
- Comment tags should be available in the editor if the user wants to use them.