Создание пользовательского шаблона заметок релиза, содержащего комментарии к релизу

Многие пользователи Jira хотят расширить выпущенные примечания к выпуску, чтобы включить комментарии к релизу для каждой задачи в отчете. В этом учебном руководстве показано, как это сделать, используя пользовательское поле и некоторые настраиваемые шаблоны Velocity. Учебник предполагает, что читатель понимает пользовательские поля Jira. Дополнительные сведения о пользовательских полях см. в документации Jira.

Этот учебник относится только к серверу Jira.

Шаг 1. Создание пользовательского поля.

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

  1. В Jira нажмите «Задачи».
  2. В левом меню выберите «Пользовательские поля».
  3. Чтобы начать добавление мастера пользовательских полей, нажмите «Добавить пользовательское поле». Создайте поле со следующими данными:
  • Тип: текстовое поле (многострочное).
  • Имя: примечания к комментариям к выпуску.
  • Описание: Это комментарий для включения в выпущенные примечания к релизу.
  • Связанные экраны: разрешить экран задач
  1. Чтобы создать свое настраиваемое поле, нажмите «Обновить».

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

Шаг 2. Создание пользовательских шаблонов Velocity для примечаний к релизу

Velocity - это шаблонный двигатель, используемый в Jira. В настоящее время Jira поставляется с текстом и шаблоном отчета заметок к релизу. В этом уроке вы измените существующие шаблоны, чтобы также отобразить пользовательское поле, созданное на предыдущем шаге, для каждой задачи в отчете. Эти шаблоны расположены в разделе <jira-application-dir> / WEB-INF / classes / templates / jira / project /releasenotes. Модифицированный шаблон releasenotes-text.vm выглядит примерно так:


<hr width="100%">
 
<a name="editarea"><h2>$action.getText('release.notes.edit.copy')</h2></a>
<p>$action.getText('release.notes.description')<br></p>
 
<textarea rows="40" cols="120">
 
$action.getText('release.notes.heading', $project, $version)
 
#foreach ($issueType in $issueTypes)
#if($issueType.issues.size() > 0)
** $textUtils.htmlEncode($issueType.name)
#foreach ($issue in $issueType.issues)
* [$issue.key] - $textUtils.htmlEncode($issue.summary)#getReleaseNoteComment($issue $customFieldManager)
#end
#end
 
#end
</textarea>
</td>
</tr>
</table>
</body>

Модифицированный шаблон releasenotes-html.vm выглядит так:


#macro (getReleaseNoteComment $issue $customFieldManager)
#set ($customFields = $customFieldManager.getCustomFieldObjects($issue.project.getLong("id"), $issue.issueType.getString("id")))
#foreach($customField in $customFields)
#if($customField.name.equals("release notes comments"))
#if($customField.getValue($issue)) - <b>Release Comment</b>: $textUtils.htmlEncode($customField.getValue($issue))#end
#end
#end
#end
<title>$action.getText('release.notes.html.title', $project, $version) </title>
<body>
<table>
<tr>
<td>
 
#foreach ($issueType in $issueTypes)
#if($issueType.issues.size() > 0)
<h2>$textUtils.htmlEncode($issueType.name)</h2>
<ul>
#foreach ($issue in $issueType.issues)
<li>[<a xhref='$!appProps.getString("jira.baseurl")/browse/$issue.key'>$issue.key</a>] -
 $textUtils.htmlEncode($issue.summary)#getReleaseNoteComment($issue $customFieldManager)</li>
#end
</ul>
#end
#end
</td>
</tr>
 
<tr>
<td>
 
<hr width="100%">
 
<a name="editarea"><h2>$action.getText('release.notes.edit.copy')</h2></a>
<p>$action.getText('release.notes.description')<br></p>
 
<textarea rows="40" cols="120">
 
$action.getText('release.notes.heading', $project, $version)
#foreach ($issueType in $issueTypes)
#if($issueType.issues.size() > 0)
 
<h2>$textUtils.htmlEncode($issueType.name)</h2>
<ul>
#foreach ($issue in $issueType.issues)
<li>[<a xhref='$!appProps.getString("jira.baseurl")/browse/$issue.key'>$issue.key</a>] -
 $textUtils.htmlEncode($issue.summary)#getReleaseNoteComment($issue $customFieldManager)</li>
#end
</ul>
#end
#end
</textarea>
</td>
</tr>
</table>
</body>

Единственное различие между двумя шаблонами и их оригиналами - это определение макроса Velocity getReleaseNoteComment и его использование после резюме задач. В макросе мы используем контекстную переменную $customFieldManager, которая является экземпляром интерфейса com.atlassian.jira.issue.CustomFieldManagеr.

