Customizing release notes content

While ARNR app’s native template builders are designed to compile data from multiple issues, some users need to showcase only one specific issue in detail for release notes or reports. Users currently use hardcoded JQL sections, which require creating multiple sections within a single template and manual editing before generating the report. To address this, a new mode called Spotlight will be introduced, allowing for easy creation of templates dedicated to single Jira issues.

Spotlight issue feature allows you to generate release notes for a specific issue in detail. There could be a case that you want to highlight only specific issue which is a major update. Let us see an example with steps -

When you navigate to the template builder to create/edit template, click on Spotlight issue

check the box called Add spotlight issue

In the expanded section, add the fields you want to use to display given Jira issue’s fields

Open

Once done with adding relevant fields, got to the main template body. You can add the static elements of your choice like log, announcement text, background, etc. But to highlight the Jira issue fields click on + Spotlight issue fields.

Clicking on + Spotlight issue fields will show the dropdown of the fields that you have added in step . Select the relevant fields. Below is a sample template -

Open

All the highlighted fields added in the table here are the once we have added in step and then selected in step . Save once all the changes are done and Preview.

Open

In the above image, notice that all the fields/field labels are replaced with actual values now! This way you can generate release notes for a specific issue by adding all the required fields. This will help you highlight a specific issue with its all details.

Using this option, you can provide a detailed prompt to AI and get the template generated in a few minutes.

Here is how you do it -

Click on Create template with AI (Beta). Refer to existing prompt and edit it based on your requirement and click on create. Based on prompt you have given, a new template will be generated. Since, it is an AI generated template, we recommend cross verifying all the static data and all the macros like JQL sections, stat macro, etc. to ensure all the elements are as expected and then preview the template to verify the expected output.

Open

These are the data points used to bring the values from Jira to your release notes content. The variables will be replaced by actual values for given data points. Some examples are projectName, fixVersion, userName, etc.

When you use such variables, upon execution of the template, variables are replaced with actual values.

List of supported output variables

Apart from the default variables that are typically the default fields, users may want to create custom fields and fetch that data to release notes. In such a case one can map the ARN custom variables with their Jira fields and bring the values of those fields to release notes.

All the custom variables created in ARN are global. It means, that irrespective of the projects they are created from, all non-deleted custom variables will be visible across all the projects.

In below image, notice the way ARN custom variable is used.

Open

When executing the template, this is how the preview will asks for the value of the custom fields.

Open

This just one simple use case, Read how to Manage & use ARN custom variables with more examples.

Introduction to JQL section

This section plays a crucial role in ARN templates. JQL dictates the appearance of your content and determines the data to be included in release notes and reports. It serves as the central hub for all information intended for end users.

There are three tabs on Add/Edit JQL section pop-up -

• Section

• Fields

• Layout

Section

In the section tab you will find below fields to define the content that will be posted in the release notes.

• Title - This text will be shown as a section header in the generated email or page.

• Description - This fields can contain the description of your given JQL section.

• JQL - This field is where you add the JQL to fetch the relevant issues to your release notes

• Hide section (checkbox) - Check if you wish to hide the JQL section when given JQL does not return any Jira issues

• Message - When the checkbox is unchecked, write a message that needs to be displayed when no issues are returned from the given JQL.

Fields

This tab is to display what all Jira issue fields/custom fields that are to be added to your release notes. If the Table layout is selected then these fields are added as columns. You can add the numbered columns

In the case of the sequential layout, selected fields will be listed in the sequence you have added them.

As shown in the below image, icon in front of each selected field would show some extra settings for the field like header style, Entry Style, display as link or text, etc.

Open

Read how to Save release notes without Jira fields using issue properties.

Introduction

To further customise the release notes that ARN generates, it is possible to configure custom CSS within different templates.

How to

Open any one of the above-mentioned template types & click on any JQL section to open it in Edit mode or start to Create a new one. Make sure the layout/format is set to Table.

Custom CSS can be applied for any of the selected columns, listed in the left-hand section of the Fields tab. Click on the gear icon beside any column name & it will reveal a couple of free text fields where custom CSS can be added.

Open

Header styles refer to the styling applied to the table header for that specific column whereas Entry styles CSS attributes are applied to all the data points generated within that column.

If the JQL section data is grouped by a specific column, it is possible to apply custom CSS to that data as well. Just click on the Gear icon beside Group by option. It shows the custom CSS options.

Open

Table layout

This layout is fairly straightforward & does not need any additional configurations. All the fields that are selected (from Fields tab as shown in the above image), will be displayed as table columns from left to right. Below is a sample screenshot of the generated release notes in tabular format.

Open

In this example you can see coulmn in the table like Priority, Key, Status, Issue type, and Summary. At the left top corner of tble notice the Task issue type icon which means the table is grouped by the issue type. This way using different customisation you can define the way of displaying issues from the given release.

Sequential layout

Selecting equential layout presents the selected fields (from the Fields tab) in a sequenced format. The desired layout needs to be designed within the area highlighted below.

Open

Here, the design is simply a sequence of available variables. These variables are displayed based on what fields you have chosen on the Fields tab.

Open

Any fields that you have selected to be used, can be arranged in any order you wish. For every field that is configured under Fields tab on the left, there will be two variables on the right. One that will fetch the field value & other to fetch its display label. e.g. for Priority field, there are two variables - {priority} & {priorityLabel}.

Required condition is, you have to add fields & their configurations before they can be used in the Layout section. The layout created will be repeated for every issue that is returned by your section JQL. For example, layout in the above screenshot will generate data that looks like the below screenshot.

Open

In below image check the check box called Hide field label variable when the field value is empty. If this is checked, and if the JQL does not fetch any data in the field value against a particular issue, then it hides the field variable and you can make sure that the release notes do not look like an incomplete piece of information.

Open

Introduction

ARN provides Stats & charts macro to make release notes more insightful for you & your team. To put it simply, Stats feature comes up with a number that corresponds to the count of issues that are returned by the configured JQL & chart feature lets you include a simple bar chart showing the count of issues returned by configured JQL aggregated over values of specific Jira field.

Stats

Clicking on Stats & charts would open a pop-up where the system accepts a JQL. And a return value. Return value identifies what kind of data will have to be extracted from the Jira issues that the JQL returns.

Open

Typical use cases may include, informing the audience about

• Issue distribution based on priority, type, assignee, etc

• Time spent on different kinds of issues

• Story point distribution across different issue types

Currently, the system can return a number of issues the stored JQL retrieves. So a typical use of this would look something like the image below.

Note that you can also optionally display the number as a link that leads back to Jira.

Sample stats generated with ARN:

Open

Charts - bar chart

Clicking on Stats & charts would open a pop-up, select the type as Bar chart. Below are the fields you have to to add or edit while creating a Bar chart.

Open

Once this setup is saved, bar chart place holder image will be inserted into the template. Users can resize this image to resize the designated area for the bar chart within the template.

Open

No of issues returned by the JQL will be aggregated against the unique value of the selected Jira field and a bar chart will be included within the area designated within the template.

Below image shows how the final chart will be rendered in preview/output when release notes.

Open

This is a custom plugin called Users to ARN template that highlights your team members as contributions who led to the success of the release. This simple yet interesting plugin allows you to recognize your team members and give them credit of the release’s success.

How to use the User macro/plugin?

This plugin is by default added at the end of the template.

Open

Click on it and edit given fields below -

• Titile (not visible to end users) - Add the title for example Contributors, Heroes, etc. It is only for your reference and not visible in the output. For the output, you can of course add the text or emojis as needed before this plugin in the main template body.

• JQL - The system will first fetch the Jira issues that are returned by the JQL and then look for the value of the field selected in the Jira fields (explained below).

• Jira fields - This field shows the drop-down list of User picker (single user) type and User picker (multiple users) type fields. Then the system looks for the users within the configured user picker field against those Jira issues.

  • Now, system forms the list of unique users returned in the above step. The list will contain only the display names of these users returned by Jira APIs. Users names are displayed comma-separated manner.

Open

Below image shows the sample output preview of the email.

Open

ARN templates now feature an AI-powered summary of the issues retrieved by a given JQL. This enables you to swiftly share a concise overview of the content included in the release notes or release notes report you're preparing. The process is as straightforward as adding a JQL section but with an AI element.

Steps

While customising any of the above templates, you will notice an option called +AI generator in the template editor.

Open

Clicking on this +AI generator opens up a pop-up with the below fields -

Open

• Title - This title will show up in release notes for the summary generated using this feature

• Prompt - Give a prompt to AI based on what content needs to be generated as a summary. You can input a maximum of 500 characters as a prompt.

  • +Variables - You can use ARN variables so those will be replaced with relevant values from the associated Jira issues

• JQL - Detail out the JQL so system retrieves the relevant Jira issues. System will look for the Jira issue fields that you have specified below and it will consider that selected field for the issues retrieved as per the JQL.

• Where to fetch issue data from? - Read detailed description AI Generator for AI-powered release notes | Fields in the AI Generator .

• Hide section - Check this option if you wish to hide this AI-generated section when there are no issues retrieved from the given JQL.

• Message - If you uncheck, Hide section option above then define the message you want to show when there are no issues retrieved from the JQL.

Once you are done with specifying all the above fields, click on Insert. You can check the preview to check what content AI has generated. You edit the content manually or update the prompt based on the given content and what you were expecting as a result.

Open