Access your CHANGELOG within Axway Appcelerator to implement a “What’s New” Feature

Adam Armstrong
Feb 13, 2019 · 3 min read

Prerequisites

  • Alloy App
  • CHANGELOG.md file
  • changelog-parser npm package
  • alloy.jmk file

What is a CHANGELOG?

A changelog is a file which contains a curated, chronologically ordered list of notable changes for each version of a project.

**Note:** A CHANGELOG is not the same as a git commit log. A CHANGELOG should only contain info the end user needs to know regarding changes to the software.

Convert CHANGELOG to Markdown

Appcelerator ships with a CHANGELOG.txt file. Change the file extension to .md so we can leverage all of the features of Markdown.

Convert your CHANGELOG contents from plain text to Markdown

To programatically access the contents, we need to adopt a standard. One of the most widely adopted standards is keep a changelog. Visit that link for more detail but here is a rough outline of how a release entry might look.

Add the ‘changelog-parser’ npm package (we will use this to export our CHANGELOG to a JSON Object at compile time)

  • Simply run this to install the command-line version
  • Open the file: **/app/alloy.jmk** (If it doesnt exists, simply create one) and copy/paste this into that file

Now, when we compile our Alloy app, before anything else is compiled, the “pre:load” task runs, ensures the /app/lib directory exists, and then parses the `CHANGELOG.md` file into a JSON Object saved into a new file, `changelog.json`.

For reference, here’s how the above CHANGELOG release looks after being converted to a JSON Object:

This gives you a Top Level Array `”versions”` with the first record [0] being the most recent version and each item in the Array includes:

  • `body` is a flattened list of features in markdwoon format
  • `parsed` is an array of features in plain text
  • `Added` is an array of “Added” features
  • `Fixed` is an array of “Fixed” features

Access your changelog.json file within your Mobile App

This is really straight forward. We simply get the file in the resourcesDirectory, read it, and then parse it as JSON.

Utilizing in your App

Where you go from here will greatly vary based on your app.

  • Determine a new version has been installed
  • On launch you may want to get the current version installed using
  • Then compare against an already saved value of the last version that was installed using
  • If new version, then present a modal with the respective version array item in your changelog variable

Output:

New Version:

Version: 4.2.9

Released: 2019–02–13

  • Whatever you do, dont forget to update your saved value so that the user doesnt get prompted again on the next launch

You know have a structured CHANGELOG in Markdown that is not only in a “friendly” format for git repos but also availabale as a JSON Object within your app.

Adam T Armstrong

Mobile Developer and IT Manager

Adam T Armstrong

Mobile Developer and IT Manager

Adam Armstrong

Written by

Web Designer, Mobile App Developer, IT Manager & Fitness Guru

Adam T Armstrong

Mobile Developer and IT Manager