Added note to 19.1 docs about turning off range merging for manual splits

[ericharmeling]

Fixes #4960.

Note that this affects only 19.1 docs, since cockroachdb/cockroach#38004 removes this limitation in 19.2.

[cockroach-teamcity]

This change is 

[cockroach-teamcity]

Online preview: http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/502a8c2573ef62b2fee33c583f3a4607fad9eb9f/

Edited pages:

• v19.1/split-at.md

[cockroach-teamcity]

Online preview: http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/287510a74bc56751e2b2ad25780cfd2f7d4f9836/

Edited pages:

• v19.1/split-at.md

[bdarnell]

We should probably have a companion upgrade checklist: when upgrading to 19.2, check your cluster settings:

• If you disabled the range merge queue in order to use manual splits, consider turning it back on since manual splits no longer conflict with the range queue
• etc.

[cockroach-teamcity]

Online preview: http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/7379eae9e98e1aa0645f5239bc169d71dc739633/

Edited pages:

• v19.1/range-merges.md
• v19.1/split-at.md
• v19.2/range-merges.md

[ericharmeling]

@bdarnell Thanks for the suggestion Ben! I updated the PR:

• Added a note about turning merging back on when upgrading (in SPLIT AT and in Range Merges docs)
• Removed the sections about "When to turn merging on/off", as they don't really add any information or apply in 19.2

I'm happy to add/remove any more information.

[bdarnell]

I was thinking the note about removing the setting in upgrading would go in https://www.cockroachlabs.com/docs/dev/upgrade-cockroach-version.html

[ericharmeling]

I was thinking the note about removing the setting in upgrading would go in https://www.cockroachlabs.com/docs/dev/upgrade-cockroach-version.html

Looking at that page, I'm not sure exactly where putting a checklist like that should go in the current structure of the page. It might be best to create a new section at the bottom of the page (something like "Post-upgrade Checklist"), with some suggestions about changing settings for performance optimization and new features in 19.2. That probably should be a separate issue and PR. That separate issue might also inform the issue that @jseldess opened about finalizing an upgrade: #5646

@jseldess Thoughts?

[jseldess]

If this action needs to be taken after finalizing the upgrade, I agree that we could either add it to https://www.cockroachlabs.com/docs/dev/upgrade-cockroach-version.html#step-5-finish-the-upgrade, or create a subsequent step.

[ericharmeling]

@bdarnell

We should probably have a companion upgrade checklist: when upgrading to 19.2, check your cluster settings:

• If you disabled the range merge queue in order to use manual splits, consider turning it back on since manual splits no longer conflict with the range queue
• etc.

A couple follow-up questions:

• Is there a reason why reseting kv.range_merge.queue_enabled is not automated as a part of the upgrade finalization process?
• What other cluster settings (the "etc." you mentioned above) need checking/updating post-upgrade?
• Are there any other post-upgrade steps that you know of that we are not documenting on Upgrade to CockroachDB v19.2?

[bdarnell]

Is there a reason why reseting kv.range_merge.queue_enabled is not automated as a part of the upgrade finalization process?

Because they might have turned it off for other reasons. We should be very cautious about automatically undoing user actions.

What other cluster settings (the "etc." you mentioned above) need checking/updating post-upgrade?

Good question. I don't know if there are any, but the "known limitation" list might be a good place to look. Any known limitation which A) had a workaround and B) is resolved in 19.2 would be worth listing here to let users know that the workaround can be removed.

[ericharmeling]

Thanks @bdarnell. I opened a new issue for the update to the Upgrade to CockroachDB v19.2 page, as I think it's out-of-scope for this PR (see #5672). I will open a separate PR to resolve that separate issue this week.

If you (or @andreimatei) are fine with the other changes in this PR, I can pass it off to @rmloveland to review for merging.

[jseldess]

@bdarnell, you ok with this PR if we follow-up with a post-upgrade checklist?

[bdarnell]

Yes, it's fine to leave a post-upgrade checklist as a separate item.

[rmloveland]

LGTM