Интеграция с системами отслеживания ошибок/проблем

При разработке программ очень часто бывает, что изменения следует связать с определенным ID ошибки или проблемы. Пользователи системы отслеживания ошибок (или системы отслеживания проблем) хотели бы связывать изменения, сделанные ими в Subversion, с конкретным ID в этой системе. Поэтому большинство систем отслеживания проблем предоставляют выполняемый перед фиксацией скрипт ловушки, который анализирует сообщение журнала для обнаружения ID ошибки, с которой связана эта фиксация. Этот способ до некоторой степени подвержен ошибкам, поскольку рассчитан на то, что пользователь напишет сообщение журнала должным образом, чтобы скрипт ловушки 'перед-фиксацией' смог разобрать его правильно.

TortoiseSVN может помочь пользователю двумя способами:

  1. Когда пользователь вводит сообщение журнала, к нему может быть автоматически добавлена заранее определённая строка, содержащая номер проблемы, связанной с этой фиксацией. Это уменьшает риск того, что пользователь введёт номер проблемы таким образом, что инструменты отслеживания ошибок не смогут правильно его обработать.

    Или TortoiseSVN может подсвечивать ту часть введённого сообщения журнала, которая будет распознана системой отслеживания проблем. Благодаря этому пользователь поймёт, что сообщение журнала может быть обработано правильно.

  2. Когда пользователь просматривает сообщения журнала, TortoiseSVN создаёт ссылку для каждого ID ошибки в сообщении журнала, по которой может быть запущен веб-обозреватель для просмотра описания соответствующей проблемы.

Добавление номеров проблем к сообщениям журнала

Вы можете интегрировать выбранную вами систему отслеживания ошибок с TortoiseSVN. Для этого вы должны определить некоторые свойства, начинающиеся с bugtraq:. Они должны быть установлены для папок («Установки проекта»).

Рисунок 4.66. Диалоговое окно свойств Bugtraq

Диалоговое окно свойств Bugtraq


Когда вы редактируете любое из свойств bugtraq используется специальный редактор для упрощения установки подходящих значений.

Есть два способа интегрировать TortoiseSVN с системами отслеживания проблем: один основан на простых строках, другой - на регулярных выражениях. Свойства, используемые в обоих подходах:

bugtraq:url

Напишите в этом свойстве URL адрес вашего инструмента отслеживания ошибок. Это должен быть правильно сформированный URI и должен содержать %BUGID%. %BUGID% заменяется номером проблемы, который вы ввели. Это позволяет TortoiseSVN показать ссылку в диалоге журнала, и когда вы смотрите на ревизию журнала сразу можете перейти в инструмент отслеживания ошибок. Вы не обязаны задавать это свойство, но тогда TortoiseSVN покажет только номер проблемы без ссылки на неё. Например, проект TortosieSVN использует http://issues.tortoisesvn.net/?do=details&id=%BUGID%.

Вы можете также использовать относительные URL вместо абсолютных. Это может пригодиться, когда ваша система отслеживания проблем расположена в том же домене/на том же сервере, что и ваше хранилище исходного кода. В случае изменения имени домена, вам не надо будет донастраивать свойство bugtraq:url. Есть два способа указания относительного адреса URL:

Если он начинается со строки ^/ предполагается, что он задан относительно корня хранилища. Например, ^/../?do=details&id=%BUGID% будет разрешаться в http://tortoisesvn.net/?do=details&id=%BUGID% если ваше хранилище расположено по адресу http://tortoisesvn.net/svn/trunk/.

URL, начинающийся со строки / предполагается заданным относительно имени сервера. Например, /?do=details&id=%BUGID% будет разрешаться в http://tortoisesvn.net/?do=details&id=%BUGID% если ваше хранилище расположено где-либо на http://tortoisesvn.net.

bugtraq:warnifnoissue

Установите это свойство в true, если желаете, чтобы TortoiseSVN предупреждал вас о незаполненном поле с номером проблемы. Допустимые значения: true/false. Если свойство не задано, предполагается значение false.

Номер проблемы в текстовом поле

При простом подходе TortoiseSVN показывает пользователю отдельное поле, в которое может быть введен ID ошибки. Затем это введённое пользователем значение добавляется к сообщению в конце/в начале как отдельная строка.

bugtraq:message

