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:

• Define text style
• 3 fonts are supported
• Bold, Underlined, Italic styles
• Define text colour and background
• Text alignment
• Insert numeric or bullet lists
• Insert a link
• Pictures
• Code block

Also, the user can inject variables into the template body. The variables will be replaced to actual values from the selected version or release while the release notes generation.

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.

Use  button to add a new table to the template.

Following configuration parameters are available for the table:

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.

   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.

   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.

Majority of standard fields and custom fields are available there. We also provide 2 (two) additional "CALCULATED" fields to outline

• Parent Epic Name - link to parent epic (if any) with Name to display
• Parent Epic Status - status of the parent epic

Also, the user can define various render type where it is applicable. 

Available render types are:

• Text - just a plan text
• Link - link to a presented entity. E.g. issue, user, component, label etc.
• Icon - icon for the defined value. For instance issue type icon.

User can change columns order.

Release Versions section (Coming Mar'21)

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.

Thus you can show not only the scope of new release / version but also where it's deployed until now and specif build numbers. This might be very useful for rolling updates to multiple geo-distributed environments.

The output of the "Environments table" looks like the following:

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

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

If you are using “Upload to Confluence” the first time you will receive the following dialog while attempting to upload.

Please specify your Confluence server URL, as well as Confluence user and password to sign in.

Troubleshooting connectivity

Sometimes upload to confluence might not out of the box as it depends on your Confluence Server configuration.

If you experience the following issue:

... 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>.

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

   
   

   <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

Also, the Jira host should be whitelisted in the confluence admin pannel.

In order to do so:

Could you please try to dop the following:

1. Open Administration

2. Navigate to whitelist

3. Turn on a whitelist

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

You would need to specify

• Confluence Space to shortlist the parent pages

• Parent page - any selected page within the Space defined

• Page title - you can define a custom name of use some of our release/package variables to include in the naming. If such name already exists we will create a new version of the document.

Click “Export“.

Navigating to Confluence

Once our App successfully uploaded your release notes to Confluence, the following confirmation will be shown

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

Upcoming features 

• Generate by schedule. User can define a schedule for release notes generation or connect it to some triggers. Such as moving version or release to a certain status etc.
• Send over email. Release notes will be generated by a trigger and send to relevant recipients over email.
• Add more formats of releases notes. PDF and DOC.

If you miss one of those features or would like to suggest your improvement here.