Changeleaf documentation (source for the public knowledge base)
Get started
- Install Changeleaf on Jira from the Atlassian Marketplace. To publish pages, also add it to Confluence on the same site (same subscription).
- A Jira admin opens Jira settings > Apps > Changeleaf and reviews the three built-in templates: Customers, Internal and Support. Change them or copy one as a new template.
- Developers write release notes in the Release note panel on work items.
- Anyone opens Apps > Release notes, picks versions and a template, and clicks Generate notes.
Writing the note on a work item
Open the work item and the Release note panel. Write one or two sentences for the people who read your release notes; leave it empty to use the summary. Tick Leave this work item out of release notes for internal work. You need permission to edit the work item.
Find what still needs a note before a release:
fixVersion = "3.5" AND releaseNoteWritten is EMPTY(no note and not marked leave out)releaseNoteWritten = yes(has a note),releaseNote ~ "export"(search the note text)
Generating a note
- Versions: pick any versions from any spaces you can browse. Same name across spaces adds every version with that name (for example all the "3.5" releases).
- Template: decides the sections, the line for each work item and where its text comes from.
- The summary line counts the work items in the note, per section, and what was left out and why. Work items without a release note lists the ones that still need a note and who owns them.
- Tabs: Preview, Edit lines, and the note as Markdown, HTML, Plain text, Wiki markup and ADF to copy anywhere.
Notes are generated as you, so they only contain work items you can see.
Editing, saving and reopening
- Edit lines: Edit replaces the text for one work item in this note only; Leave out removes it from this note; Put back undoes that. Set opening and closing text for this note.
- Save as draft keeps the note. Open it from Saved notes any time: it is generated again from Jira, your edits are kept, and Changeleaf tells you which work items came in or went out since you saved.
Publishing to Confluence
After saving, Choose a Confluence space, optionally a parent page id, and Publish to Confluence. Later, Update the page rewrites the same page, and only when the note changed, so watchers aren't notified for nothing. If the space already has a page with the note's title, Changeleaf updates that page instead of failing. Pages are published as you.
Templates (Jira admins)
| Setting | What it does |
|---|---|
| Title, opening and closing text | Tokens {versions} {spaces} {date} (latest release date) {count} {description} (the description written on the versions) |
| Line | One line per work item. Tokens {note} {key} (links to the work item) {summary} {type} {status} {priority} {components} {labels} {assignee} {space} {parent} {versions} {field:customfield_10050}. Empty brackets are dropped |
| Where the note text comes from | The Release note panel, any Jira field (for example a "Release note" text field you already have), or the summary |
| When a work item has no note | Use the summary and list it as missing; use the summary quietly; or leave it out and list it |
| Sections | Heading plus rules: work item types, labels, components (any of each) and optional JQL. A work item goes in the first section it matches. JQL is checked by Jira when you save and before every note |
| Heading for everything else | Catches work items no section matched; leave empty to drop them |
| What goes in | Sub-tasks (off by default), unfinished work (off by default), labels to leave out (no-release-note by default), group by space, order by key, priority or type |
Drafts on release (space admins)
Space settings > Release notes: choose the space's template and turn on Save a draft note when a version in this space is released. Optionally Also publish it to Confluence in a chosen space and parent page. Releasing the version again refreshes the same draft and page. Drafts are made by the app, so they include every work item in the version.
Changeleaf with Cutline and Branchline
Changeleaf reads Jira's versions as they are. Branchline (by Great Work) keeps one release in step across spaces, and Cutline (by Great Work) adds a release calendar, gates and freeze windows; a common setup is a Cutline checklist item "Release notes published" for the Changeleaf page.