How to set up a release notes template in Jira
By Jake Marsh · Updated
Jira Cloud has no release notes templates of its own; its release notes list a version's work items in a fixed layout. With Changeleaf, a Jira admin opens Jira settings > Apps > Changeleaf, edits one of the three built-in templates (Customers, Internal, Support) or clicks New template, and sets the title, the sections, the line each work item gets and where its text comes from. Anyone generating notes then picks the template and gets the same layout every release.
The three templates you start with
| Template | Title | Sections | Each line |
|---|---|---|---|
| Customers | What's new in {versions} | New, Improved, Fixed | The team's note only |
| Internal | Release notes: {versions} ({count} work items) | Features, Improvements, Bug fixes, Tasks, plus Other | Key, summary and assignee, grouped by space |
| Support | Fixes and changes in {versions} | Fixed, Changed | Key, components and the note, sorted by priority |
They are a starting point. Change any of them, or copy one as a new template for another audience, such as partners or an app store "What's new" text.
Steps to build a template
- Open Jira settings > Apps > Changeleaf and click New template, or open one to change it.
- Set the title, opening and closing text. Tokens fill themselves in:
{versions},{spaces},{date}(the latest release date),{count}and{description}(the description written on the versions). - Write the line. One line per work item, built from tokens:
{note},{key}(linked to the work item),{summary},{type},{status},{priority},{components},{labels},{assignee},{space},{parent},{versions}, and any custom field as{field:customfield_10050}. Brackets with nothing in them are dropped, so[{components}]disappears on work items with no component. - Choose where the note text comes from: the Changeleaf panel on each work item, any Jira field (a "Release note" text field you already use, for example), or the summary.
- Decide what happens when a work item has no note: use the summary and list it as missing, use the summary quietly, or leave the work item out and list it.
- Add sections. Each has a heading and rules: work item types, labels, components and optional JQL. A work item goes in the first section it matches. Set a heading for everything else, or leave it empty to drop the rest.
- Set what goes in. Sub-tasks and unfinished work are off by default. Work items labelled
no-release-noteare left out by default. Group by space if you like, and order by key, priority or type. - Save. Jira checks every JQL rule with its strict parser when you save, and again before every note, so a typo in a field name shows an error instead of quietly emptying a section.
Example lines
| Audience | Line | Comes out as |
|---|---|---|
| Customers | {note} | Export now keeps your column order. |
| Support | {key} [{components}] {note} | WEB-412 [Export] Export now keeps your column order. |
| Team | {key} {summary} ({assignee}) | WEB-412 Keep column order in CSV export (assignee's name) |
| With a custom field | {note} ({field:customfield_10050}) | Export now keeps your column order. (Plan: Pro) |
Example sections by JQL
- Security fixes: type Bug, JQL
labels = security, placed first so those work items don't also land in Fixed. - Enterprise only: JQL
"Plan[Dropdown]" = Enterprise, with your own field name. - Breaking changes: label
breaking-change.
For a one-off list from a pasted Jira export, without templates or Jira access, our free release notes template generator groups issues into features, improvements and fixes.
Changeleaf starts with Atlassian's 30-day free trial; prices are on the Changeleaf page.
What it costs
Changeleaf is From $6 a month for up to 10 users. Every plan and the install link are on the Changeleaf page.
Changeleaf: Release Notes from Versions for Jira
Release notes from Jira versions, written by your team, shaped per audience, across spaces, saved and published to Confluence. From $6 a month for up to 10 users.
Questions
Who can create release notes templates?
Jira admins, in Jira settings > Apps > Changeleaf. Space admins pick which template their space's release-time drafts use.
Can one note use more than one template?
No. Generate the same versions once per template, one for each audience.
Can I change a single line without changing the template?
Yes. After generating, Edit lines lets you replace the text for one work item in that note only, or leave it out of that note.
What formats can I copy a note in?
Markdown, HTML, plain text, wiki markup and ADF, alongside the Preview.
More Changeleaf guides
- How to publish Jira release notes to Confluence automatically
- How to make one release note from several Jira versions and spaces
More Jira guides
- How to set up a code freeze in Jira (Cutline)
- How to book shared test environments in Jira (Berth)
- How to find duplicate issues in Jira (Mergewell)
- How to bulk delete attachments in Jira Cloud (Attachwell)