From 0d9a4cc8a4b8ed5c2416c733cc6c8dc2335b7b7d Mon Sep 17 00:00:00 2001 From: Jonathan Diehl <1334574+jdiehl@users.noreply.github.com> Date: Mon, 31 Aug 2026 13:07:11 +0200 Subject: [PATCH 1/5] Add guidance on feature rollouts and Mendix version upgrades to OTA updates doc --- .../overtheair-updates.md | 23 +++++++++++++++++++ .../overtheair-updates.md | 23 +++++++++++++++++++ .../overtheair-updates.md | 23 +++++++++++++++++++ 3 files changed, 69 insertions(+) diff --git a/content/en/docs/refguide/mobile/distributing-mobile-apps/overtheair-updates.md b/content/en/docs/refguide/mobile/distributing-mobile-apps/overtheair-updates.md index 072cac2828c..caf2e557ac8 100644 --- a/content/en/docs/refguide/mobile/distributing-mobile-apps/overtheair-updates.md +++ b/content/en/docs/refguide/mobile/distributing-mobile-apps/overtheair-updates.md @@ -115,3 +115,26 @@ To release a new version OTA, follow these steps: 1. Deploy your new app to the cloud On the next restart of the application, the new OTA update will be downloaded and used. + +## Rolling Out Features That Span an App Store Release {#rolling-out-features} + +Updating a native app can take several days because Apple must review each app store release. During this time, both the old and the new version of the app must keep working. + +Use the following steps to release a feature that needs a full app store release, without breaking the app for users who have not updated yet. + +1. Build a new version of your app that includes the feature. Keep the feature disabled so users cannot use it yet. +1. Deploy this version with an OTA update. +1. Wait until all users have received the OTA update. +1. Build a new version of the app that enables the feature. Publish this version through a new app store release. Do not use OTA for this step. Wait for Apple to approve the release. + +The app store release only changes the setting that enables the feature. This means the old and the new version of the app behave the same way while the release is waiting for approval. Both versions continue to work until the app store release is approved. + +## Upgrading the Mendix Version {#upgrading-mendix-version} + +Keep Mendix version upgrades separate from new feature work. Combining them makes it harder to tell whether a problem comes from the version upgrade or from a new feature. + +When you upgrade the Mendix version, keep changes to your model as small as possible. Do not change data or the interface of microflows that your native app depends on. + +A Mendix version upgrade is backwards compatible as long as the model stays compatible with the previous native client. This means the old client and the new client can both connect to the upgraded runtime and continue to work correctly. + +Because both clients continue to work, you can release the new native client through a normal app store release. Users do not need to receive the update through OTA. Some users keep the old client and some users get the new client, and both work with the upgraded Mendix runtime until every user has updated. diff --git a/content/en/docs/refguide10/mobile/distributing-mobile-apps/overtheair-updates.md b/content/en/docs/refguide10/mobile/distributing-mobile-apps/overtheair-updates.md index df11ac07d43..4e4c4c9b9c0 100644 --- a/content/en/docs/refguide10/mobile/distributing-mobile-apps/overtheair-updates.md +++ b/content/en/docs/refguide10/mobile/distributing-mobile-apps/overtheair-updates.md @@ -115,3 +115,26 @@ To release a new version OTA, follow these steps: 1. Deploy your new app to the cloud On the next restart of the application, the new OTA update will be downloaded and used. + +## Rolling Out Features That Span an App Store Release {#rolling-out-features} + +Updating a native app can take several days because Apple must review each app store release. During this time, both the old and the new version of the app must keep working. + +Use the following steps to release a feature that needs a full app store release, without breaking the app for users who have not updated yet. + +1. Build a new version of your app that includes the feature. Keep the feature disabled so users cannot use it yet. +1. Deploy this version with an OTA update. +1. Wait until all users have received the OTA update. +1. Build a new version of the app that enables the feature. Publish this version through a new app store release. Do not use OTA for this step. Wait for Apple to approve the release. + +The app store release only changes the setting that enables the feature. This means the old and the new version of the app behave the same way while the release is waiting for approval. Both versions continue to work until the app store release is approved. + +## Upgrading the Mendix Version {#upgrading-mendix-version} + +Keep Mendix version upgrades separate from new feature work. Combining them makes it harder to tell whether a problem comes from the version upgrade or from a new feature. + +When you upgrade the Mendix version, keep changes to your model as small as possible. Do not change data or the interface of microflows that your native app depends on. + +A Mendix version upgrade is backwards compatible as long as the model stays compatible with the previous native client. This means the old client and the new client can both connect to the upgraded runtime and continue to work correctly. + +Because both clients continue to work, you can release the new native client through a normal app store release. Users do not need to receive the update through OTA. Some users keep the old client and some users get the new client, and both work with the upgraded Mendix runtime until every user has updated. diff --git a/content/en/docs/refguide9/mobile/distributing-mobile-apps/overtheair-updates.md b/content/en/docs/refguide9/mobile/distributing-mobile-apps/overtheair-updates.md index 3496057707b..e30cc6b63e0 100644 --- a/content/en/docs/refguide9/mobile/distributing-mobile-apps/overtheair-updates.md +++ b/content/en/docs/refguide9/mobile/distributing-mobile-apps/overtheair-updates.md @@ -114,3 +114,26 @@ To release a new version OTA, follow these steps: 1. Deploy your new app to the cloud On the next restart of the application, the new OTA update will be downloaded and used. + +## Rolling Out Features That Span an App Store Release {#rolling-out-features} + +Updating a native app can take several days because Apple must review each app store release. During this time, both the old and the new version of the app must keep working. + +Use the following steps to release a feature that needs a full app store release, without breaking the app for users who have not updated yet. + +1. Build a new version of your app that includes the feature. Keep the feature disabled so users cannot use it yet. +1. Deploy this version with an OTA update. +1. Wait until all users have received the OTA update. +1. Build a new version of the app that enables the feature. Publish this version through a new app store release. Do not use OTA for this step. Wait for Apple to approve the release. + +The app store release only changes the setting that enables the feature. This means the old and the new version of the app behave the same way while the release is waiting for approval. Both versions continue to work until the app store release is approved. + +## Upgrading the Mendix Version {#upgrading-mendix-version} + +Keep Mendix version upgrades separate from new feature work. Combining them makes it harder to tell whether a problem comes from the version upgrade or from a new feature. + +When you upgrade the Mendix version, keep changes to your model as small as possible. Do not change data or the interface of microflows that your native app depends on. + +A Mendix version upgrade is backwards compatible as long as the model stays compatible with the previous native client. This means the old client and the new client can both connect to the upgraded runtime and continue to work correctly. + +Because both clients continue to work, you can release the new native client through a normal app store release. Users do not need to receive the update through OTA. Some users keep the old client and some users get the new client, and both work with the upgraded Mendix runtime until every user has updated. From e7f981b0cbd2de52aff0c800f7d91233bc8e86a9 Mon Sep 17 00:00:00 2001 From: Jonathan Diehl <1334574+jdiehl@users.noreply.github.com> Date: Mon, 31 Aug 2026 13:26:32 +0200 Subject: [PATCH 2/5] Revise OTA rollout guidance: add constant-based feature toggling, clarify OTA vs version upgrade limitations, reorder sections --- .../overtheair-updates.md | 51 ++++++++++--------- .../overtheair-updates.md | 51 ++++++++++--------- .../overtheair-updates.md | 51 ++++++++++--------- 3 files changed, 84 insertions(+), 69 deletions(-) diff --git a/content/en/docs/refguide/mobile/distributing-mobile-apps/overtheair-updates.md b/content/en/docs/refguide/mobile/distributing-mobile-apps/overtheair-updates.md index caf2e557ac8..35257944487 100644 --- a/content/en/docs/refguide/mobile/distributing-mobile-apps/overtheair-updates.md +++ b/content/en/docs/refguide/mobile/distributing-mobile-apps/overtheair-updates.md @@ -81,6 +81,34 @@ If you have made any changes directly to your iOS or Android app, you will have * The splash screen has been changed * The native template was updated (NT patch updates also require a full release) +## Rolling Out Features That Span an App Store Release {#rolling-out-features} + +Updating a native app can take several days because Apple must review each app store release. During this time, both the old and the new version of the app must keep working. + +You can use a nanoflow decision or a conditional visibility setting to hide a new feature from users. A good way to control this is with a constant that is exposed to the client. You can turn the feature on or off by setting the constant to a different value per environment, or by changing its default value in a later deployment. + +Use OTA updates to make all the technical changes for the feature while the feature stays hidden from users. The app store release then only changes the value of the constant that enables the feature. Because this is a small change, the app store release does not require any other changes to the model. This keeps the old and the new version of the app compatible with each other. + +Use the following steps to release a feature that needs a full app store release, without breaking the app for users who have not updated yet. + +1. Build a new version of your app that includes the feature. Use a nanoflow decision or conditional visibility, controlled by a constant, to keep the feature disabled. +1. Deploy this version with an OTA update. +1. Wait until all users have received the OTA update. +1. Build a new version of the app that changes the constant to enable the feature. Publish this version through a new app store release. Do not use OTA for this step, because the feature that requires a full release cannot be enabled through OTA alone. Wait for Apple to approve the release. + +Because only the constant changes, the old and the new version of the app behave the same way while the release is waiting for approval. Both versions continue to work until the app store release is approved. + +## Upgrading the Mendix Version {#upgrading-mendix-version} + +Keep Mendix version upgrades separate from new feature work. Combining them makes it harder to tell whether a problem comes from the version upgrade or from a new feature. + +When you upgrade the Mendix version, keep changes to your model as small as possible. Do not change data, and do not change the parameters or return type of microflows that your native app depends on. For more information on keeping your model compatible, see [Best Practices](/refguide/mobile/building-efficient-mobile-apps/offlinefirst-data/best-practices/). + +A Mendix version upgrade is backwards compatible as long as the model stays compatible with the previous native client, and as long as you do not change the Native Template, native modules, or other elements that require a full release. When these conditions are met, the old client and the new client can both connect to the upgraded runtime and continue to work correctly. + +Because both clients continue to work, you can release the new native client through a normal app store release. You cannot use OTA to update the Mendix version itself, because OTA updates do not support version changes. Some users keep the old client and some users get the new client, and both work with the upgraded Mendix runtime until every user has updated. + + ## Enabling and Building an App with Mendix OTA Updates Enabled {#build-with-ota-support} By default OTA updates are disabled for your Native Mobile Profile. To enable them, do the following: @@ -115,26 +143,3 @@ To release a new version OTA, follow these steps: 1. Deploy your new app to the cloud On the next restart of the application, the new OTA update will be downloaded and used. - -## Rolling Out Features That Span an App Store Release {#rolling-out-features} - -Updating a native app can take several days because Apple must review each app store release. During this time, both the old and the new version of the app must keep working. - -Use the following steps to release a feature that needs a full app store release, without breaking the app for users who have not updated yet. - -1. Build a new version of your app that includes the feature. Keep the feature disabled so users cannot use it yet. -1. Deploy this version with an OTA update. -1. Wait until all users have received the OTA update. -1. Build a new version of the app that enables the feature. Publish this version through a new app store release. Do not use OTA for this step. Wait for Apple to approve the release. - -The app store release only changes the setting that enables the feature. This means the old and the new version of the app behave the same way while the release is waiting for approval. Both versions continue to work until the app store release is approved. - -## Upgrading the Mendix Version {#upgrading-mendix-version} - -Keep Mendix version upgrades separate from new feature work. Combining them makes it harder to tell whether a problem comes from the version upgrade or from a new feature. - -When you upgrade the Mendix version, keep changes to your model as small as possible. Do not change data or the interface of microflows that your native app depends on. - -A Mendix version upgrade is backwards compatible as long as the model stays compatible with the previous native client. This means the old client and the new client can both connect to the upgraded runtime and continue to work correctly. - -Because both clients continue to work, you can release the new native client through a normal app store release. Users do not need to receive the update through OTA. Some users keep the old client and some users get the new client, and both work with the upgraded Mendix runtime until every user has updated. diff --git a/content/en/docs/refguide10/mobile/distributing-mobile-apps/overtheair-updates.md b/content/en/docs/refguide10/mobile/distributing-mobile-apps/overtheair-updates.md index 4e4c4c9b9c0..30eeec2dc2d 100644 --- a/content/en/docs/refguide10/mobile/distributing-mobile-apps/overtheair-updates.md +++ b/content/en/docs/refguide10/mobile/distributing-mobile-apps/overtheair-updates.md @@ -81,6 +81,34 @@ If you have made any changes directly to your iOS or Android app, you will have * The splash screen has been changed * The native template was updated (NT patch updates also require a full release) +## Rolling Out Features That Span an App Store Release {#rolling-out-features} + +Updating a native app can take several days because Apple must review each app store release. During this time, both the old and the new version of the app must keep working. + +You can use a nanoflow decision or a conditional visibility setting to hide a new feature from users. A good way to control this is with a constant that is exposed to the client. You can turn the feature on or off by setting the constant to a different value per environment, or by changing its default value in a later deployment. + +Use OTA updates to make all the technical changes for the feature while the feature stays hidden from users. The app store release then only changes the value of the constant that enables the feature. Because this is a small change, the app store release does not require any other changes to the model. This keeps the old and the new version of the app compatible with each other. + +Use the following steps to release a feature that needs a full app store release, without breaking the app for users who have not updated yet. + +1. Build a new version of your app that includes the feature. Use a nanoflow decision or conditional visibility, controlled by a constant, to keep the feature disabled. +1. Deploy this version with an OTA update. +1. Wait until all users have received the OTA update. +1. Build a new version of the app that changes the constant to enable the feature. Publish this version through a new app store release. Do not use OTA for this step, because the feature that requires a full release cannot be enabled through OTA alone. Wait for Apple to approve the release. + +Because only the constant changes, the old and the new version of the app behave the same way while the release is waiting for approval. Both versions continue to work until the app store release is approved. + +## Upgrading the Mendix Version {#upgrading-mendix-version} + +Keep Mendix version upgrades separate from new feature work. Combining them makes it harder to tell whether a problem comes from the version upgrade or from a new feature. + +When you upgrade the Mendix version, keep changes to your model as small as possible. Do not change data, and do not change the parameters or return type of microflows that your native app depends on. For more information on keeping your model compatible, see [Best Practices](/refguide/mobile/building-efficient-mobile-apps/offlinefirst-data/best-practices/). + +A Mendix version upgrade is backwards compatible as long as the model stays compatible with the previous native client, and as long as you do not change the Native Template, native modules, or other elements that require a full release. When these conditions are met, the old client and the new client can both connect to the upgraded runtime and continue to work correctly. + +Because both clients continue to work, you can release the new native client through a normal app store release. You cannot use OTA to update the Mendix version itself, because OTA updates do not support version changes. Some users keep the old client and some users get the new client, and both work with the upgraded Mendix runtime until every user has updated. + + ## Enabling and Building an App with Mendix OTA Updates Enabled {#build-with-ota-support} By default OTA updates are disabled for your Native Mobile Profile. To enable them, do the following: @@ -115,26 +143,3 @@ To release a new version OTA, follow these steps: 1. Deploy your new app to the cloud On the next restart of the application, the new OTA update will be downloaded and used. - -## Rolling Out Features That Span an App Store Release {#rolling-out-features} - -Updating a native app can take several days because Apple must review each app store release. During this time, both the old and the new version of the app must keep working. - -Use the following steps to release a feature that needs a full app store release, without breaking the app for users who have not updated yet. - -1. Build a new version of your app that includes the feature. Keep the feature disabled so users cannot use it yet. -1. Deploy this version with an OTA update. -1. Wait until all users have received the OTA update. -1. Build a new version of the app that enables the feature. Publish this version through a new app store release. Do not use OTA for this step. Wait for Apple to approve the release. - -The app store release only changes the setting that enables the feature. This means the old and the new version of the app behave the same way while the release is waiting for approval. Both versions continue to work until the app store release is approved. - -## Upgrading the Mendix Version {#upgrading-mendix-version} - -Keep Mendix version upgrades separate from new feature work. Combining them makes it harder to tell whether a problem comes from the version upgrade or from a new feature. - -When you upgrade the Mendix version, keep changes to your model as small as possible. Do not change data or the interface of microflows that your native app depends on. - -A Mendix version upgrade is backwards compatible as long as the model stays compatible with the previous native client. This means the old client and the new client can both connect to the upgraded runtime and continue to work correctly. - -Because both clients continue to work, you can release the new native client through a normal app store release. Users do not need to receive the update through OTA. Some users keep the old client and some users get the new client, and both work with the upgraded Mendix runtime until every user has updated. diff --git a/content/en/docs/refguide9/mobile/distributing-mobile-apps/overtheair-updates.md b/content/en/docs/refguide9/mobile/distributing-mobile-apps/overtheair-updates.md index e30cc6b63e0..65756deddd9 100644 --- a/content/en/docs/refguide9/mobile/distributing-mobile-apps/overtheair-updates.md +++ b/content/en/docs/refguide9/mobile/distributing-mobile-apps/overtheair-updates.md @@ -80,6 +80,34 @@ If you have made any changes directly to your iOS or Android app, you will have * The app's launcher icons have been changed * The splash screen has been changed +## Rolling Out Features That Span an App Store Release {#rolling-out-features} + +Updating a native app can take several days because Apple must review each app store release. During this time, both the old and the new version of the app must keep working. + +You can use a nanoflow decision or a conditional visibility setting to hide a new feature from users. A good way to control this is with a constant that is exposed to the client. You can turn the feature on or off by setting the constant to a different value per environment, or by changing its default value in a later deployment. + +Use OTA updates to make all the technical changes for the feature while the feature stays hidden from users. The app store release then only changes the value of the constant that enables the feature. Because this is a small change, the app store release does not require any other changes to the model. This keeps the old and the new version of the app compatible with each other. + +Use the following steps to release a feature that needs a full app store release, without breaking the app for users who have not updated yet. + +1. Build a new version of your app that includes the feature. Use a nanoflow decision or conditional visibility, controlled by a constant, to keep the feature disabled. +1. Deploy this version with an OTA update. +1. Wait until all users have received the OTA update. +1. Build a new version of the app that changes the constant to enable the feature. Publish this version through a new app store release. Do not use OTA for this step, because the feature that requires a full release cannot be enabled through OTA alone. Wait for Apple to approve the release. + +Because only the constant changes, the old and the new version of the app behave the same way while the release is waiting for approval. Both versions continue to work until the app store release is approved. + +## Upgrading the Mendix Version {#upgrading-mendix-version} + +Keep Mendix version upgrades separate from new feature work. Combining them makes it harder to tell whether a problem comes from the version upgrade or from a new feature. + +When you upgrade the Mendix version, keep changes to your model as small as possible. Do not change data, and do not change the parameters or return type of microflows that your native app depends on. For more information on keeping your model compatible, see [Best Practices](/refguide/mobile/building-efficient-mobile-apps/offlinefirst-data/best-practices/). + +A Mendix version upgrade is backwards compatible as long as the model stays compatible with the previous native client, and as long as you do not change the Native Template, native modules, or other elements that require a full release. When these conditions are met, the old client and the new client can both connect to the upgraded runtime and continue to work correctly. + +Because both clients continue to work, you can release the new native client through a normal app store release. You cannot use OTA to update the Mendix version itself, because OTA updates do not support version changes. Some users keep the old client and some users get the new client, and both work with the upgraded Mendix runtime until every user has updated. + + ## Enabling and Building an App with Mendix OTA Updates Enabled {#build-with-ota-support} By default OTA updates are disabled for your Native Mobile Profile. To enable them, do the following: @@ -114,26 +142,3 @@ To release a new version OTA, follow these steps: 1. Deploy your new app to the cloud On the next restart of the application, the new OTA update will be downloaded and used. - -## Rolling Out Features That Span an App Store Release {#rolling-out-features} - -Updating a native app can take several days because Apple must review each app store release. During this time, both the old and the new version of the app must keep working. - -Use the following steps to release a feature that needs a full app store release, without breaking the app for users who have not updated yet. - -1. Build a new version of your app that includes the feature. Keep the feature disabled so users cannot use it yet. -1. Deploy this version with an OTA update. -1. Wait until all users have received the OTA update. -1. Build a new version of the app that enables the feature. Publish this version through a new app store release. Do not use OTA for this step. Wait for Apple to approve the release. - -The app store release only changes the setting that enables the feature. This means the old and the new version of the app behave the same way while the release is waiting for approval. Both versions continue to work until the app store release is approved. - -## Upgrading the Mendix Version {#upgrading-mendix-version} - -Keep Mendix version upgrades separate from new feature work. Combining them makes it harder to tell whether a problem comes from the version upgrade or from a new feature. - -When you upgrade the Mendix version, keep changes to your model as small as possible. Do not change data or the interface of microflows that your native app depends on. - -A Mendix version upgrade is backwards compatible as long as the model stays compatible with the previous native client. This means the old client and the new client can both connect to the upgraded runtime and continue to work correctly. - -Because both clients continue to work, you can release the new native client through a normal app store release. Users do not need to receive the update through OTA. Some users keep the old client and some users get the new client, and both work with the upgraded Mendix runtime until every user has updated. From 66b89a393ebd336b155d65a893ef75fdb83aa9aa Mon Sep 17 00:00:00 2001 From: Jonathan Diehl <1334574+jdiehl@users.noreply.github.com> Date: Mon, 31 Aug 2026 13:33:01 +0200 Subject: [PATCH 3/5] Clarify feature rollout section: introduce two-step solution before mechanism --- .../mobile/distributing-mobile-apps/overtheair-updates.md | 4 ++-- .../mobile/distributing-mobile-apps/overtheair-updates.md | 4 ++-- .../mobile/distributing-mobile-apps/overtheair-updates.md | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/content/en/docs/refguide/mobile/distributing-mobile-apps/overtheair-updates.md b/content/en/docs/refguide/mobile/distributing-mobile-apps/overtheair-updates.md index 35257944487..9cb3721e0bf 100644 --- a/content/en/docs/refguide/mobile/distributing-mobile-apps/overtheair-updates.md +++ b/content/en/docs/refguide/mobile/distributing-mobile-apps/overtheair-updates.md @@ -85,9 +85,9 @@ If you have made any changes directly to your iOS or Android app, you will have Updating a native app can take several days because Apple must review each app store release. During this time, both the old and the new version of the app must keep working. -You can use a nanoflow decision or a conditional visibility setting to hide a new feature from users. A good way to control this is with a constant that is exposed to the client. You can turn the feature on or off by setting the constant to a different value per environment, or by changing its default value in a later deployment. +To solve this, split the release of the feature into two steps. First, use an OTA update to build and prepare the feature while it stays hidden from users. Then, use a small app store release to turn the feature on. Because the app store release only changes a small setting instead of the feature itself, it does not require any other changes to the model. This keeps the old and the new version of the app compatible with each other while the release is under review. -Use OTA updates to make all the technical changes for the feature while the feature stays hidden from users. The app store release then only changes the value of the constant that enables the feature. Because this is a small change, the app store release does not require any other changes to the model. This keeps the old and the new version of the app compatible with each other. +You can hide a feature with a nanoflow decision or a conditional visibility setting. A good way to control this is with a constant that is exposed to the client. You can turn the feature on or off by setting the constant to a different value per environment, or by changing its default value in a later deployment. Use the following steps to release a feature that needs a full app store release, without breaking the app for users who have not updated yet. diff --git a/content/en/docs/refguide10/mobile/distributing-mobile-apps/overtheair-updates.md b/content/en/docs/refguide10/mobile/distributing-mobile-apps/overtheair-updates.md index 30eeec2dc2d..0dc7d8a6cc2 100644 --- a/content/en/docs/refguide10/mobile/distributing-mobile-apps/overtheair-updates.md +++ b/content/en/docs/refguide10/mobile/distributing-mobile-apps/overtheair-updates.md @@ -85,9 +85,9 @@ If you have made any changes directly to your iOS or Android app, you will have Updating a native app can take several days because Apple must review each app store release. During this time, both the old and the new version of the app must keep working. -You can use a nanoflow decision or a conditional visibility setting to hide a new feature from users. A good way to control this is with a constant that is exposed to the client. You can turn the feature on or off by setting the constant to a different value per environment, or by changing its default value in a later deployment. +To solve this, split the release of the feature into two steps. First, use an OTA update to build and prepare the feature while it stays hidden from users. Then, use a small app store release to turn the feature on. Because the app store release only changes a small setting instead of the feature itself, it does not require any other changes to the model. This keeps the old and the new version of the app compatible with each other while the release is under review. -Use OTA updates to make all the technical changes for the feature while the feature stays hidden from users. The app store release then only changes the value of the constant that enables the feature. Because this is a small change, the app store release does not require any other changes to the model. This keeps the old and the new version of the app compatible with each other. +You can hide a feature with a nanoflow decision or a conditional visibility setting. A good way to control this is with a constant that is exposed to the client. You can turn the feature on or off by setting the constant to a different value per environment, or by changing its default value in a later deployment. Use the following steps to release a feature that needs a full app store release, without breaking the app for users who have not updated yet. diff --git a/content/en/docs/refguide9/mobile/distributing-mobile-apps/overtheair-updates.md b/content/en/docs/refguide9/mobile/distributing-mobile-apps/overtheair-updates.md index 65756deddd9..fd24411c079 100644 --- a/content/en/docs/refguide9/mobile/distributing-mobile-apps/overtheair-updates.md +++ b/content/en/docs/refguide9/mobile/distributing-mobile-apps/overtheair-updates.md @@ -84,9 +84,9 @@ If you have made any changes directly to your iOS or Android app, you will have Updating a native app can take several days because Apple must review each app store release. During this time, both the old and the new version of the app must keep working. -You can use a nanoflow decision or a conditional visibility setting to hide a new feature from users. A good way to control this is with a constant that is exposed to the client. You can turn the feature on or off by setting the constant to a different value per environment, or by changing its default value in a later deployment. +To solve this, split the release of the feature into two steps. First, use an OTA update to build and prepare the feature while it stays hidden from users. Then, use a small app store release to turn the feature on. Because the app store release only changes a small setting instead of the feature itself, it does not require any other changes to the model. This keeps the old and the new version of the app compatible with each other while the release is under review. -Use OTA updates to make all the technical changes for the feature while the feature stays hidden from users. The app store release then only changes the value of the constant that enables the feature. Because this is a small change, the app store release does not require any other changes to the model. This keeps the old and the new version of the app compatible with each other. +You can hide a feature with a nanoflow decision or a conditional visibility setting. A good way to control this is with a constant that is exposed to the client. You can turn the feature on or off by setting the constant to a different value per environment, or by changing its default value in a later deployment. Use the following steps to release a feature that needs a full app store release, without breaking the app for users who have not updated yet. From 28d85217238405a0107e3c588133edc6879c76e9 Mon Sep 17 00:00:00 2001 From: Jonathan Diehl <1334574+jdiehl@users.noreply.github.com> Date: Mon, 31 Aug 2026 13:34:53 +0200 Subject: [PATCH 4/5] Remove unnecessary wait-for-OTA step in feature rollout guidance --- .../mobile/distributing-mobile-apps/overtheair-updates.md | 1 - .../mobile/distributing-mobile-apps/overtheair-updates.md | 1 - .../mobile/distributing-mobile-apps/overtheair-updates.md | 1 - 3 files changed, 3 deletions(-) diff --git a/content/en/docs/refguide/mobile/distributing-mobile-apps/overtheair-updates.md b/content/en/docs/refguide/mobile/distributing-mobile-apps/overtheair-updates.md index 9cb3721e0bf..09dc743b2cf 100644 --- a/content/en/docs/refguide/mobile/distributing-mobile-apps/overtheair-updates.md +++ b/content/en/docs/refguide/mobile/distributing-mobile-apps/overtheair-updates.md @@ -93,7 +93,6 @@ Use the following steps to release a feature that needs a full app store release 1. Build a new version of your app that includes the feature. Use a nanoflow decision or conditional visibility, controlled by a constant, to keep the feature disabled. 1. Deploy this version with an OTA update. -1. Wait until all users have received the OTA update. 1. Build a new version of the app that changes the constant to enable the feature. Publish this version through a new app store release. Do not use OTA for this step, because the feature that requires a full release cannot be enabled through OTA alone. Wait for Apple to approve the release. Because only the constant changes, the old and the new version of the app behave the same way while the release is waiting for approval. Both versions continue to work until the app store release is approved. diff --git a/content/en/docs/refguide10/mobile/distributing-mobile-apps/overtheair-updates.md b/content/en/docs/refguide10/mobile/distributing-mobile-apps/overtheair-updates.md index 0dc7d8a6cc2..731f6dbbe0d 100644 --- a/content/en/docs/refguide10/mobile/distributing-mobile-apps/overtheair-updates.md +++ b/content/en/docs/refguide10/mobile/distributing-mobile-apps/overtheair-updates.md @@ -93,7 +93,6 @@ Use the following steps to release a feature that needs a full app store release 1. Build a new version of your app that includes the feature. Use a nanoflow decision or conditional visibility, controlled by a constant, to keep the feature disabled. 1. Deploy this version with an OTA update. -1. Wait until all users have received the OTA update. 1. Build a new version of the app that changes the constant to enable the feature. Publish this version through a new app store release. Do not use OTA for this step, because the feature that requires a full release cannot be enabled through OTA alone. Wait for Apple to approve the release. Because only the constant changes, the old and the new version of the app behave the same way while the release is waiting for approval. Both versions continue to work until the app store release is approved. diff --git a/content/en/docs/refguide9/mobile/distributing-mobile-apps/overtheair-updates.md b/content/en/docs/refguide9/mobile/distributing-mobile-apps/overtheair-updates.md index fd24411c079..61c27cff29b 100644 --- a/content/en/docs/refguide9/mobile/distributing-mobile-apps/overtheair-updates.md +++ b/content/en/docs/refguide9/mobile/distributing-mobile-apps/overtheair-updates.md @@ -92,7 +92,6 @@ Use the following steps to release a feature that needs a full app store release 1. Build a new version of your app that includes the feature. Use a nanoflow decision or conditional visibility, controlled by a constant, to keep the feature disabled. 1. Deploy this version with an OTA update. -1. Wait until all users have received the OTA update. 1. Build a new version of the app that changes the constant to enable the feature. Publish this version through a new app store release. Do not use OTA for this step, because the feature that requires a full release cannot be enabled through OTA alone. Wait for Apple to approve the release. Because only the constant changes, the old and the new version of the app behave the same way while the release is waiting for approval. Both versions continue to work until the app store release is approved. From e4798bbbb3439a86137ef53a335175a776503c80 Mon Sep 17 00:00:00 2001 From: Jonathan Diehl <1334574+jdiehl@users.noreply.github.com> Date: Mon, 31 Aug 2026 13:35:52 +0200 Subject: [PATCH 5/5] Note that combining version upgrades with feature work can break the app for existing users --- .../mobile/distributing-mobile-apps/overtheair-updates.md | 2 +- .../mobile/distributing-mobile-apps/overtheair-updates.md | 2 +- .../mobile/distributing-mobile-apps/overtheair-updates.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/content/en/docs/refguide/mobile/distributing-mobile-apps/overtheair-updates.md b/content/en/docs/refguide/mobile/distributing-mobile-apps/overtheair-updates.md index 09dc743b2cf..dcc3f0932c0 100644 --- a/content/en/docs/refguide/mobile/distributing-mobile-apps/overtheair-updates.md +++ b/content/en/docs/refguide/mobile/distributing-mobile-apps/overtheair-updates.md @@ -99,7 +99,7 @@ Because only the constant changes, the old and the new version of the app behave ## Upgrading the Mendix Version {#upgrading-mendix-version} -Keep Mendix version upgrades separate from new feature work. Combining them makes it harder to tell whether a problem comes from the version upgrade or from a new feature. +Keep Mendix version upgrades separate from new feature work. Combining them makes it harder to tell whether a problem comes from the version upgrade or from a new feature. It can also break the app for existing users if the new feature changes the model in a way that is not compatible with the old client. When you upgrade the Mendix version, keep changes to your model as small as possible. Do not change data, and do not change the parameters or return type of microflows that your native app depends on. For more information on keeping your model compatible, see [Best Practices](/refguide/mobile/building-efficient-mobile-apps/offlinefirst-data/best-practices/). diff --git a/content/en/docs/refguide10/mobile/distributing-mobile-apps/overtheair-updates.md b/content/en/docs/refguide10/mobile/distributing-mobile-apps/overtheair-updates.md index 731f6dbbe0d..007cb665494 100644 --- a/content/en/docs/refguide10/mobile/distributing-mobile-apps/overtheair-updates.md +++ b/content/en/docs/refguide10/mobile/distributing-mobile-apps/overtheair-updates.md @@ -99,7 +99,7 @@ Because only the constant changes, the old and the new version of the app behave ## Upgrading the Mendix Version {#upgrading-mendix-version} -Keep Mendix version upgrades separate from new feature work. Combining them makes it harder to tell whether a problem comes from the version upgrade or from a new feature. +Keep Mendix version upgrades separate from new feature work. Combining them makes it harder to tell whether a problem comes from the version upgrade or from a new feature. It can also break the app for existing users if the new feature changes the model in a way that is not compatible with the old client. When you upgrade the Mendix version, keep changes to your model as small as possible. Do not change data, and do not change the parameters or return type of microflows that your native app depends on. For more information on keeping your model compatible, see [Best Practices](/refguide/mobile/building-efficient-mobile-apps/offlinefirst-data/best-practices/). diff --git a/content/en/docs/refguide9/mobile/distributing-mobile-apps/overtheair-updates.md b/content/en/docs/refguide9/mobile/distributing-mobile-apps/overtheair-updates.md index 61c27cff29b..69cfce87aea 100644 --- a/content/en/docs/refguide9/mobile/distributing-mobile-apps/overtheair-updates.md +++ b/content/en/docs/refguide9/mobile/distributing-mobile-apps/overtheair-updates.md @@ -98,7 +98,7 @@ Because only the constant changes, the old and the new version of the app behave ## Upgrading the Mendix Version {#upgrading-mendix-version} -Keep Mendix version upgrades separate from new feature work. Combining them makes it harder to tell whether a problem comes from the version upgrade or from a new feature. +Keep Mendix version upgrades separate from new feature work. Combining them makes it harder to tell whether a problem comes from the version upgrade or from a new feature. It can also break the app for existing users if the new feature changes the model in a way that is not compatible with the old client. When you upgrade the Mendix version, keep changes to your model as small as possible. Do not change data, and do not change the parameters or return type of microflows that your native app depends on. For more information on keeping your model compatible, see [Best Practices](/refguide/mobile/building-efficient-mobile-apps/offlinefirst-data/best-practices/).