RU:Good changeset comments

Что такое комментарий к пакету правок?

Пакет правок — это набор изменений, сделанных одним пользователем за относительно небольшой отрезок времени.

Когда вы загружаете правки на сервер, программа редактирования предложит вам ввести описание пакета правок.

• Диалоговые окна некоторых редакторов
• 

  iD

• 

  Potlatch 2

• 

  JOSM

Комментарий, который вы вводите, будет отображаться вместе с вашими правками во многих случаях, например, когда кто-нибудь изучает историю объекта или смотрит список всех правок в области.

xkcd иллютрирует типичную проблему с комментариями

Если вы знакомы с git, то комментарии к пакетам правок аналогичны git commit message по правилам написания, целям и назначению. Сами же пакеты правок (changeset) аналогичны коммитам.

Зачем мне писать комментарии к правкам?

Есть множество причин, почему вы должны сделать комментарий к своей правке для описания внесенных изменений:

• Из вежливости к вашим коллегам-картографам, ведь этот комментарий помогает им легче понять что вы сделали и почему. Если вы не оставляете комментарий к правкам, то это выглядит как "Это не твоё дело, что я тут сделал и почему" что явно не очень хорошо вписывается в проект где все работают сообща.
• Во избежание недоразумений и быстрого исправления ошибок. Если правка с комментарием "Обвёл пару домиков по Bing" удалет 50 ресторанов, то очевидно что это ошибка. Если бы комметарий был вроде "Удаляю закрывшиеся рестораны которые я встретил прогуливаясь на прошлой неделе" то всем было бы сразу ясно зачем удалили эти рестораны и почему.
• Увеличить ценность ваших правок и предотвратить войну правок показав почему вы сделали правку и на основании каких источников. Если кто-то обнаружит, что вы добавили дом, который совершенно не видно на спутниковом снимке, то захочет удалить его. Но взглянув на комментарий "Добавил недавно возведённый дом" он передумает.
• В качестве памятки. Комментарии помогут вам в будущем вспомнить что вы делали, почему и зачем. Попробуйте через 6 месяцев или год вспомнить эту информацию :)

Некоторые картографы также используют комментарии чтобы показачть что они пока ещё не завершили работу. ("… но надо ещё доработать …", "… но область к западу от реки пока отсутствует …" и тому подобное)

Бывают ситуации, когда назначение пакета правок очевидно — особенно если он затрагивает только один объект. Но так бывает сильно реже чем может показаться. Если вы поправили опечатку, комментарий "Поправил опечатку" всё ещё помогает прояснить что вы реально хотели исправить опечатку, а не пустили кота походить по клавиатуре.

Примеры

Как надо делать

Хороший комментарий должен кратко и адекватно описывать правку.

Вот несколько примеров хороших комментариев :

• "Проезд был неровно обозначен."
• "Инфраструктура школы не была обозначена."
• В целом можно посмотреть как пишет комментарии этот картограф

Также можно посмотреть на примеры английских комментариев:

• "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 knowledge. Some house numbers could sadly not be found."

Как не стоит делать

Некоторые комментарии бесполезны и не приносят пользы. Вот некоторые реальные плохие примеры:

• "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"
• "Added unknown object"
• "Исправления"
• "Новая информация"
• "some fixes"
• "fix"
• "additions to map"
• "--"
• Больше плохих примеров можно посмотреть тут.

Помните, что ваши комментарии будут жить в базе столько, сколько будет жить проект. Поэтому не стоит выражать свою злость, гнев, недовольство редакторами или вашими коллегами-картографами.

Будьте осторожны, дополняя открытый пакет правок

Поведение редакторов:

• iD создаёт новый пакет правок для каждой отгрузки. → Эта секция не относится к iD.
• Potlatch (версии 1 и 2) дописывает ваши правки в существующий пакет правок по умолчанию, но вы можете нажать C чтобы закрыть текущий пакет правок (changeset).
• JOSM по умолчанию создаёт новый пакет правок для каждой отгрузки, но вы можете изменить эту настройку в диалоге отгрузки (upload).

Когда вы отгружаете ваши правки на сервер и указываете комментарий, некоторые редакторы (с некоторыми настройками) не всегда закрывают пакет правок. Таким образом несколько правок могут быть объеденены в общий пакет с едиными комментарием.

Если вы завершили определённую задачу и приступили к другой, удостоверьтесь что эта другая задача будет сохранена как отдельный пакет правок с отдельным комментарием.

Повторное использование комментариев

Большиство редакторов разрешают переиспользовать предыдущий комментарий (показывая его в выпадающем меню). Это иногда имеет смысл, но не попадайтесь в "ловушку удобства" используя слишком общие комментарии ("немного правок") только для того, чтобы переиспользовать его при следующей отгрузке. Это делает комментарии бесполезными. Также обратите внимание и случайно не используйте старый коммантарий к новому пакету правок.

Смотрите также

• Key:comment - как комментарии к пакетам правок хранятся в базе данных;
• Template:UserAppreciatesGoodChangesetComments - чтобы использовать шаблон «пользователь любит хорошие комментарии к пакетам правок», добавьте {{UserAppreciatesGoodChangesetComments}} на свою страницу пользователя в вики.