"users-meta failed with compilation_error" when upgrade to 4.8

[mrjones-plip]

Describe the bug
Due to a new view that was added in 4.7, which requires the newer version of CouchDB, upgrading from any version pre 4.4 to any version post 4.7 will fail

To Reproduce

1. deploy 4.1
2. upgrade directly to 4.8
3. see error

Expected behavior
upgrade should succeed

Logs

2024-06-03 17:46:15 ERROR: Error thrown while installing: Error: Error while saving docs: saving _design/:staged:users-meta failed with compilation_error
    at Object.module.exports.saveDocs (/api/src/db.js:164:11)
    at runMicrotasks (<anonymous>)
    at processTicksAndRejections (node:internal/process/task_queues:96:5)
    at async Object.saveStagedDdocs (/api/src/services/setup/utils.js:258:5)
    at async Object.stage (/api/src/services/setup/upgrade-steps.js:92:3)
    at async safeInstall (/api/src/services/setup/upgrade.js:40:5) {
  [stack]: 'Error: Error while saving docs: saving _design/:staged:users-meta failed with compilation_error\n' +
    '    at Object.module.exports.saveDocs (/api/src/db.js:164:11)\n' +
    '    at runMicrotasks (<anonymous>)\n' +
    '    at processTicksAndRejections (node:internal/process/task_queues:96:5)\n' +
    '    at async Object.saveStagedDdocs (/api/src/services/setup/utils.js:258:5)\n' +
    '    at async Object.stage (/api/src/services/setup/upgrade-steps.js:92:3)\n' +
    '    at async safeInstall (/api/src/services/setup/upgrade.js:40:5)',
  [message]: 'Error while saving docs: saving _design/:staged:users-meta failed with compilation_error'
}

Screenshots

Environment

• Instance: NA
• Browser: NA
• Client platform: NA
• App: NA
• Version: 4.7+

Additional context
This was discovered upgrading MoH KE and initially a documentation fix was suggested, but instead a patch release is suggested with this ticket

Workaround
The workaround is to upgrade to 4.6.0 (which gets you on to CouchDB 3) and then upgrade to whatever version you want.

[mrjones-plip]

cc @dianabarsan @garethbowen @1yuv @derickl

should I add Affects labels for 4.0.0 - 4.7.0?

[garethbowen]

@mrjones-plip I think it's more important to show as a known issue for the version you're upgrading TO than the version you're upgrading FROM. ie: the affects labels should be from the time the issue was introduced, so 4.7.0 and above.

[garethbowen]

As part of this we should

1. make sure our linting protects from future mistakes by treating view code as an older version of es than other code.
2. raise an issue to remove this limitation in a future version, eg: 5.0.0
3. raise an issue to make the upgrade more tolerant of failures like this - if this error were ignored and the upgrade continued then everything would work as expected, albeit with a little downtime. This should not block the upgrade.

[mrjones-plip]

so 4.7.0 and above

Thannks @garethbowen - added!

[garethbowen]

@mrjones-plip Don't forget our old friend 4.7.1

[mrjones-plip]

OMG! How could I possibly forget!? I had to create it, but added.

[garethbowen]

@mrjones-plip I'm about to head on leave - would you mind organising someone to take this on and release 4.7.2 and 4.8.1?

[mrjones-plip]

no problem!

[jonathanvq]

@medic/quality-assurance, this should be on your radar.

[dianabarsan]

Merged to master and backported to 4.7.x and 4.8.x