janhoy commented on code in PR #5190: URL: https://github.com/apache/solr/pull/5190#discussion_r4359630507
########## solr/solr-ref-guide/modules/deployment-guide/pages/cli/index.adoc: ########## @@ -97,12 +101,12 @@ These are the changes in default CLI behavior as compared to 9.x and 10.1. * On a sub-command, `-v` means `--verbose`; only the top-level `bin/solr` accepts `-v` as a request for the version. * `bin/solr config` has no `-v` short form for `--value`, because `-v` means `--verbose`; use `--value`. - The default implementation accepts `-v` for it. + The legacy CLI accepts `-v` for it. Review Comment: It's dangerous to use a term like **legacy**, in this context we could perhaps say that before Solr 10.2 `-v` was a short-hand for value for the config command, but not any more. The **legacy** comment is general for any other place it may have been used. Also, I'm not sure that "migration changes" even belong in this doc page. It will duplicate the upgrade notes in major-changes-in-solr-10, section 10.2. so I'd prefer if we just do a WARNING callout on this page with a link to that upgrade notes section, and document all deliberate breaking changes for PicoCLI there only. ########## solr/solr-ref-guide/modules/deployment-guide/pages/solr-control-script-reference.adoc: ########## @@ -29,8 +29,8 @@ More examples of SolrCLI in use are available throughout this Guide, particularl ==== This page documents the `bin/solr` script as it behaves by default. -An experimental re-implementation of the command line interface, built on picocli, is also included in this release. -It is disabled by default, and the options it accepts differ in places from those documented here. +A re-implementation of the command line interface, built on picocli, is also included in this release. +It is enabled by default, and the options it accepts differ in places from those documented here. See xref:cli/index.adoc[] if you would like to try it. ==== Review Comment: I'm still sceptical to keeping such a large CLI usage block this prominent when it does not apply (fully) to the default CLI that 99% will be using. Could we move the section to a new sub page "Commons-CLI command reference"? That page could describe the escape hatch and document the old behavior. ########## solr/solr-ref-guide/modules/deployment-guide/pages/cli/index.adoc: ########## @@ -38,9 +42,9 @@ SOLR_TOOL_OPTS="-Dsolr.picocli=false" bin/solr status ---- -== List of Commands +== Commands -These following commands now have a reference page generated from their source annotations. +Each command has a reference page generated from its source annotations. Review Comment: An end user won't know what a "source annotation" is. The ref guide is for end users, we should describe what they see, the commands they write and the response they get back, not code-level things. -- 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]
