Manage Application Versions
Managing different application versions can be tricky! This page provides some high-level guidance to help you manage your application versions.
Table of Contents:
View App Changes Between Versions
This feature allows you to see changes that have been made between different versions of your application. This allows you to verify the changes you have made before releasing a new version of your application, and to efficiently develop test plans for running QA, by focusing your plan on things that have changed.
Overview
View Changes button is available on Application Releases page. The View Changes page allows you to see what has changed in every menu, form and question in your application. Using the dropdown at the top of the page, you can choose any two versions to compare, and the app changes view will show you what has changed between them.
The left pane shows the first app version you have selected, or the "base" on which comparisons will be made. The right pane shows the second version you have selected.
Items that were added between the first version and the second version are highlighted in Green in the right pane and have a + next to them.
Items that were removed between the first version and the second version are highlighted in Red in the left pane and have a - next to them.
Items that have changed between the first version and the second version are highlighted in Yellow and have an arrow icon next to them.
Menu and Form Changes
Addition
Deletion
Addition, Deletion and Changes to:
Name
Comment
Display condition
Questions
Addition and Deletion of the question itself
Addition, Deletion and Changes to:
Names
Including changes to any translation
Comments
Calculations (for hidden value questions)
Display Conditions
Validation Conditions
Comments
Default Values
Options
Case property loads
Case property saves
Workflows
Seeing what has changed before making a new version or releasing a new version.
Before releasing a new version of your application to users, it is good practice to check all the changes you have made for consistency and accuracy. You can do this with the app changes view. Set the "base" version to the previous released version, and set the current build to be the version you are comparing to. This will show you all the changes you are about to release. Check to make sure all of these changes are known and have been tested.
Squashing bugs
You can narrow down which change might have introduced a bug by using the app changes view. You should first test various versions of your application to narrow the bug down to a small range of versions. Then select the last known "good" version as the "base" compare version. Select a "buggy" version to compare it with. You will see all the changes between these two versions. It is only necessary to look at these changes to find the bug, as nothing else in the app will have changed.
Efficient QA plan writing
While writing QA plans, you can narrow down the area you need to test by using the app changes view. With your knowledge of the application in general, and the changes that have been made since the last QA pass, you can decide to only test the parts of the application that have changed, instead of needing to test the whole app.
Control Application Versions During Updates
NOTE: This page discusses how to control the version of a CommCare app that is requested when conducting an app update. For an overview of app updates in CommCare, see https://dimagi.atlassian.net/wiki/x/bzPKfw.
What are my options?
By default, app updates in CommCare will retrieve the latest starred version of your app on HQ. However, there are 2 alternatives to this behavior that are available:
"Latest version" (available starting in CommCare 2.30) -- This setting will tell CommCare to retrieve the most recent build of an app, even if it is un-starred.
"Latest saved state" (available starting in CommCare 2.34) – This setting will tell CommCare to retrieve the current working state of your app, even if no build has been created for it yet.
The update target setting is configured on a per-app, per-device basis, with the goal of allowing app builders and other project admins to use one of these alternative settings, while leaving normal CommCare users on the default setting, so that they only receive starred app versions.
How can I configure my update target?
In CommCare 2.34 and above: There are 2 locations in CommCare where you can set your app's update target: either from the main Settings screen of the app (the same place where the "Enable Updating to Un-Starred Builds" setting used to be), or from the options menu of the Update screen. Screenshots of both locations can be seen below.
**IMPORTANT: In CommCare 2.36 and above – In order for the "Update Options" item to be visible in these 2 locations, you must first take the following steps:
Enable Developer Options on your device (instructions for doing so can be found at CommCare Developer Options).
Select the "Show Update Options Item" setting, and then choose "Enabled”.
From the settings screen:
From the update screen:
Managing and Prompting Application Updates in CommCare:
In the "Application Versions" section of CommCare, we offer a feature that allows you to manage and prompt updates on mobile devices. This ensures that your mobile workers are consistently using the latest builds of both CommCare and the applications developed and released on CommCareHQ.
This functionality is crucial for maintaining uniformity across your mobile workforce. By ensuring that all mobile workers are operating on the same version of the application, you can avoid discrepancies and inconsistencies in data collection that often arise when different versions are in use. When an application is updated to a newly released version, this feature guarantees that all users promptly receive and install the update, thus streamlining the workflow and improving data accuracy.
Detailed Options for Managing Application Versions
This feature contains two options, “Prompt updates to CommCare” and “Prompt updates to app”, which ensures the update management for CommCare and the mobile applications respectively.
Within this system, we provide three distinct choices available in the dropdown menu for managing updates. These options allow administrators to tailor the update process to the specific needs and policies of their organization. The choices available are:
Off: This option disables update prompts, allowing mobile workers to continue using their current version of the application without any interruptions. While this might be useful in certain scenarios where stability is prioritized over new updates, it is generally recommended to keep this setting to "On" or "Forced" to ensure that users benefit from the latest updates.
On: When this option is selected, mobile workers will receive a prompt to update their CommCare applications to the latest released version. This approach encourages users to stay up-to-date with minimal disruption to their workflow.
Forced: Selecting this option enforces a mandatory update. Mobile workers will not be able to continue using CommCare unless they are operating on the latest version. This ensures that all users are immediately on the same version, eliminating any risk of data inconsistencies due to using an older version.
By providing these options, CommCare allows administrators to have precise control over how and when updates are implemented across their mobile workforce. This flexibility ensures that the update process can be aligned with organizational policies and operational needs, thereby optimizing the efficiency and reliability of data collection activities.