Changelog Library for Android

Table of contents

• Introduction blabla
  • What ?
  • Why ?
  • Overview
  • Features
  • Samples
• Getting started
  • Include the library
  • Configure the dialog style
  • Write the changelog
  • Display the dialog
• Customisation
  • Change the dialog title
  • Choose what release to show
  • Define your own styles
• Acknowledgments

Introduction blabla

What

A simple and lightweight library written in Kotlin to show ?beautiful? changelog and what's new dialogs.

The changelog information is written in a simple xml file under res/xml.

Why

I wanted a simple dialog to show my users after an app update. So as usual, I began browsing Github and other platforms for a nice library. I found some, for example https://github.com/MartinvanZ/Inscription.

The problem ? They all use WebViews, meaning that if you want your dialog to match your application theme, you would need to mimic it using CSS (and maintain it in case you change your mind on the colours or other stuffs, which I constantly do). I find CSS quite boring, so I decided to code my own library using only pure Android Views.

Overview

Features

• Changelog written in a simple xml format
• Choose which release(s) notes to show
• Lightweight and easy to use
• Flexible title and behavior
• Uses the AppCompat theme by default (primary and accent colors)
• Completely customizable using styles

Samples

A sample app is available under samples. Feel free to clone and test it.

Getting started

Include the library

This library is hosted on GitHub packages.

GitHub packages currently require a GitHub token... From within your GitHub account, Settings -> Developer Settings -> Personal Access Tokens -> Generate new token. Ensure the token has the scope read:packages, copy it and create a file github.properties at the root of your project, with the following content:

gpr.usr=YOUR_GITHUB_USERNAME
gpr.key=YOUR_PERSONAL_ACCESS_TOKEN

Don't forget to add github.propoerties to your .gitignore.

Now, add the maven repository in your module's build.gradle:

// github tokens for access to Github Packages
def githubProperties = new Properties()
githubProperties.load(new FileInputStream(rootProject.file("github.properties")))

repositories {
    /* ... other ... */
    maven { 
        name = "GitHubPackages"
        url = uri("https://maven.pkg.github.com/derlin/android-changelog")

        credentials {
            username = githubProperties['gpr.usr'] ?: System.getenv("GPR_USER")
            password = githubProperties['gpr.key'] ?: System.getenv("GPR_API_KEY")
        }
    }
}

Add the dependency (change version if needed):

dependencies {
    /* ... */
    implementation 'ch.derlin.android:changelog:1.1@aar'
}

Configure the dialog style

! Important Don't skip this step, or you will run into exceptions at runtime.

In your styles.xml, configure the changelog style by setting the changelogStyle attribute in your AppTheme. A default style is available, called LibChangelog:

<!-- res/values/in styles.xml -->

<!-- Your base application theme. -->
<style name="AppTheme" parent="Theme.AppCompat.Light.DarkActionBar">
    <!-- ... other configurations ... --> 
    
    <!-- Apply style for changelog -->
    <item name="changelogStyle">@style/LibChangelog</item>
</style>

Write the changelog

Create an xml file in res/xml, for example changelog.xml. The format is rather simple, so an example should be worth a thousand words:

<?xml version="1.0" encoding="utf-8"?>
<changelog>
   <release version="1.2" versioncode="3" summary="I don't remember what this release is about... But I can assure you the update is worth it." date="2018-05-30">
        <change>Fix bugs introduced in version 1.1</change>
        <change>...</change>
    </release>
    <release version="1.1" versioncode="2" date="2018-05-30">
        <change>Fix the leaking of private information to NSA</change>
        <change>Change colors</change>
        <change>Introduce new bugs</change>
    </release>
    <release version="1.0" versioncode="1" summary="Made it !" date="2018-02-18">
        <change>First commit</change>
    </release>
</changelog>

Note that:

• the date is in ISO format: YYYY-MM-dd
• the versionName and versionCode are mandatory and should match the versions stated in build.gradle
• date and summary are optional

Display the dialog

To create and show the dialog from an activity, just call Changelog.createDialog. Don't forget to call show !

Changelog.createDialog(this).show()

listener: if you want to get notified when the dialog is dismissed, add an onDismissListener to the dialog before calling shhow.

versions: in case you want to show only the latest version's changelog, you can use the extension method getAppVersion, which returns a Pair<versionCode, versionName>.

import ch.derlin.changelog.Changelog
import ch.derlin.changelog.Changelog.getAppVersion

// ...

val version = getAppVersion()
val dialog = Changelog.createDialog(this, versionCode = version.first)
dialog.setOnDismissListener({_ -> doStuffOnDismiss() })
dialog.show()

Customisation

Change the dialog title

By default, the dialog title is @string/changelog_title. You can either override it in res/values/strings.xml or pass a string to the createDialog method.

Choose what release to show

By default, the dialog will show the whole changelog. You can specify the versionCode argument in order to display only releases with a versionCode equal or greater.

As stated above, you can use the getAppVersion extension method to get the current versionCode.

Define your own styles

The dialog is made of three parts:

• the dialog view itself (LinearLayout with a title and a RecyclerView)
• the header entries: contains a title, a date and a summary
• the cell entries: contains a bullet and a text

Everything is completely customizable using only styles !

To begin customizing the dialog, create a style inheriting from LibChangelog and set the changelogStyle attribute to refer to it instead.

In you custom changelogStyle, you can modify any style reference (see res/values/attrs.xml for a complete list). Important: when you override a style, don't forget to specify the parent (LibChangelog.STYLE).

An example is worth a thousand words. To make the screenshot on the right in the overview section, here is the code:

<style name="AppTheme" parent="Theme.AppCompat.Light.DarkActionBar">
    <!-- Apply style for changelog. 
     Just ensure that the style inherits from LibChangelog -->
    <item name="changelogStyle">@style/MyChangelog</item>
</style>

<style name="MyChangelog" parent="LibChangelog">
    <!-- here is the magic -->
    <!-- just override the title and bullet styles -->
    <item name="changelogTitleStyle">@style/MyChangelogHeader</item>
    <item name="changelogBulletStyle">@style/MyChangelogBullet</item>
</style>

<style name="MyChangelogHeader" parent="LibChangelog.HeaderTitle">
    <!-- override the changelog title: change the color and specify a background image -->
    <item name="android:background">@mipmap/parallax_changelog</item>
    <item name="android:textColor">?android:windowBackground</item>
    <item name="android:gravity">bottom</item>
    <item name="android:paddingLeft">10dp</item>
    <item name="android:paddingBottom">20dp</item>
</style>

<style name="MyChangelogBullet" parent="LibChangelog.CellBullet">
    <!-- change the bullets to use some other drawable resource
     add margin to make it better looking -->
    <item name="android:background">@drawable/logo</item>
    <item name="android:layout_marginEnd">10dp</item>
</style>

Done !

Acknowledgments

This library has been motivated by the following project (from whom I reused the xml structure):

• Inscription by Martin van Zuilekom

© Copyright 2018 Lucy Linder