Updating

After fixing bugs or adding new features you can to release an update to the Homey App Store. Read this article for useful tips and considerations.

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. 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.

Homey will never downgrade apps. If you want to undo a release, then re-submit an older build with a higher version number.

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.