# Updating

## Writing a changelog

Updating your app with some fixes or new features? Awesome! Let your users know what’s new and what has changed for them. When publishing a new version of your app a `.homeychangelog.json` file is automatically created in the root directory of your app and `homey` will ask you 'What's new?'. Here you can list all the new features, content or functional changes since the previous live version.

What do your users want to see?

* Only name the changes that are relevant to your users:
  * **Added** for new features.
  * **Changed** for changes in existing functionality.
  * **Deprecated** for soon-to-be removed features.
  * **Removed** for (temporary) removed features.
  * **Fixed** for any bug fixes.
  * **Security** in case of vulnerabilities.
* In case you've made some changes to for example your readme based on our feedback there is no need to mention this in your changelog. Only changes that have been made since the previous live version are important.

## App versions

The version of your app should be indicated using [semver](https://semver.org). This version indication is used to determine whether an app should be updated for users. If there is a higher version available for a user, it will be automatically installed. Therefore, make sure that the app you are submitting has a version that is *higher* than the current *Live* version.

{% hint style="warning" %}
Homey will never downgrade apps. If you want to undo a release, then re-submit an older build with a higher version number.
{% endhint %}

## Update your Live app while having a newer version in Test

Sometimes it may be needed to patch the *Live* version of your app while also having a *Test* version of your app published. This is possible by submitting a patch with a version *lower* than your current *Test* version. When an app update with a version lower than the current *Test* version is created (e.g. v2.0.1), it will replace the current *Test* version (e.g. v3.0.0). Therefore, if you have published your patch to *Live* and you want to make your previous *Test* version available again, you must release the *Test* version with a higher version number than the highest version ever released (e.g. v3.0.1).

The users of the *Live* version will automaticallly update to the new patch version (e.g. v2.0.1), and the users of the *Test* version will automatically update to the new *Test* version (e.g. v3.0.1). If you do not upload a new *Test* version, users using this *Test* version (e.g. v3.0.0) will not automatically downgrade, but stay on their currently installed version (e.g. v3.0.0).

* Let's say you have version 1.0.0 as *Live* version and version 2.0.0 as *Test* version. Version 1.0.0 contains a critical bug that must be fixed immediately.
* First you submit a fix for the bug in version 1.0.1.
* Version 1.0.1 will become the *Test* version, which you can test. The previous *Test* version 2.0.0 will become unavailable, but existing users of 2.0.0 can keep using it.
* If the bug is fixed, you can set version 1.0.1 to *Live*. Users of version 1.0.0 will automatically update to this version. Existing users of 2.0.0 will not downgrade.
* Now the previous version 2.0.0 can be set back to *Test*, but since the version 2.0.0 is already taken by a previous build it must be resubmitted as version 2.0.1.