From e319b0a2a3e2443954fc8112026d18b3ef025e46 Mon Sep 17 00:00:00 2001 From: Tom Wier Date: Fri, 16 Oct 2026 10:27:43 +0300 Subject: [PATCH 1/4] docs: add 5.3.2 release notes --- content/en/releases/5_3_2.md | 71 +++++++++++++++++++++++++++++++++++ content/en/releases/_index.md | 1 + 2 files changed, 72 insertions(+) create mode 100644 content/en/releases/5_3_2.md diff --git a/content/en/releases/5_3_2.md b/content/en/releases/5_3_2.md new file mode 100644 index 000000000..855121ca7 --- /dev/null +++ b/content/en/releases/5_3_2.md @@ -0,0 +1,71 @@ +--- +title: "5.3.2 release notes" +linkTitle: "5.3.2" +sidebar: + exclude: true +description: + Released 2026-10-16 +--- + +## Highlights + +5.3.2 is a patch release with two fixes for Nouveau, the CouchDB search service that drives user replication and server-side purging. + +### CouchDB 3.5.3 + +The CHT upgrades CouchDB to 3.5.3. This version fixes upstream bugs ([apache/couchdb#6118](https://github.com/apache/couchdb/issues/6118) that caused Nouveau index rebuilds to fail after documents were purged from the database, for example with the [archiving endpoint](/technical-overview/data/performance/archiving/). Without that index, users can't sync ([#11456](https://github.com/medic/cht-core/issues/11456)). + +### Smaller Nouveau queries + +API and Sentinel request at most {{< format-number 20_000 >}} results per page from the `docs_by_replication_key` Nouveau index, down from {{< format-number 200_000 >}}. CouchDB sends the limit to every shard, so the old value could exhaust the Nouveau heap during server-side purging and leave the index unusable until Nouveau restarted. Replication authorization pages through larger result sets instead of requesting them all at once ([#11490](https://github.com/medic/cht-core/issues/11490)). + +## Known issues + +Check the repository for the [latest known issues](https://github.com/medic/cht-core/issues?q=is%3Aissue+label%3A%22Affects%3A+5.3.2%22). + +## Upgrade notes + +### Breaking changes + +None. + +### UI/UX changes + +None. + + + +## And more... + +### Features + +None. + +### Improvements + +None. + +### Security fixes + +None. + +### Performance improvements + +None. + +### Bug fixes + +- [#11456](https://github.com/medic/cht-core/issues/11456): Syncing issues with rebuilt Nouveau index after archiving +- [#11490](https://github.com/medic/cht-core/issues/11490): Server-side purging requests 200k hits per shard from `docs_by_replication_key`, exhausting Nouveau heap + +### Technical improvements + +None. + + + +## Contributors + +Thanks to all who committed changes for this release! + +- [Tom Wier](https://github.com/witash) diff --git a/content/en/releases/_index.md b/content/en/releases/_index.md index ddfcc7693..d41992439 100644 --- a/content/en/releases/_index.md +++ b/content/en/releases/_index.md @@ -96,6 +96,7 @@ Devices with more navigation systems are more likely to get a more accurate loca ## Release Notes ### 5.x +- [5.3.2](/releases/5_3_2) - 2026-10-16 - [5.3.1](/releases/5_3_1) - 2026-09-15 - [5.3.0](/releases/5_3_0) - 2026-08-31 - [5.2.0](/releases/5_2_0) - 2026-06-26 From 5c7b51f501bb23b20f11edff5e585e20fe1b3c76 Mon Sep 17 00:00:00 2001 From: Tom Wier Date: Fri, 16 Oct 2026 10:46:50 +0300 Subject: [PATCH 2/4] docs: adding 5.3.2 upgrade notes --- content/en/releases/5_3_2.md | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/content/en/releases/5_3_2.md b/content/en/releases/5_3_2.md index 855121ca7..8c7c8753c 100644 --- a/content/en/releases/5_3_2.md +++ b/content/en/releases/5_3_2.md @@ -13,7 +13,7 @@ description: ### CouchDB 3.5.3 -The CHT upgrades CouchDB to 3.5.3. This version fixes upstream bugs ([apache/couchdb#6118](https://github.com/apache/couchdb/issues/6118) that caused Nouveau index rebuilds to fail after documents were purged from the database, for example with the [archiving endpoint](/technical-overview/data/performance/archiving/). Without that index, users can't sync ([#11456](https://github.com/medic/cht-core/issues/11456)). +The CHT upgrades CouchDB to 3.5.3. This version fixes upstream bugs ([apache/couchdb#6118](https://github.com/apache/couchdb/issues/6118)) that caused Nouveau index rebuilds to fail after documents were purged from the database, for example with the [archiving endpoint](/technical-overview/data/performance/archiving/). Without that index, users can't sync ([#11456](https://github.com/medic/cht-core/issues/11456)). ### Smaller Nouveau queries @@ -25,6 +25,21 @@ Check the repository for the [latest known issues](https://github.com/medic/cht- ## Upgrade notes +### Instances with a broken Nouveau index + +If your Nouveau indexes work, upgrade to 5.3.2 as usual. This includes instances that archived documents but haven't rebuilt an index since. + +If an index rebuild already failed on your instance and users can't sync, upgrading to 5.3.2 alone doesn't repair the index: + +- Upgrading from the **Upgrade** page in the Admin app, or with the upgrade API, fails because the upgrade queries the broken index. +- Upgrading with `helm upgrade`, or by changing the image versions in your Docker Compose files, succeeds but doesn't rebuild the index. 5.3.2 doesn't change the index definitions, so nothing triggers a rebuild. + +To fix the index, run the the [repair script](https://gist.github.com/jkuester/6ab703b2d12265d2b181bc020b73571b) on the 5.3.0 or 5.3.1 instance, then upgrade. The script requires the default 5.3.0 or 5.3.1 index definitions. + +If an earlier upgrade attempt left a broken staged index, the upgrade replaces your working index with it. Before upgrading, stage the upgrade again or delete the staged index. + +To upgrade from 5.3.0 or 5.3.1 to a later release that changes the `docs_by_replication_key` index, upgrade to 5.3.2 first. + ### Breaking changes None. From 18a3125f8e9c89ccd1990f45db9bc6f2fcceb4e1 Mon Sep 17 00:00:00 2001 From: Tom Wier Date: Fri, 16 Oct 2026 12:02:37 +0300 Subject: [PATCH 3/4] docs: add issue 11500 to release notes --- content/en/releases/5_3_2.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/content/en/releases/5_3_2.md b/content/en/releases/5_3_2.md index 8c7c8753c..f80b05f74 100644 --- a/content/en/releases/5_3_2.md +++ b/content/en/releases/5_3_2.md @@ -9,7 +9,7 @@ description: ## Highlights -5.3.2 is a patch release with two fixes for Nouveau, the CouchDB search service that drives user replication and server-side purging. +5.3.2 is a patch release with two fixes for Nouveau, the CouchDB search service that drives user replication and server-side purging. It also fixes a 5.3.0 regression in how reports display their subject. ### CouchDB 3.5.3 @@ -19,6 +19,10 @@ The CHT upgrades CouchDB to 3.5.3. This version fixes upstream bugs ([apache/cou API and Sentinel request at most {{< format-number 20_000 >}} results per page from the `docs_by_replication_key` Nouveau index, down from {{< format-number 200_000 >}}. CouchDB sends the limit to every shard, so the old value could exhaust the Nouveau heap during server-side purging and leave the index unusable until Nouveau restarted. Replication authorization pages through larger result sets instead of requesting them all at once ([#11490](https://github.com/medic/cht-core/issues/11490)). +### Report subjects with an empty `patient_id` + +When an offline user creates a person and then submits a report about them before syncing, the person has no shortcode yet, so the report saves an empty `fields.patient_id`. Since 5.3.0, the reports list and report detail showed these reports' subject as plain text with no link to the contact, and showed the submitter's lineage instead of the subject's. The CHT falls back to `fields.patient_uuid` when `fields.patient_id` is empty, so these reports display their subject correctly ([#11500](https://github.com/medic/cht-core/issues/11500)). + ## Known issues Check the repository for the [latest known issues](https://github.com/medic/cht-core/issues?q=is%3Aissue+label%3A%22Affects%3A+5.3.2%22). @@ -72,6 +76,7 @@ None. - [#11456](https://github.com/medic/cht-core/issues/11456): Syncing issues with rebuilt Nouveau index after archiving - [#11490](https://github.com/medic/cht-core/issues/11490): Server-side purging requests 200k hits per shard from `docs_by_replication_key`, exhausting Nouveau heap +- [#11500](https://github.com/medic/cht-core/issues/11500): Report subject is not linked and shows the submitter's lineage when `fields.patient_id` is an empty string (regression in 5.3.0) ### Technical improvements @@ -84,3 +89,4 @@ None. Thanks to all who committed changes for this release! - [Tom Wier](https://github.com/witash) +- [Binod Adhikary](https://github.com/binokaryg) From c2c572352f26e22ad665f56657708af9944a5bea Mon Sep 17 00:00:00 2001 From: witash Date: Wed, 21 Oct 2026 10:28:03 +0300 Subject: [PATCH 4/4] Apply batched suggestions from code review Co-authored-by: Joshua Kuestersteffen --- content/en/releases/5_3_2.md | 15 +++++---------- 1 file changed, 5 insertions(+), 10 deletions(-) diff --git a/content/en/releases/5_3_2.md b/content/en/releases/5_3_2.md index f80b05f74..934617d61 100644 --- a/content/en/releases/5_3_2.md +++ b/content/en/releases/5_3_2.md @@ -21,7 +21,7 @@ API and Sentinel request at most {{< format-number 20_000 >}} results per page f ### Report subjects with an empty `patient_id` -When an offline user creates a person and then submits a report about them before syncing, the person has no shortcode yet, so the report saves an empty `fields.patient_id`. Since 5.3.0, the reports list and report detail showed these reports' subject as plain text with no link to the contact, and showed the submitter's lineage instead of the subject's. The CHT falls back to `fields.patient_uuid` when `fields.patient_id` is empty, so these reports display their subject correctly ([#11500](https://github.com/medic/cht-core/issues/11500)). +When an offline user creates a person and then submits a report about them before syncing, the person has no shortcode yet, so the report saves an empty `fields.patient_id`. Since 5.3.0, the reports list and report detail showed these reports' subject as plain text with no link to the contact, and showed the submitter's lineage instead of the subject's. With this fix, the CHT correctly falls back to `fields.patient_uuid` when `fields.patient_id` is empty, so these reports display their subject correctly ([#11500](https://github.com/medic/cht-core/issues/11500)). This matches the behavior of CHT versions prior to 5.3.0. ## Known issues @@ -31,18 +31,13 @@ Check the repository for the [latest known issues](https://github.com/medic/cht- ### Instances with a broken Nouveau index -If your Nouveau indexes work, upgrade to 5.3.2 as usual. This includes instances that archived documents but haven't rebuilt an index since. +All instances currently running 5.3.0 or 5.3.1 should upgrade to 5.3.2 first before upgrading to any later release. -If an index rebuild already failed on your instance and users can't sync, upgrading to 5.3.2 alone doesn't repair the index: +If you are running a CHT version prior to 5.3.0 OR if offline users can successfully sync, your Nouveau indexes have not been affected by the [#11456](https://github.com/medic/cht-core/issues/11456) bug and you can upgrade to 5.3.2 as usual. -- Upgrading from the **Upgrade** page in the Admin app, or with the upgrade API, fails because the upgrade queries the broken index. -- Upgrading with `helm upgrade`, or by changing the image versions in your Docker Compose files, succeeds but doesn't rebuild the index. 5.3.2 doesn't change the index definitions, so nothing triggers a rebuild. +If you are running CHT 5.3.0 or 5.3.1 AND users are unable to sync due to the [#11456](https://github.com/medic/cht-core/issues/11456) bug additional steps are required to successfully upgrade. That issue affects the CHT instance's ability to rebuild Nouveau indexes. Trying to upgrade an affected instance to a new CHT version will fail because the Nouveau indexes are not available and cannot be rebuilt. The issue with the Nouveau indexes must be resolved prior to upgrading. -To fix the index, run the the [repair script](https://gist.github.com/jkuester/6ab703b2d12265d2b181bc020b73571b) on the 5.3.0 or 5.3.1 instance, then upgrade. The script requires the default 5.3.0 or 5.3.1 index definitions. - -If an earlier upgrade attempt left a broken staged index, the upgrade replaces your working index with it. Before upgrading, stage the upgrade again or delete the staged index. - -To upgrade from 5.3.0 or 5.3.1 to a later release that changes the `docs_by_replication_key` index, upgrade to 5.3.2 first. +The simplest way to fix the Nouveau indexes is to run the the [repair script](https://gist.github.com/jkuester/6ab703b2d12265d2b181bc020b73571b) in your Couch container. (Note that the current version of the script only supports single-node Couch instances, but can be easily customized for a multi-node deployment.) See the documentation on the script for more details. ### Breaking changes