Release Notes Automation

Release notes are documents that are shared with end users, customers and clients of an organization. It also plays an important role in an organization where multiple team or track work towards one final product while each team/track produce an independent component or part of the final product.

They are usually produced during the end phase of software release cycle after completing quality test and ready to be delivered. It contains details such as version number, release date, Highlights of this release, compatibility with other components or products, list of bugs that got fixed, test results and known issues if any.

Delivery manager or product owner creates often release notes with support from the entire team. In most cases it will be a manual process, which involves more of coordination, and follow up with team members to gather all information and put together as one document. Below diagram shows a typical flow in creating a release note document
Manual Release Notes

Automation

This blog is created to help making this process an automated one. There are different ways to automate based on the tools and process the teams are following. The approach I am going to elaborate is based on the tools we follow in our organization. Below are the lists of tools I will be using to explain release notes automation process

  1. JIRA – Ticket tracking tool. Features and Bugs are logged as tickets and will be worked on by developers to complete the features.
  2. Jenkins – Build tool. Used to build final product and make sure each commits by developer are compiling fine.
  3. Stash/GitHub – Source code repository
  4. Confluence – Documentation tool. Organization wide shared document repository

Steps for Automation

Following are the major steps to make automation work

  1. Fix version and Release ticket
  2. Trigger Point
  3. Release notes details
  4. Create/Store release notes
  5. Update Confluence doc
Fix version and Release ticket

This is preliminary step that needs to be followed religiously to get all the feature list and bug fixes from ticket tracking system (JIRA in this case).

Every ticket created should have a “Fix version” which would be the release version. “Fix version” will be used to generate list of tickets that are being completed for a particular release.

“Release ticket” is created for releasing the component and it should have “Fix version” in it. Tech lead who releases the component should make sure they provide release ticket detail to the build system (Jenkins). Build system will use this detail to fetch all tickets that are attached to this “Fix version”.

Trigger Point

We need a trigger point to start the release notes job. All our release process start based on creating a tag and we use that as a trigger point to start the release note creation process.

Release Notes Details

Below are the details we will be covering in our release notes document

  • Version of the component
  • Release Date
  • Summary (Highlights) of the release
  • List of tickets that gets addressed during this release
  • Unit test case coverage details
  • Compatibility of other components

These details are being retrieved from two sources.

  1. Build script during release
    • Release version
    • Release version
    • Code coverage detail
  2. From JIRA Web Service API
    • Summary (Highlights) of the release
    • List of tickets address for this release
Create/Store Release Notes

This is a big step in which release notes gets generated and stored using script. We use Node JS script to create release notes based on predefined HTML template. Based on the information gathered from different sources Node JS script will generate HTML file as release notes and store them in Stash/GitHub repo. There will be a master HTML page that will include all the created release notes in iFrames, which can be referenced from Confluence doc.

Update Confluence

Confluence tool has the capability to point to an external file in an iFrame. The master HTML file which gets created in the previous step will be pointed to this doc. This makes this doc to have all release notes that gets created.

Sample Workflow

  1. User creates a annotated tag with release ticket in the comment. Sample tag created for Bento Android below
    git tag -a bento/v3.4.1-RC1 -m "Release ticket ADAND-850"

  2. Tag creation triggers Release Jenkins Job, which pushes the artifact to Nexus and then sends an email to team about the component release.

  3. On successful completion of release, Release Jenkins Job gathers details like Version, Release Ticket, Code Coverage, Compatibility components tested with and triggers Release Notes Jenkins Job. Below is the sample param that’s being sent to Release Notes Jenkins Job

    { "fixVersionTicket":"ADAND-783", "version":"0.3.4", "dependencies":"Android Player=2.10.2,TVE=4.6.2-SNAPSHOT", "coverageXml":"<root> <counter type='INSTRUCTION' missed='943' covered='12542'/> <counter type='BRANCH' missed='380' covered='833'/> <counter type='LINE' missed='225' covered='2849'/> <counter type='COMPLEXITY' missed='372' covered='868'/> <counter type='METHOD' missed='24' covered='575'/> <counter type='CLASS' missed='2' covered='111'/> </root>" }

  4. Release Notes Jenkins Job uses a Node Script to get list of tickets associated with the release tickets. Uses a HTML template to substitute the placeholders with corresponding values and generate release notes HTML files.

  5. Generated Release Notes HTML files are stored in GitHub/Stash.

  6. Confluence doc which points the release notes will get updated for every release we make.

  7. Flowchart diagram for this is given below

Sample workflow

Saravanan Kathiresan

Read more posts by this author.