Customizing release notes content

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 varialbles, upon execution of the template, variables are replaced with actual values. The below images shows how variables are added to the template.

Whereas this image shows the output of the template that replaces variables with actual values/data from Jira.

List of supported output variables

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.

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

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.

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.

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.

Table layout

This layout is fairly straightforward & does not need any additional configurations. All the fields that are selected (from Feilds 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.

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.

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.

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.

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.

The Order by clause in JQLs respects the sorting of Group by fields as well. This means that groups created by the Group by fields in the JQL section can be ordered in the desired sequence. Additionally, you can now choose where to place orphan elements of the respective Group by field. This update provides greater flexibility and control over the organization of your data.

Here is an example:

• There is JQL section with the Components field as a group-by field.

• So the Jira issue data returned by this JQL section will be grouped by the value of their component.

• If you want those groups to appear in a certain order (ascending or descending), then you should include the group-by field (Components field in this case) in the Order by clause of the JQL like this

• This will automatically order the groups created by the Group-by’ field in the order defined in the JQL.

• You can include multiple fields in the order by clause of the JQL and the order of all such fields will be honored in the output of that JQL section.

Orphan elements

• Now if there are any Jira issues where the value of the Components field is blank, such issues are called orphans.

  • By default, the orphan issues are placed at the bottom of the group.

  • However, you can choose to place them at the top of the group.

  • Navigate to the field customization menu of the concerned group by field to choose where the orphan issues should be placed.

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.

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:

Charts - bar chart

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

• Title - Chart title, this is displayed to the end user

• Type - If creating Bar chart select Bar chart, to display the count. select Stats

• JQL - Add the relevant JQL

• X-axis - Define the Jira issue field that should be displayed on the x-axis.

  • For eg. in chart from image below, we have selected Assignee for the X-axis so it shows the names of the users and on Y-axis it shows the numbers by default

• Return - It will be counted by default

A bar chart place holder image shall be inserted into the template. Users can resize this image to resize the designated area for the bar chart within the template.

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

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.

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.

Below image shows the sample output preview of the email.

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.

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

• 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 issye 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 https://amoeboids.atlassian.net/wiki/spaces/ARN/pages/3801612289/Generator+for+AI-powered+release+notes#Feilds-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.