:Added practical upgrade lessons learned that may help others

[remcovanvugt]

Overview

I recently encountered a few practical hurdles when upgrading a real old 2.x cluster to 3.x, I guess a few notes in the documentation might help others in the same situation.

Checklist

• Code is written and works correctly
• Changes are covered by tests
• Any new configurable parameters are documented in rel/overlay/etc/default.ini
• Documentation changes were made in the src/docs folder
• Documentation changes were backported (separated PR) to affected branches

[nickva]

Thank you for your contribution!

Those seem reasonable, hopefully it will help others during their upgrade.

To fix the issues with formatting try:

cd src/docs
./setup.sh
make check
make html

Setup will try to create a python virtual environment if it's not there yet and fetch dependencies. Then make check will check for formatting errors. And after make html is finished the docs can be inspected locally with open build/html/index.html

The list of warning currently look like line lengths mostly:

08:26:35  + cd src/docs
08:26:35  + make check
08:26:35  python3 ext/linter.py src/
08:26:35  /home/jenkins/workspace/jenkins-cm[1](https://ci-couchdb.apache.org/job/jenkins-cm1/job/PullRequests/job/PR-5407/1/pipeline-console/?start-byte=0&selected-node=80#log-1)_PullRequests_PR-5407/src/docs/src/install/upgrading.rst
08:[2](https://ci-couchdb.apache.org/job/jenkins-cm1/job/PullRequests/job/PR-5407/1/pipeline-console/?start-byte=0&selected-node=80#log-2)6:35    line 98 : trailing whitespace detected!
08:26:[3](https://ci-couchdb.apache.org/job/jenkins-cm1/job/PullRequests/job/PR-5407/1/pipeline-console/?start-byte=0&selected-node=80#log-3)5     attachment uploads. Please 
08:26:35  
08:26:35    line 100 : too long (100 > 90) line
08:26:35  #. There is are new default thresholds for smoosh that may or may not be present in your old config.
08:26:35  
08:26:35    line 101 : too long (96 > 90) line
08:26:35     If the configuration is not adjust you may experience high cpu usage on the upgraded cluster.
08:26:35  
08:26:35    line 102 : trailing whitespace detected!
08:26:35     `see issue: <https://github.com/apache/couchdb/issues/30[4](https://ci-couchdb.apache.org/job/jenkins-cm1/job/PullRequests/job/PR-5407/1/pipeline-console/?start-byte=0&selected-node=80#log-4)7>`_   
08:26:35  
08:26:35    line 103 : too long (127 > 90) line
08:26:3[5](https://ci-couchdb.apache.org/job/jenkins-cm1/job/PullRequests/job/PR-5407/1/pipeline-console/?start-byte=0&selected-node=80#log-5)  #. Make sure you have configured the :ref:`view_index_dir<config/view_index_dir>` parameter. In previous version this defaulted
08:2[6](https://ci-couchdb.apache.org/job/jenkins-cm1/job/PullRequests/job/PR-5407/1/pipeline-console/?start-byte=0&selected-node=80#log-6):35  
08:26:35    line 104 : too long (123 > 90) line
0[8](https://ci-couchdb.apache.org/job/jenkins-cm1/job/PullRequests/job/PR-5407/1/pipeline-console/?start-byte=0&selected-node=80#log-8):26:35     to the value of :ref:`database_dir<config/database_dir>`. Not setting this may cause the cluster to start rebuilding all
08:26:35  
08:26:35  make: *** [Makefile:48: check] Error 1