add docs explaining how to run update-fields.sh in configbaker #11023

doc/sphinx-guides/source/admin/metadatacustomization.rst

@@ -539,7 +539,7 @@ a necessary re-index, but for your custom metadata you will need to keep track o
 
 Please note also that if you are going to make a pull request updating ``conf/solr/schema.xml`` with fields you have
 added, you should first load all the custom metadata blocks in ``scripts/api/data/metadatablocks`` (including ones you
-don't care about) to create a complete list of fields. (This might change in the future.)
+don't care about) to create a complete list of fields. (This might change in the future.) Please see :ref:`update-solr-schema-dev` in the Developer Guide.
 
 Reloading a Metadata Block
 --------------------------

doc/sphinx-guides/source/container/configbaker-image.rst

@@ -54,7 +54,7 @@ Scripts
     - Default script when running container without parameters. Lists available scripts and details about them.
   * - ``update-fields.sh``
     - Update a Solr ``schema.xml`` with a given list of metadata fields. See ``update-fields.sh -h`` for usage details
-      and :ref:`update-solr-schema` for an example use case.
+      and example use cases at :ref:`update-solr-schema` and :ref:`update-solr-schema-dev`.
 
 Solr Template
 ^^^^^^^^^^^^^

doc/sphinx-guides/source/developers/tips.rst

@@ -187,6 +187,23 @@ Once some Dataverse collections, datasets, and files have been created and index
 
 You can simply double-click "start.jar" rather that running ``java -jar start.jar`` from the command line. Figuring out how to stop Solr after double-clicking it is an exercise for the reader.
 
+.. _update-solr-schema-dev:
+
+Updating the Solr Schema (Developers)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Both developers and sysadmins need to update the Solr schema from time to time. One difference is that developers will be committing changes to ``conf/solr/schema.xml`` in git. To prevent cross-platform differences in the git history, when running the ``update-fields.sh`` script, we ask all developers to run the script from within Docker. (See :doc:`/container/configbaker-image` for more on the image we'll use below.)
+
+.. code-block::
+
+    curl http://localhost:8080/api/admin/index/solr/schema | docker run -i --rm -v ./docker-dev-volumes/solr/data:/var/solr gdcc/configbaker:unstable update-fields.sh /var/solr/data/collection1/conf/schema.xml
+
+    cp docker-dev-volumes/solr/data/data/collection1/conf/schema.xml conf/solr/schema.xml
+
+At this point you can do a ``git diff`` and see if your changes make sense before committing.
+
+Sysadmins are welcome to run ``update-fields.sh`` however they like. See :ref:`update-solr-schema` in the Admin Guide for details.
+
 Git
 ---