feat(#1949): Preparing for CHT 5.0, remove existing upgrades dir

content/en/building/guides/_index.md

@@ -6,4 +6,5 @@ description: >
   Focused CHT app development guides
 aliases:
    - /apps/guides/
+   - /building/guides/updates/
 ---

content/en/building/guides/updates/collect-forms-update.md → content/en/building/guides/collect-forms-update.md

@@ -7,6 +7,7 @@ description: >
 
 aliases:
    - /apps/guides/updates/collect-forms-update
+   - /building/guides/updates/collect-forms-update/
 ---
 
 To do over the air Medic Collect form updates via HTTP rather than sending APKs which have a long manual install process, follow the steps below:

content/en/building/guides/updates/feature-flags.md → content/en/building/guides/feature-flags.md

@@ -12,6 +12,7 @@ relatedContent: >
 
 aliases:
    - /apps/guides/updates/feature-flags
+   - /building/guides/updates/feature-flags/
 ---
 
 Some CHT Core features can be enabled for specific users only. This can be particularly helpful for features that require training. The updated or "new" version will generally be the system default, but users can be configured to see the "old" version. If you do nothing when you upgrade, users will automatically start seeing the new version.

content/en/building/login.md

@@ -38,7 +38,7 @@ To enhance the security of CHT applications, users logging in for the first time
 {{< figure src="password-change.png" link="password-change.png" class="col-12 col-lg-12" >}}
 
 This feature is enabled by default because it encourages best practices. However, only new users will be prompted to go through this flow or those users whose passwords have been reset by the system administration.
-Projects can disable this feature by enabling the `can_skip_password_change` [permission]( {{< ref "building/reference/app-settings/user-permissions#system-defined-permissions" >}}). This permission is a [feature flag]({{< relref "building/guides/updates/feature-flags" >}}) and will be removed in a later CHT release.
+Projects can disable this feature by enabling the `can_skip_password_change` [permission]( {{< ref "building/reference/app-settings/user-permissions#system-defined-permissions" >}}). This permission is a [feature flag]({{< relref "building/guides/feature-flags" >}}) and will be removed in a later CHT release.
 
 Subsequent logins won’t require a password change – if the app closes before changing the password, the user will be prompted again when they reopen it. If a user is unable to update their password, they won’t be able to access the app.
 

content/en/building/reference/app-settings/user-permissions.md

@@ -67,8 +67,8 @@ Permissions can be assigned to user roles either directly in `base_settings.json
 | `can_view_unallocated_data_records` | Allows viewing reports that have no associated contact                                                                                                                                                                                                                                                                                                                                        |
 | `can_view_users` | Allows viewing all user accounts                                                                                                                                                                                                                                                                                                                                                              |
 | `can_write_wealth_quintiles` | Allows updating contacts with wealth quintile information                                                                                                                                                                                                                                                                                                                                     |
-| `can_view_old_filter_and_search` | Allows users to see the old filter and search in Reports Tab and Contact Tab which is considered deprecated and will be completely removed in a future release. Admin user will always see the new redesigned filter. See [Feature Flags]({{< ref "building/guides/updates/feature-flags" >}}) for more info.                                                                                 |
-| `can_view_old_action_bar` | Allows users to see the old action bar in Message Tab, Reports Tab and Contact Tab which is considered deprecated and will be completely removed in a future release. The More Options menu will be hidden when this permission is enabled. The Admin user will always see the new More Options menu. See [Feature Flags]({{< ref "building/guides/updates/feature-flags" >}}) for more info. |
+| `can_view_old_filter_and_search` | Allows users to see the old filter and search in Reports Tab and Contact Tab which is considered deprecated and will be completely removed in a future release. Admin user will always see the new redesigned filter. See [Feature Flags]({{< ref "building/guides/feature-flags" >}}) for more info.                                                                                 |
+| `can_view_old_action_bar` | Allows users to see the old action bar in Message Tab, Reports Tab and Contact Tab which is considered deprecated and will be completely removed in a future release. The More Options menu will be hidden when this permission is enabled. The Admin user will always see the new More Options menu. See [Feature Flags]({{< ref "building/guides/feature-flags" >}}) for more info. |
 | `can_default_facility_filter` | Defaults the Place Filter in Reports tab to the user's associated facility. The user should have a contact associated that belongs to a facility. This feature is not available for Admin and Offline type of users. Use with caution, online users that can access thousands of reports can experience slow performance especially where the network is slow. Added in 4.3.                  |
 |`can_have_multiple_places`| Allows users to be assigned more than one `facility_id`. Helps support health systems where offline Supervisors manage CHWs from different geographical areas. Each `facility_id` must be at the same level in the hierarchy. Added in 4.9.0                                                                                                                                                  |
 |`can_skip_password_change`| Turns off the password change prompt for users logging in for the first time or who have had their password reset. Added in 4.17.0                                                                                                                                                                                                                                                            |

content/en/building/reports/reports-overview.md

@@ -46,7 +46,7 @@ Using the search box, you can search for reports by patient name, phone number,
 <br clear="all">
 
 > [!NOTE]
-> A new user experience for Filter and Search was introduced in v3.17. The previous version can be re-enabled for users by adding the [permission]({{< ref "building/reference/app-settings/user-permissions" >}}) `can_view_old_filter_and_search` to the user's role; however, the old version should be considered deprecated and will be completely removed in a future release. See [Feature Flags]({{< ref "building/guides/updates/feature-flags" >}}) documentation for more info
+> A new user experience for Filter and Search was introduced in v3.17. The previous version can be re-enabled for users by adding the [permission]({{< ref "building/reference/app-settings/user-permissions" >}}) `can_view_old_filter_and_search` to the user's role; however, the old version should be considered deprecated and will be completely removed in a future release. See [Feature Flags]({{< ref "building/guides/feature-flags" >}}) documentation for more info
 
 <br clear="all">
 

content/en/hosting/cht/_index.md

@@ -4,7 +4,7 @@ weight: 6
 description: >
     Guides for hosting CHT applications
 relatedContent: >
-    building/guides/updates/preparing-for-4/
+    hosting/cht/migration/preparing-for-4/
 aliases:
   - /apps/guides/hosting/4.x
   - /hosting/4.x/

content/en/building/guides/updates/preparing-for-4.md → content/en/hosting/cht/migration/preparing-for-4.md

@@ -1,11 +1,12 @@
 ---
 title: "Preparing to upgrade to CHT 4.0"
-linkTitle: "Preparing to upgrade to CHT 4.0"
+linkTitle: "Preparing for 4.0"
 weight:
 aliases:
   - /apps/guides/hosting/3.x/preparing-for-4.0
   - /apps/guides/updates/preparing-for-4.md
   - /apps/guides/updates/preparing-for-4/
+  - /building/guides/updates/preparing-for-4/
 description: >
   Steps to ensure your CHT App will run smoothly on CHT 4.0 and later
 

content/en/hosting/cht/migration/preparing-for-5.md

@@ -0,0 +1,107 @@
+---
+title: "Preparing to upgrade to CHT 5.0"
+linkTitle: "Preparing for 5.0"
+weight: 
+description: >
+  Steps to ensure your CHT App will run smoothly on CHT 5.0 and later
+
+---
+
+## Introduction
+
+CHT releases use [Semantic Versioning](https://en.wikipedia.org/wiki/Semver#Semantic_versioning) (also known as "SemVer"), which means that the CHT upgrade from the major 4.x version to the 5.x version denotes there are breaking changes. The key to a successful upgrade will be to understand and plan for these breaking changes.
+
+While this releases breaking changes mainly apply to Kubernetes based deployments (e.g. Nouveau & Upgrade service), deployments using token login may be affected as well.
+
+As with all upgrades, major or minor, you should always:
+* Have [backups]({{< relref "/hosting/cht/docker/backups/" >}}) that have been tested to work
+* Ensure your [CHT Conf]({{< relref "/community/contributing/code/cht-conf/" >}}) version is up to date
+* Review the change log to understand how end users might be affected
+
+## CouchDB Nouveau
+
+{{< callout type="info" >}} Applies to: [Kubernetes]({{< relref "/hosting/cht/kubernetes/" >}}) hosted CHT instances {{< /callout >}}
+
+A major feature of CHT 5.0 is replacing the old freetext search in 4.x with CouchDB Nouveau. The addition of Nouveau [decreases the amount of disk space](https://github.com/medic/cht-core/issues/9898#issuecomment-2864545914) used by the CHT.  Disk space has been shown to be a major contributor to hosting costs, hence Nouveau is the first feature to [reduce Hosting Total Cost of Ownership (TCO)](https://github.com/medic/cht-roadmap/issues/171).
+
+Kubernetes based deployments will need to follow the migration steps from the deprecated [CHT 4.x Helm Charts repository](https://github.com/medic/helm-charts/) to the new [CHT 5.x Helm Charts](https://github.com/medic/cht-core/tree/master/scripts/build/helm) in the main CHT repository.
+
+Please see the technical guide on how to migrate Kubernetes based deployments to 5.0.
+
+Background information:
+* [Reduce disk space with CouchDB Nouveau (TCO)](https://github.com/medic/cht-core/issues/9542)
+
+### Related Updates
+
+While the 5.0 upgrade for Docker based deployments will be transparent, there's some more Nouveau related changes that deployments should know about which can affect both Docker and Kubernetes:
+
+* Offline users' devices will have their search indexes rebuilt after the upgrade. During the rebuild, search functionality will be initially unavailable. However, once the indexing is complete, the search behavior will be unchanged from before for all users:  the search experience is the same in both CHT 4.x and CHT 5.x.
+* The Nouveau index data on the server will be stored in `${COUCHDB_DATA}/nouveau` for single-node CouchDBs and in `${DB1_DATA}/nouveau` for clustered CouchDBs.
+* The following `medic-client` views no longer exist. Be sure to update any custom scripts which use them:  `contacts_by_freetext`,  `contacts_by_type_freetext` and  `reports_by_freetext` .
+
+## Upgrade service removed from Kubernetes
+
+{{< callout type="info" >}} Applies to: [Kubernetes]({{< relref "/hosting/cht/kubernetes/" >}}) hosted CHT instances {{< /callout >}}
+
+In CHT 4.x there are two ways to upgrade a Kubernetes hosted CHT instance:
+
+1. Click "Stage" and then "Upgrade" in the CHT administration interface.  
+2. Push a new helm chart to Kubernetes that specified different versions.
+
+A recurring problem seen on production deployments was that, over time, CHT administrators would use the CHT administration interface to upgrade.  Then, during a migration or a restore from backup, Kubernetes administrators would inadvertently downgrade a CHT instance by using an out of date Helm chart.
+
+To avoid this situation, the upgrade service has been removed from Kubernetes based deployments.
+
+Kubernetes based deployments will need to follow the migration steps from the deprecated [CHT 4.x Helm Charts repository](https://github.com/medic/helm-charts/) to the new [CHT 5.x Helm Charts](https://github.com/medic/cht-core/tree/master/scripts/build/helm) in the main CHT repository. Please see the TK technical guide on how to migrate Kubernetes based deployments to 5.0.
+
+Background information:
+* [Hide upgrade button in admin app for k8s deployments, while still allowing staging upgrades](https://github.com/medic/cht-core/issues/9954)
+* [Remove upgrade service from Helm charts](https://github.com/medic/cht-core/issues/10186)
+
+## Token login requires `app_url`
+
+{{< callout type="info" >}} Applies to: Instances that use [token login]({{< relref "/building/login/#magic-links-for-logging-in-token-login" >}}) {{< /callout >}}
+
+For instances that use token login,  be sure declare `app_url` in your [settings file]({{< relref "/building/reference/app-settings/token_login/#app_settingsjson-token_login" >}}). This is backwards compatible and safe to do while still on CHT 4.x.  
+
+Be sure to use [the new declarative config](#declarative-configuration) as well.
+
+Background information:
+* [Require `app_url` to be set when enabling `token_login`](https://github.com/medic/cht-core/issues/9983)
+
+## Enabling languages via generated docs
+
+{{< callout type="info" >}} Applies to: Instances that enable languages via web interface {{< /callout >}}
+
+As of [CHT 4.2.0]({{< relref "/releases/4_2_0/#technical-improvements" >}}), deployment administrators can enable or disable supported languages [via the settings file]({{< relref "/building/reference/app-settings/#app_settingsjson" >}}). CHT 5.0 removes this web interface to enable or disable languages and requires this to be done via App Settings.
+
+Before upgrading, ensure [your app settings]({{< relref "/building/reference/app-settings/#app_settingsjson" >}}) has the correct languages enabled. This is backwards compatible and safe to do while still on CHT 4.x.
+
+Background information:
+* [Deprecate enabling languages through generated docs](https://github.com/medic/cht-core/issues/8157)
+* [Allow app builders to specify disabled languages in config](https://github.com/medic/cht-core/issues/6281)
+
+
+## Declarative Configuration 
+
+{{< callout type="info" >}} Applies to: All Instances {{< /callout >}}
+
+tk - all the content ;)  - but upgrade your app settings to be declarative. 
+
+Be sure to [update](#token-login-requires-app_url) your `app_url` in settings if you're using token login..
+
+Background information:
+* [Make declarative config mandatory](https://github.com/medic/cht-core/issues/5906)
+
+## Increase ecmaVersion ES linting to version 6
+
+{{< callout type="info" >}} Applies to: CHT versions between 4.0 and 4.4  {{< /callout >}}
+
+Deployments running CHT Version 4.0 and 4.4 must upgrade to version 4.5 or later before upgrading to version 5.x.
+
+Background information:
+* [Increase ecmaversion linting for ddocs](https://github.com/medic/cht-core/issues/9202)
+
+<!--
+todo:  replace all "TK" with correct link/text
+-->

content/en/releases/4_0_0.md

@@ -18,7 +18,7 @@ Check the repository for the [latest known issues](https://github.com/medic/cht-
 
 ### Breaking changes
 
-To prepare for this release, read through our [Preparing to Upgrade documentation]({{< ref "building/guides/updates/preparing-for-4" >}}).
+To prepare for this release, read through our [Preparing to Upgrade documentation]({{< ref "hosting/cht/migration/preparing-for-4" >}}).
 
 {{< callout type="warning" >}}
   Be aware that as this is a major upgrade some manual steps are required - following the usual upgrade process will not work. [Data migration documentation is coming soon]({{< ref "/hosting/cht" >}}), but in the meantime reach out on [the forum](https://forum.communityhealthtoolkit.org/) for direct support in upgrading. New projects should start on 4.0.0 to make the following upgrades easier.

content/en/releases/4_12_0.md

@@ -24,7 +24,7 @@ None.
 
 This release includes changes to the user interface which will improve the learnability of the CHT by aligning with the look and feel of other android apps. Below is a summary of the changes, all of which were covered in the [July Round-up Call](https://youtube.com/watch?v=NSFRQt378Ls&t=460s):
 - [Update to the overall CHT app Navigation experience](https://forum.communityhealthtoolkit.org/t/the-ui-evolution-of-the-cht/3515#navigation-6)
-- Added the ability to temporarily [opt out]({{< relref "building/guides/updates/feature-flags" >}}) of the new Navigation experience
+- Added the ability to temporarily [opt out]({{< relref "building/guides/feature-flags" >}}) of the new Navigation experience
 - [Removal of opt out capabilities for Old Filter and Search](https://forum.communityhealthtoolkit.org/t/feature-removal-opting-out-of-two-ui-changes/3738)
 - [Removal of opt out capabilities for Old Action Bar](https://forum.communityhealthtoolkit.org/t/feature-removal-opting-out-of-two-ui-changes/3738)
 

content/en/releases/4_2_0.md

@@ -26,7 +26,7 @@ None.
 
 The additive actions (creating reports, places, people, etc...) have moved from the bottom action bar to a Floating Action Button that opens a menu with all actions. This change aligns the CHT more closely with Android UX and [material design patterns](https://m3.material.io/components/menus/overview), and applies to the Messages, Reports, and Contacts tab.
 
-NOTE: The bottom action bar can be temporarily re-enabled for specific users by granting them the `can_view_old_action_bar` permission; however, it will be completely removed in a future release. See the [Feature Flags]({{< relref "building/guides/updates/feature-flags" >}}) documentation for more information.
+NOTE: The bottom action bar can be temporarily re-enabled for specific users by granting them the `can_view_old_action_bar` permission; however, it will be completely removed in a future release. See the [Feature Flags]({{< relref "building/guides/feature-flags" >}}) documentation for more information.
 
 {{< cards cols=2 >}}
   {{< figure src="../images/4_2_0-7998-mobile-fab.png" class="left col-4 col-lg-4" >}}
@@ -41,7 +41,7 @@ NOTE: The bottom action bar can be temporarily re-enabled for specific users by
 
 The Export, Edit, and Delete actions have moved from the bottom action bar to a new More Option (⋮) menu located on the top right side of the screen. This change aligns the CHT more closely with Android UX and [material design patterns](https://m3.material.io/components/menus/overview), and applies to the Messages, Reports, and Contacts tab.
 
-NOTE: The bottom action bar can be temporarily re-enabled for specific users by granting them the `can_view_old_action_bar` permission; however, it will be completely removed in a future release. See the [Feature Flags]({{< relref "building/guides/updates/feature-flags" >}}) documentation for more information.
+NOTE: The bottom action bar can be temporarily re-enabled for specific users by granting them the `can_view_old_action_bar` permission; however, it will be completely removed in a future release. See the [Feature Flags]({{< relref "building/guides/feature-flags" >}}) documentation for more information.
 
 {{< cards >}}
   {{< figure src="../images/4_2_0-7872-mobile.png" class="left col-3 col-lg-3" >}}