Apache Solr open-source search software
Add docs for updating the ref-guide ui bundle
Houston Putman6292d00b3842
diff --git a/solr/solr-ref-guide/README.adoc b/solr/solr-ref-guide/README.adocindex 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 pTo 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.+