nick-boss-tech opened a new pull request, #5230: URL: https://github.com/apache/solr/pull/5230
🤖 *AI text below* 🤖 *(reviewed by Nick Shanin)* https://issues.apache.org/jira/browse/SOLR-17988 ## What happens today **Several Solr 10.0 changes are missing from the upgrade notes and the Reference Guide, so an upgrading user has no way to find them.** Environment variables renamed or removed in 10.0 are silently ignored. The 10.0 start scripts do not read `SOLR_PORT`, `SOLR_HOST`, `SOLR_REQUESTLOG_ENABLED`, `SOLR_ADMIN_UI_DISABLED`, or `SOLR_WAIT_FOR_ZK`, and they print no warning. The upgrade note describes `SOLR_HOST` as "deprecated", although 10.0 no longer reads it at all. The port pages still describe `SOLR_PORT`: the stop port and RMI port in the control-script reference are derived from `SOLR_PORT_LISTEN`, and the cluster upgrade guide tells users to set `SOLR_PORT`. The SSL client authentication system properties were renamed: `solr.jetty.ssl.needClientAuth` is now `solr.jetty.ssl.need.client.auth.enabled`, and `solr.jetty.ssl.wantClientAuth` is now `solr.jetty.ssl.want.client.auth.enabled`. Neither old name has an alias, so setting it has no effect. The new Admin UI switches (`SOLR_UI_ENABLED`, `SOLR_UI_EXPERIMENTAL_ENABLED`) are documented nowhere; they control only the new Admin UI module, while the classic Admin UI is controlled by `solr.ui.enabled`. ## What this change does **Documentation only, in three pages.** [major-changes-in-solr-10.adoc](https://github.com/nick-boss-tech/solr/blob/6d2f34fb52e53f716fc66f1254924f74521967c2/solr/solr-ref-guide/modules/upgrade-notes/pages/major-changes-in-solr-10.adoc) gains the removed environment variables with their replacements, the Admin UI switches, the SSL client authentication renames, and one sentence on `bin/postlogs`. [solr-control-script-reference.adoc](https://github.com/nick-boss-tech/solr/blob/6d2f34fb52e53f716fc66f1254924f74521967c2/solr/solr-ref-guide/modules/deployment-guide/pages/solr-control-script-reference.adoc) now names `SOLR_PORT_LISTEN` in its port and stop-port text. [upgrading-a-solr-cluster.adoc](https://github.com/nick-boss-tech/solr/blob/6d2f34fb52e53f716fc66f1254924f74521967c2/solr/solr-ref-guide/modules/deployment-guide/pages/upgrading-a-solr-cluster.adoc) replaces its three `SOLR_PORT` references with `SOLR_PORT_LISTEN`. No code or script changes. One audit finding was corrected along the way: the suggested replacement for `SOLR_WAIT_FOR_ZK` was `SOLR_CLOUD_WAIT_FOR_ZK_SECONDS`, but no 10.0 script reads that variable, so the note points to the system property `solr.cloud.wait.for.zk.seconds` instead. ## Proof **The Reference Guide builds clean with these pages, and every statement was checked against both source trees.** The evidence for each entry is a line-by-line check of the Solr 9.10.1 and 10.0.0 trees: which names the 10.0 scripts and code read, and which they no longer read. The standalone Ref Guide build (`:solr:solr-ref-guide:buildLocalSite`) ran successfully at head `16d3005293d` on 2026-10-24. The one commit since then removes a working draft file that is not part of the guide. This is a documentation-only change, so no code tests apply. ## A choice to check **The notes list the removed environment variables; the alternative is for the start scripts to warn when one of them is set.** The scripts already warn for `SOLR_JETTY_HOST`, so the pattern exists in the codebase. A warning would catch the mistake at startup instead of in the upgrade notes, at the cost of a code change in the start scripts and a test for it. This PR is documentation only, and my recommendation is that the note is enough here: the names and their replacements are now written down where an upgrading user looks. If you would rather the scripts warn as well, that belongs in its own ticket as a code change, and I am happy to open it. Was limiting this PR to the documentation the right call? ## Limits Thirty further system properties are not in the Reference Guide. They are mostly socket, buffer, and pool tuning; a separate PR stacking on this one covers the operator-facing subset. The sample text in `solr.in.sh` says `SOLR_UI_ENABLED` disables the Admin UI, and the code does not do that; that is a code-comment fix and is not in this PR. *AI-generated description. Nick Shanin directed the work and takes responsibility for this contribution.* -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
