[solr] branch branch_9x updated: Add docs for updating the ref-guide ui bundle

[ho...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

houston pushed a commit to branch branch_9x
in repository https://gitbox.apache.org/repos/asf/solr.git


The following commit(s) were added to refs/heads/branch_9x by this push:
     new 208df0c27ed Add docs for updating the ref-guide ui bundle
208df0c27ed is described below

commit 208df0c27ed061405acd3d44807ecbb4634dc718
Author: Houston Putman <ho...@apache.org>
AuthorDate: Tue May 17 13:58:31 2022 -0400

    Add docs for updating the ref-guide ui bundle
    
    (cherry picked from commit 6292d00b3842a4e0fd67b13109cf97b44ab7aa47)
---
 solr/solr-ref-guide/README.adoc | 19 +++++++++++++++++--
 1 file changed, 17 insertions(+), 2 deletions(-)

diff --git a/solr/solr-ref-guide/README.adoc b/solr/solr-ref-guide/README.adoc
index ec8214e0796..2af44774c80 100644
--- a/solr/solr-ref-guide/README.adoc
+++ b/solr/solr-ref-guide/README.adoc
@@ -28,8 +28,6 @@ See the `../../dev-docs/ref-guide` directory for information about editing and p
 
 To ignore the Ref Guide steps when running gradle `assemble` or `check`, use either `-Prefguide.include=false` or `SOLR_REF_GUIDE_INCLUDE=false`.
 
-If you want to test any changes for the Site UI files in `ui-src`, then use either `-Prefguide.buildLocalUI=true` or `SOLR_REF_GUIDE_BUILD_LOCAL_UI=true` when building the local or official site.
-
 In order to build the official ref guide, run `./gradlew buildOfficialSite`. It will also be built under `build/site/`.
 Note, this will not include any local changes to the ref guide, just what is published to git.
 By default it will not include prerelase versions (the `main` and `branch_*x` branches), just the release versions (i.e. `branch_x_y`).
@@ -38,3 +36,20 @@ This is the option that is used when generating the nightlies refGuide release.
 
 **WARNING: NEVER run the "setOfficialAntoraYaml" task yourself. This is a job the release manager does as a part of the release process.
 The dependency versions in the antora.yml will be updated at release time, it is not meant to be kept up to date between releases.**
+
+== Changing the UI Bundle
+
+Antora uses a `ui-bundle` to create a website out of the asciidoctor pages.
+We use the https://gitlab.com/antora/antora-ui-default/[Default Antora UI] with overrides given in the `ui-src/` directory.
+
+If you want to test any changes for the Site UI files in `ui-src/`, then use either `-Prefguide.buildLocalUI=true` or `SOLR_REF_GUIDE_BUILD_LOCAL_UI=true` when building the local or official site locally.
+If you commit these changes to the `main` branch, then you must run a https://ci-builds.apache.org/job/Solr/job/Solr-reference-guide-ui-bundle/[Jenkins Job] to update this file in the nightlies server.
+Once you run this job, you need to run the jenkins job to rebuild the ref-guide as well.
+That job is run nightly, so you could also just wait.
+
+If you want to update, add or delete any file in `ui-src/`, please comment in-place that you are making a change.
+If you are changing a file that already exists in the default UI, but not in `ui-src/`, download the file from the default UI repo to the correct directory under `ui-src/` first.
+
+You can find examples throughout the existing files in the directory.
+Without these comments it will be extremely hard for us to rebase our local versions of the files with the upstream default Antora UI when the time comes.
+