Это свойство активирует систему отслеживания ошибок в режиме поля ввода. Если это свойство установлено, тогда TortoiseSVN будет просить ввести номер ошибки при фиксации ваших изменений. Этот номер используется для добавления строки в конец сообщения журнала, для чего сообщение должно содержать %BUGID%, которое заменяется на номер ошибки при фиксации. Это служит для обеспечения того, чтобы содержащаяся в журнале фиксаций ссылка на номер проблемы всегда имела совместимый формат и могла быть обработана системой отслеживания ошибок для связывания номера проблемы с конкретной фиксацией. Например, вы можете использовать Проблема: %BUGID%, но это зависит от используемой вами системы.

bugtraq:label

Этот текст отображается TortoiseSVN в диалоге фиксации для обозначения поля ввода, в которое вы вводите номер проблемы. Если свойство не задано, отображается Bug-ID / Issue-Nr:. Помните, что окно не будет изменять размеры для размещения этой метки, поэтому размер этой метки не должен превышать 20-25 символов.

bugtraq:number

Если установлено в true, в поле номера проблемы допускаются только цифры, за исключением запятой, которая может применяться в качестве разделителя при вводе нескольких номеров. Допустимые значения: true/false. Если не задано, предполагается значение true.

bugtraq:append

Это свойство определяет, будет ли ID ошибки добавляться в конец сообщения журнала (значение true) или вставляться в начале сообщения (значение false). Допустимые значения: true/false. Если не задано, предполагается значение true, чтобы не повредить существующим проектам.

Номера проблем с использованием регулярных выражений

При подходе с регулярными выражениями, TortoiseSVN не показывает отдельного поля ввода, но помечает ту часть введённого пользователем сообщения журнала, которая будет распознана системой отслеживания ошибок. Это делается, пока пользователь пишет сообщение журнала. Это также означает, что ID ошибки может быть в любом месте сообщения журнала! Этот метод намного более гибкий, и именно он используется в самом проекте TortoiseSVN.

bugtraq:logregex

Это свойство подключает систему отслеживания ошибок в режиме регулярных выражений. Оно содержит либо одно, либо два регулярных выражения, по одному в строке.

Если два выражения установлены, то первое выражение используется как предварительный фильтр при поиске выражения, которое содержит ID ошибки. Второе выражение затем извлекает ID ошибки из результатов первого регулярного выражения. Это позволяет вам использовать список ID ошибок и выражения простым языком. Например, вы можете исправить несколько ошибок и строку наподобии этой: «This change resolves issues #23, #24 and #25».

