document nouveau handling of lucene 9 & 10

Author: rnewson

nouveau/README.md

@@ -3,8 +3,8 @@
 Nouveau is a modern replacement for dreyfus/clouseau and is built on;
 
 1) the Dropwizard framework (https://dropwizard.io)
-2) Java 11+
-3) Lucene 9
+2) Java 21+
+3) Lucene 10
 
 Nouveau transforms Apache CouchDB databases into Apache Lucene indexes at the shard level and then merges the results together.
 
@@ -23,7 +23,7 @@ This work is currently EXPERIMENTAL and may change in ways that invalidate any e
 * integration with resharding
 * update=false
 * `_nouveau_info`
-* `_search_cleanup`
+* `_nouveau_cleanup`
 * /openapi.{json.yaml}
 
 ## What doesn't work yet?

src/docs/src/api/database/cleanup.rst

@@ -58,6 +58,8 @@
             "ok": true
         }
 
+.. _api/db/nouveau_cleanup:
+
 ==========================
 ``/{db}/_nouveau_cleanup``
 ==========================

src/docs/src/ddocs/nouveau.rst

@@ -63,6 +63,40 @@ results from deeper in the result set.
 A nouveau index will inherit the partitioning type from the ``options.partitioned`` field
 of the design document that contains it.
 
+.. _ddoc/nouveau/lucene_upgrade:
+
+Lucene Version Upgrade
+======================
+
+Nouveau has been upgraded to use Lucene 10, earlier releases used Lucene 9.
+
+Nouveau can query and update indexes created by Lucene 9 but will not create new
+ones. The index definition can optionally define a ``lucene_version`` field
+(which must be either 9 or 10 expressed as an integer). If not specified
+when defining a new index the current version (10) will be automatically
+added to the definition.
+
+As Lucene only supports indexes up to one major release behind the current, it
+is important to rebuild all indexes to the current release. As Lucene major
+releases are infrequent, and Nouveau supports 9 and 10 versions simultaneously
+it is only necessary to rebuild version 9 indexes before Nouveau upgrades to
+Lucene 11 (when it exists), and so the plugin rebuilds one index at a time as a
+background activity.  A ``couch_scanner`` plugin is available to automate this
+process, and can be enabled as follows;
+
+.. code-block:: ini
+
+    [couch_scanner_plugins]
+    nouveau_index_upgrader = true
+
+The plugin will scan all design documents for index definitions either with no
+``lucene_version`` field or one equal to a previous version (lower than
+10). The new index will be built by the plugin and, on successful
+completion, will update the ``lucene_version`` field in the index
+definition. Search requests against that index will seamlessly switch from the
+old index to the new one. Invoking the :ref:`_nouveau_cleanup <api/db/nouveau_cleanup>`
+will delete the old indexes.
+
 .. _ddoc/nouveau/field_types:
 
 Field Types

src/docs/src/install/nouveau.rst

@@ -25,7 +25,7 @@ service that embeds `Apache Lucene <https://lucene.apache.org>`_. Typically, thi
 service is installed on the same host as CouchDB and communicates with it over
 the loopback network.
 
-Nouveau server is runtime-compatible with Java 11 or higher.
+Nouveau server is runtime-compatible with Java 21 or higher.
 
 Enable Nouveau
 ==============