Overview and quick start guide

Release management app has embedded functionality for release notes generator. User can define multiple release notes templates for version and release and use them for the notes generation.

Release notes templates support rich text formatting. Furthermore, data from version or release (such as version or release fields, issues lists etc) could be automatically injected to the release body.  

Quick start guide

In order to generate the first release notes follow a few simple steps:

1. Navigate to Release Notes tab in the main menu
2. Click create template button:
   1. 
3. Specify template name and save a template with a default body:
   1. 
4. Click button
5. Choose version from a list an click button
   1. 
6. Download generated release notes as HTML
   1. 

Release notes templates

Templates operations

User can create, clone or delete release notes template. 

Template body formatting and injectable variables

Following features are available for the rich text formatting:

...

The list of variables depends on template type: Version or Release.

Version variables

• Name
• Start date
• Release date
• Projected release
• Version delayed. "Not Delayed" or "Delayed" values will be injected to the notes depends on the version status
• Description
• Project name 
• Project key
• User name. Name of a user who generated release notes
• Current date. Date when release notes were generated.
• Current timestamp. Date and time of release notes were generated.

Release variables

• Name
• Start date
• Release date
• Projected release
• Release delayed. "Not Delayed" or "Delayed"  values will be injected to the notes depends on the release status
• User name. Name of a user who generated release notes
• Current date. Date when release notes were generated.
• Current timestamp. Date and time of release notes were generated.

JQL Table section

Table of issues based on JQL query could be added to the release notes body.

...

1. Name of the section. A section with the same name will be added to the release notes.
2. Section description. If the text is specified - it will be added as a plain text after the section name.
3. JQL variables. In order to build flexible JQL which will use data from the selected version or release the user can inject variables to JQL query. List of available variables depends on the template type
   1. Version specific variables
      1. Version name
      2. Start date
      3. Release date
      4. Projected release date
      5. Project key
      6. User name
      7. Current date
      8. Current timestamp
   2. Release specific variables
      1. Start date
      2. Release date
      3. Projected release date
      4. Versions in release
      5. User name
      6. Current date
      7. Current timestamp
4. JQL query to extract an issue list. 
5. If the option is enabled the section will be rendered if JQL will return 0 rows. Otherwise, the section will not be rendered at all.

6. If this option is enabled all the issue will be grouped by respected Jira Epics.

   Info
   title Release template type
   For Release templates you can choose an option whether to group by Epic or Version

   
   

7. The message which will be injected to a template if JQL will return 0 rows. This option will be working in case a switcher #5 is turned on.

8. Columns to be shown in the table. User can select the majority standard and custom Jira fields. See details in the chapter below.

   Info
   title Hint
   In order to extract all issues in version use JQL:  fixVersion={version.name} For all issues in the release: fixVersion IN ({release.versions})

   
   

Columns configuration

On the "Columns" tab the user can define a list of columns to be presented the table.

...

User can change columns order.

Release Versions section

For release templates you can pick up a "Release versions" table to outline the specific components and it's versions comprising your business release.

...

The output of the table looks like the following

Environments Table section

If you want to add Deployment Environments details to your Release Notes you can add "Environments table" to your template.

...

The feature could be used for both version-specific and release-specific templates. For release-specific templates the table will show all the included versions and their Deployed Environments, e.g.

Custom variables

You can define a set of free text variables that you would need to populate with each and every report generation. This is a useful workaround for the custom fields that we do not support for versions and release. Also might be a solution to extend our standard variables list with your own list.

...

Once you click "Generate" you will be asked to select a version and package as well as specify all free text variables for your notes

Export options

Download as HTML

The output on Release Notes could be downloaded as HTML

...

You can use it to Copy/Paste into MS Word, Google Docs, Confluence and any other wiki with (almost) no changes to layout. See other options below plus Upcoming Features for more formats we plan to support shortly.

Upload to Confluence

To substitute “Copy/Paste to Confluence” we implemented a direct integration with Confluence to upload into one of your available spaces.

Getting started

Authentication via token (Confluence 7.9 or later)

In order to upload your release notes to Confluence Release App need to authenticate to act on behalf of user.

...

Troubleshooting connectivity

Token based authentication should work out of the box w/o any fuss. In case there are some issues with that and you can't upload you release notes to confluence we suggest to assure there's a connectivity established from Jira Server to Confluence server via HTTPS.

Basic Authentication 

Less secured authentication option for Confluence version 7.9 or later is "Basic Authentication". Also default for previous versions of Confluence.

...

Troubleshooting connectivity

With basic authentication there's usually some fuss with connectivity.

...

... it's because Cross-Origin Resource Sharing (CORS) is not enabled for your Confluence Server as result the requests which are coming from Jira are not accepted.

To overcome please follow the instructions below

1. Stop Confluence server
2. Navigate to your confluence home directory (Usually for Linux:  /opt/atlassian/confluence/)
3. Open confluence_home_directory/confluence/WEB-INF/
4. Backup web.xml
5. Open web.xml for editing

6. Add the flowing code block after the last <filter>...</filter>.

   Info
   Please replace  "https://jira.your_company_domain.com" to your Jira URL.

   
   

   Code Block
   linenumbers true
   <filter> <filter-name>CorsFilter</filter-name> <filter-class >org.apache.catalina.filters.CorsFilter</filter-class > <init-param> <param-name>cors.allowed.origins</param-name> <param-value>https://jira.your_company_domain.com</param-value> </init-param> <init-param> <param-name>cors.allowed.methods</param-name> <param-value>OPTIONS,GET,POST,PUT,DELETE</param-value> </init-param> <init-param> <param-name>cors.exposed.headers</param-name> <param-value>Access-Control-Allow-Origin,Access-Control-Allow-Credentials</param-value> </init-param> <init-param> <param-name>cors.allowed.headers</param-name> <param-value>X-Atlassian-Token,Authorization, Content-Type,X-Requested-With,accept,Origin,Access-Control-Request-Method,Access-Control-Request-Headers</param-value> </init-param> <init-param> <param-name>cors.support.credentials</param-name> <param-value>true</param-value> </init-param> </filter> <filter-mapping> <filter-name>CorsFilter</filter-name> <url-pattern>/rest/api/*</url-pattern> </filter-mapping>

   
   

7. Save changes
8. Start Confluence server and make sure that the server has been successfully started. If no, restore web.xml from backup

...

4. Add your Jira host and click the checkbox “All incoming“

5. Test Jira URL 

Configuring the destination

If you already connected to confluence you will see the following dialog to help us define the destination to upload your release notes

...

Click on the link specified to navigate to your release notes in confluence.

...

Propagating Confluence link to Jira issues

You have an option to automatically add Confluence link with generated notes to all encompassing Epics. To do so turn on "Add release notes link to epics" toggle before you push to Confluence.

...