Если вы хотите отловить ID ошибки как это сделано выше в сообщении журнала, то вы можете использовать следующее регулярное выражение, оно же используется в проекте TortoiseSVN: [Ii]ssues?:?(\s*(,|and)?\s*#\d+)+ and (\d+).

Первое выражение достаёт строку «issues #23, #24 and #25» из окружающего её сообщения журнала. Второе выражение извлекает просто десятичные числа из выдачи первого выражения, и оно вернёт «23», «24» и «25» для использования в качестве ID ошибок.

Разбирая по частям первое выражение: строка должна начинаться со слова «issue», возможно, с заглавной буквы. После этого следует необязательная «s» (более одной проблемы) и необязательное двоеточие. После чего идут одна или более групп, с нулём или более ведущих пробелов перед каждой, необязательная запятая или «and» и ещё дополнительные пробелы. В заключение, должны быть обязательный символ «#» и обязательное десятичное число.

Если задано только одно выражение, тогда группы в строке регулярного выражения должны соответствовать 'чистым' ID ошибок. Пример: [Ii]ssue(?:s)? #?(\d+) Этот метод требуется некоторым системам отслеживания проблем, например trac, но в нём труднее построить регулярное выражение. Мы рекомендуем, чтобы вы использовали этот метод, если об этом явно сказано в документации вашей системы отслеживания проблем.

Если вы незнакомы с регулярными выражениями, взгляните на введение по адресу http://en.wikipedia.org/wiki/Regular_expression[4], а также на доступные в Сети документацию и учебный курс по адресу http://www.regular-expressions.info/.

Не всегда просто получить правильное регулярное выражение, поэтому в диалог свойства bugtraq встроен тестовый диалог. Нажмите на кнопке справа от окна редактирования для вызова. Здесь вы можете ввести некоторый тестовый текст, изменять каждое регулярное выражение и видеть результат. Если регулярное выражение неверно, то цвет фона окна редактирования меняется на красный.

Если установлены оба свойства, bugtraq:message и bugtraq:logregex, свойство logregex имеет преимущество.

Подсказка

Даже если у вас нет системы отслеживания проблем с выполняемой перед фиксацией ловушкой, разбирающей ваши сообщения журнала, вы всё равно можете применить эту возможность для преобразования в ссылки проблем, упомянутых в сообщениях!

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

Некоторые tsvn:-свойства требуют значений true/false. TortoiseSVN также понимает yes как синоним true и no как синоним false.

Устанавливайте свойства на папках

Для того чтобы система работата, эти свойства должны быть установлены на папках. Когда вы фиксируете файл или папку свойства читаются из этой папки. Если там свойства не найдены, то TortoiseSVN будет искать вверх по дереву папок пока не дойдет до неверсированной папки или корня дерева (например, C:\). Если вы можете быть уверены, что каждый пользователь извлекает только из, допустим, trunk/, а не какой-то подпапки, тогда достаточно установить свойства для trunk/. Если вы не можете быть в этом уверены, то вы должны установить свойства рекурсивно для каждой подпапки. Настройки свойства глубже в иерахии проекта перекрывают настройки верхних уровней (ближе к trunk/).

Начиная с версии 1.8 TortoiseSVN и Subversion используют так называемые наследуемые свойства, которое означает, что свойство, заданное для папки, автоматически и неявно устанавливается для всех подпапок. Так что больше нет необходимости задавать свойства для всех папок, а только для корневой.

Только для свойств проекта, т.е. для tsvn:, bugtraq: и webviewer:, вы можете использовать флажок Рекурсивно для установки свойства для всех подпапок в иерархии, без установки его также для всех файлов.

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

Никакой информации системы отслеживания проблем в обозревателе хранилища

Поскольку интеграция с системой отслеживания проблем зависит от доступа к свойствам Subversion, вы сможете увидеть результаты только при использовании извлечённой рабочей копии. Получение свойств удалённо - медленная операция, поэтому вы не увидите работу этой возможности в обозревателе хранилища, если только не запустите его из вашей рабочей копии. Если вы запустили обозреватель хранилища и ввели URL хранилища, эта возможность будет недоступна.

По этой же причине свойства проекта не будут автоматически скопированы, если дочерняя папка добавляется с помощью обозревателя хранилища.

Интеграция с системой отслеживания ошибок не ограничена только TortoiseSVN, она может быть использована с любым клиентом Subversion. Для дополнительной информации прочтите Issue Tracker Integration Specification в хранилище исходного кода TortoiseSVN. («Лицензия» объясняет как получить доступ к хранилищу.)

Получение информации из системы отслеживания проблем

В предыдущем разделе мы имели дело с добавлением информации о проблемах в сообщения журнала. Но что если вам необходимо получить информацию из системы отслеживания проблем? У диалога фиксации есть COM-интерфейс, позволяющий выполнить интеграцию с внешней программой, умеющей взаимодействовать с вашей системой отслеживания проблем. Типичный запрос - получить у системы отслеживания список назначенных вам открытых проблем, чтобы вы могли выбрать проблемы, которые были затронуты в этой фиксации.

Конечно, любой такой интерфейс будет очень специфичным для Вашей системы отслеживания проблем, поэтому мы не можем предоставить эту часть, и описание создания такой программы выходит за рамки данного руководства. Определение интерфейса и примеры подключаемых модулей на C# и C++/ATL Вы можете получить в папке contrib в TortoiseSVN repository. («Лицензия» объясняет, как получить доступ к хранилищу.) Также описание API дано в Глава 7, Интерфейс IBugtraqProvider. Другой (рабочий) пример плагина на C# есть в Gurtle, который реализует требуемый COM-интерфейс для взаимодействия с системой отслеживания проблем Google Code.

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

Рисунок 4.67. Пример диалога запроса системы отслеживания проблем

Пример диалога запроса системы отслеживания проблем


В этом примере вы можете выбрать одну или более открытых проблем. Затем модуль может сгенерировать специально отформатированный текст, который он добавит к вашему сообщению журнала.



[4] Есть статья об этом и в русском разделе Википедии: http://ru.wikipedia.org/wiki/Регулярные_выражения - прим. переводчика