Мы используем CustomFieldManager для получения всех CustomFieldObjects для текущей задачи, а затем выполняем итерации  в поисках поля, которое мы хотим. Когда мы находим поле «комментарии к Замечаниям к релизу», мы получаем и отображаем значение, если оно не равно нулю.

Мы не используем метод getCustomFieldObjectByName, потому что он устарел, и мы не можем быть уверены, что имя пользовательского поля будет уникальным в экземпляре Jira.

Эти шаблоны Velocity отображают пользовательские поля «Примечания к комментарии к замечаниям к релизу» в ваших сгенерированных примечаниях к релизу. Вы можете перезапустить Jira, и она подберет изменения.

Вот пример комментариев к замечаниям к релизу:

РИСУНОК

Развертывание шаблонов Velocity без перезагрузки

В экземпляре разработки вы можете играть с заменой файлов Velocity без перезагрузки.

Из <jira-install> /atlassian-jira/WEB-INF/classes/velocity.properties:

  1. Измените resource.loader.cache с true на false.
  2. Раскомментируйте (т. е. удалите знак #) \ # velocityimacro.library.autoreload = true.

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

Шаг 3: измените Jira для использования пользовательских шаблонов Velocity

  1. Поместите два шаблона Velocity в подкаталог <jira-application-dir> / WEB-INF / classes / templates / jira / project / releasenotes каталога установки Jira.
  2. Чтобы указать новые форматы шаблонов, измените значение свойства jira.releasenotes.templates в jira-config.properties вашего домашнего каталога Jira.

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

Нет необходимости изменять свойство jira.releasenotes.templatenames, потому что нам по-прежнему нужна опция HTML и Text, и мы только изменили сами шаблоны.

  1. Измените значение свойства jira.releasenotes.templates следующим образом, представляя ваши новые файлы шаблонов HTML и Text Velocity соответственно:

jira.releasenotes.templates = releasenotes-with-releasecomment-html.vm, releasenotes-with-releasecomment-text.vm

  1. Сохраните измененный файл jira-config.properties и перезапустите Jira.
  1. Теперь вы можете проверить, работает ли то, что вы сделали. Вы должны убедиться, что вы можете создавать некоторые заметки о релизе, которые будут содержать задачи.
  2. Убедитесь, что вы создали версию для проекта, в котором вы тестируете это (примечания к релизу могут быть созданы только для версии).
  3. Убедитесь, что у вас есть некоторые задачи, в которых исправлены версии, установленные для версии, которую вы создали выше.
  4. Убедитесь, что вы ввели какой-либо текст комментария к релизу с задачами с исправленными версиями выше (в нашем примере, если нет комментариев к релизу для задачи, тогда ничего не будет отображаться, и оно будет очень похоже на оригинальные примечания к релизу).
  5. Перейдите на страницу «Примечания к релизу» и следуйте инструкциям руководства «Создание примечаний к релизу». Вы должны увидеть текст комментариев к заметках к релизу после  текста резюме для каждой задачи.

Шаг 4: Примечания к релизу фильтра

В качестве дополнительной опции вы можете отфильтровать заметки к релизу на основе различных свойств задачи, чтобы узнать, соответствуют ли они вашим критериям. Например, чтобы печатать только те задачи, которые имеют разрешение Fixed и Status, поставьте оператор #if вокруг кода, который создает маркер(bullet point) для задачи:


#set ($resolution = $issue.getResolutionObject())
#set ($status = $issue.getStatusObject())
## check for resolved or closed and fixed
#if (($status.getId() == "5" || $status.getId() == "6") && $resolution.getId() == "1")
 <li>[<a href='$!appProps.getString("jira.baseurl")/browse/$issue.getString("key")'>$issue.getString("key")</a>] -
 $textUtils.htmlEncode($issue.getString("summary"))#getReleaseNoteComment($issue $customFieldManager)</li>
#end

Вывод

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

Удачи !

Похожие темы

  • Доступные поля: подробную информацию о том, какую информацию вы можете получить, см. в Jira Remote API. Например:
    • Проекты
    • Задачи
  • Синтаксис шаблона: Руководство пользователя Velocity поможет вам выбрать правильный синтаксис.
  • Помощь и поддержка: сообщение в категории разработки Jira в Atlassian Community, чтобы получить помощь от сообщества пользователей.

По материалам Atlassian JIRA  Server Developer Creating a custom Release Notes template containing release comments