Renaming “Releases“ to “Packages“

Topics

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 package and use them for the notes generation.

Release notes templates support rich text formatting. Furthermore, data from version or package (such as version or package 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. Open

      

3. Specify template name and save a template with a default body:

   1. Open

      

4. Click

   button

5. Choose version from a list an click button

6. Download generated release notes as HTML

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 package while the release notes generation.

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

Version variables

• Name

• Start date

• Release date

• Projected release date

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

• Version specific custom properties

Package variables

• Name

• Start date

• Release date

• Projected release

• Release delayed. "Not Delayed" or "Delayed"  values will be injected to the notes depends on the package 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.

• Package specific custom properties

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 package 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. Package specific variables

      1. Start date

      2. Release date

      3. Projected release date

      4. Versions in package

      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.

    

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.

    

Custom properties in JQL

You can also use custom properties for versions and package to define JQL. If you do we will disable JQL validation, therefore suggest to enter a valid JQL with some hard-coded values and then change it to injectable variables.

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.

Package Versions section

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

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 package / 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 package-specific templates. For package-specific templates the table will show all the included versions and their Deployed Environments, e.g.

Your own 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 package. Also might be a solution to extend our standard variables list with your own list.

To add one click "+ Free text variable" and name it accordingly

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.

Download as AsciiDoc (Coming Soon)

AsciiDoc is a lightweight markup language that helps you concentrate on writing content rather than being distracted by complex word processors, bury the content in XML schemas like DocBook, or battle with finicky WYSIWYG editors. Read more.

With Flexible Release Notes in Release Management App you can now download your notes in AsciiDoc format.

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.

We suggest token-based authentication as default scenario. This is available in Confluence version 7.9 or later.

Please navigate to Atlassian documentation on How to Use Personal Access Tokens.

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.

Basic authentication requires you to enter login/password of your Confluence user.

Troubleshooting connectivity

With basic authentication there's usually some fuss with 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>.

    

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

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

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.

Here's the link to generated notes from Jira issue view: