Add upgrade notes about not being able to upgrade from v 4.3 and lower to v 4.7 and higher

[dianabarsan]

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 with:

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'
}

This should be captured in upgrade notes.

[mrjones-plip]

I'll grab this!

But...hrrm....what does this actually look like? If I'm, say, 4.1.0 and I want to upgrade to 4.8.0, maybe I don't look at all the release notes? I just look at 4.8.0's? So, do we add a note on all release notes? Would I expect to see it in the "known issues" for 4.8.0? Or even the known issues for 4.4.0? The one upgrade issue on 4.4.0 is actually unrelated to this one.

While it's a bit verbose, I propose updating all 23 of the current 4.x release notes to have an extra section:

Please note that if you're upgrading from a version before 4.4 to a version that is greater than 4.7, you must first upgrade to version 4.4. For example, if you're on version 4.1.0 and want to upgrade to 4.8.0, you should stage and upgrade to version 4.4.0 and then stage and upgrade to version 4.8.0.

In the case of existing content, we'll add this new warning above it. So on 4.3.0's release page, it would look like this:

Upgrade notes

Please note that if you're upgrading from a version before 4.4 to a version that is greater than 4.7, you must first upgrade to version 4.4. For example, if you're on version 4.1.0 and want to upgrade to 4.8.0, you should stage and upgrade to version 4.4.0 and then stage and upgrade to version 4.8.0.

Continuous downwards replication (the algorithm through which offline users download docs from the server) has been completely rewritten. This change required a high number of view updates, which implies that staging this upgrade and indexing views before upgrading will be a lengthy process - depending on the size of the database. Additionally, the server might need additional storage while this process is ongoing. Users will receive the usual upgrade popup, and they will need to reload the app in order to resume replication.

@dianabarsan - what is the workaround if you don't read this and get the error above? Is it safe to just do the upgrade to 4.4 first and proceed?

cc @1yuv and @derickl

[garethbowen]

My 2c here is the fix to the view is probably quite straight forward and that it would be better to fix it and release patches to 4.7 and 4.8 rather than expect people to read release notes.

[1yuv]

I second @garethbowen 's idea if it's possible to fix. Users could attempt from any version, so for medic/couchdb-migration, we can throw error stating that it's not possible if there are such scenarios.

[mrjones-plip]

ok - sounds good! I've opened https://github.com/medic/cht-core/issues/9166 to track the fix and will close this ticket.