Add comments to mixed-cluster upgrade code

[janl]

Via https://github.com/apache/couchdb/pull/4394#pullrequestreview-1263473784

It’d be nice if we tagged code that can be removed after we can expect everybody to have gone through a rolling cluster upgrade with the version number at which it can be removed, so we can semi-automate cleaning up said code.

We could decide to make it a promise that if someone wants to do a rolling upgrade from N-1 to N, that if they are on the latest N-1 release that they can upgrade safely and that N no longer has the upgrade code. But all versions inside N-1 can be rolling-upgraded.

That would reflect reality, especially outside IBM/Cloudant, where folks don’t track each and every CouchDB version.

cc @mikerhodes

[piyahub]

Hi! I would like to work on this issue.

From the discussion, the goal is to add clear inline comments inside the mixed-cluster upgrade code to mark sections that exist only for backward-compatibility during rolling upgrades. These comments will indicate when a piece of upgrade logic can be safely removed once users have moved past specific CouchDB versions.

Before I begin, could you confirm:

Which specific files/directories contain the mixed-cluster upgrade logic you want documented?

Should the comments follow any preferred format or tag (e.g., “TODO: remove after version X”)?

Once I get this clarification, I’ll start working on the update. Thanks!

[rnewson]

Hi @piyahub,

if there is something missing in the docs or could be improved, please go ahead and open a PR. We will discuss the changes there. You can find some contribution tips in our guide and I would like to draw particular attention to our prohibition of artificial intelligence.