[
https://issues.apache.org/jira/browse/SOLR-17383?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Christos Malliaridis updated SOLR-17383:
----------------------------------------
Description:
With the changes from SOLR-16757 arguments were moved to java source code to
simplify and merge shell script logic. We noticed many overlappings in
arguments' short and long forms that cause confusion and possible unexpected
results.
Since commands are executed with "bin/solr", the user has a hard time learning
the short form of each argument and the long form of the same argument may vary
too, because it is often context-specific.
Arguments that have conflicts are:
||Short Param||Long Param||Occurences||
|{{-c}}|{{--name}}|{{HealthCheckTool, ConfigTool, CreateTool, DeleteTool,
LinkConfigTool, PostTool}}|
|{{-c}}|{{--cloud}}|{{AssertTool, RunExampleTool, bin/solr}}|
|{{-c}}|{{--collection}}|{{PackageTool, bin/solr
}}|
|{{-c}}|{{--collections}}|? (unknown if there is a short form)|
| | | |
|{{-v}}|{{--verbose}}|{{SolrCLI, bin/solr}}|
|{{-v}}|{{{{{}--value{}}}}}|{{ConfigTool}}|
|{{-V (cap)}}|{{{{{}--verbose{}}}}}|bin/solr|
|{{-v}}|{{--version}}|SolrCLI|
| |{{ }}| |
|{{-s}}|{{{{{}--shards{}}}}}|CreateTool|
|{{-s}}|{{--started}}|AssertTool|
|{{-s}}|{{--script}}|RunExampleTool|
|{{-s}}|{{--solr-url}}|bin/solr|
|{{-s}}|{{--solr-home}}|bin/solr|
| | | |
|{{-url}}|{{--solr-url}}|{{SolrCLI}}|
|(no short form)|{{--solr-url}}|{{ApiTool, StatusTool}}|
|{{-url}}|{{--solr-collection-url}}|{{PostLogsTool, ExportTool}}|
|{{-url}}|{{--solr-update-url}}|{{PostTool}}|
| | |{{ }}|
|{{-d}}|{{--conf-dir}}|{{CreateTool, ConfigSetUploadTool, bin/solr}}|
|{{-d}}|{{--delete-config}}|{{DeleteTool}}|
|{{-d}}|{{--delay}}|{{PostTool}}|
|{{-d}}|{{--server-dir}}|{{RunExampleTool}}|
|{{-d}}|{{--dir}}|{{bin/solr}}|
|{{ }}|{{ }}|{{ }}|
|{{-r}}|{{--recurse}}|{{SolrCLI}}|
|{{-r}}|{{--root}}|{{AssertTool}}|
|{{-r}}|{{--recursive}}|{{PostTool}}|
|{{ }}|{{ }}|{{ }}|
|{{-m}}|{{--memory}}|{{RunExampleTool, bin/solr}}|
|{{-m}}|{{--message}}|{{AssertTool}}|
|{{ }}|{{ }}|{{ }}|
|{{-t}}|{{--type}}|{{PostTool}}|
|{{-t}}|{{--timeout}}|{{AssertTool}}|
|{{-t}}|{{--data-home}}|{{bin/solr}}|
|{{ }}|{{ }}|{{ }}|
|{{-e}}|{{--example}}|{{bin/solr, RunExampleTool}}|
|{{-e}}|{{--exitcode}}|{{AssertTool}}|
|{{ }}|{{ }}|{{ }}|
|{{-n}}|{{--no-prompt}}|{{RunExampleTool}}|
|{{-y}}|{{--no-prompt}}|{{PackageTool}}|
|{{-noprompt}}|{{--no-prompt}}|{{bin/solr}}|
|{{-n}}|{{--conf-name}}|{{ConfigSetUploadTool, CreateTool, LinkConfigTool,
bin/solr}}|
|{{ }}|{{ }}|{{ }}|
|{{-a}}|{{--addlopts}}|{\{{{RunExampleTool (see also }}}}SOLR-16757)|
|{{-a}}|{{--additional-options}}|{{bin/solr}}|
|{{-a}}|{{-action}}|{{ConfigTool}}|
|{{ }}|{{ }}|{{ }}|
|{{-p}}|{{--port}}|{{RunExampleTool, bin/solr}}|
|{{-p}}|{{--property}}|{{ConfigTool}}|
|{{-p}}|{{--param}}|{{PackageTool}}|
|{{-p}}|{{--params}}|{{PostTool}}|
|{{ }}|{{ }}|{{ }}|
|{{-f}}|{{--force}}|{{RunExampleTool, bin/solr}}|
|{{-f}}|{{--force-delete-config}}|{{DeleteTool}}|
|{{-f}}|{{--format}}|{{PostTool}}|
|{{-f}}|{{--foreground}}|{{bin/solr}}|
|{{ }}|{{ }}|{{ }}|
|{{-h}}|{{--help}}|{{SolrCLI, bin/solr}}|
|{{-h}}|{{--host}}|{{RunExampleTool, bin/solr}}|
|{{ }}|{{ }}| |
|{{-u (not obvious)}}|{{--credentials}}|SolrCLI|
Noticable confusions for beginners may be:
*
{code:java}
bin/solr start -c -e techproducts # "creates" and starts a solr cloud instance
with example data, -c does not receive an argument
bin/solr create -c mycollection # "creates" a new collection in an existing
solr, -c requires a value{code}
*
{code:java}
bin/solr create -c mycollection # succeeds
bin/solr create --collection mycollection (fails?)
bin/solr create --name mycollection (succeeds){code}
*
{code:java}
bin/solr config -c ... --action set-user-property --property
update.autoCreateFields -v false # Does this set property to false or execute
command in verbose mode, or both{code}
We should consider for which arguments it is fine to have overlapping short
forms, which arguments can be unified and use same short and long-form to
improve learnability and which arguments should maybe not have a short form or
should use different wording to use different abbreviations.
was:
With the changes from SOLR-16757 arguments were moved to java source code to
simplify and merge shell script logic. We noticed many overlappings in
arguments' short and long forms that cause confusion and possible unexpected
results.
Since commands are executed with "bin/solr", the user has a hard time learning
the short form of each command and the long form of the same "argument" may
vary too, because it is often context-specific.
Arguments that have conflicts are:
||Short Param||Long Param||Occurences||
|{{-c}}|{{--name}}|{{HealthCheckTool, ConfigTool, CreateTool, DeleteTool,
LinkConfigTool, PostTool}}|
|{{-c}}|{{--cloud}}|{{AssertTool, RunExampleTool, bin/solr}}|
|{{-c}}|{{--collection}}|{{PackageTool, bin/solr
}}|
|{{-c}}|{{--collections}}|? (unknown if there is a short form)|
| | | |
|{{-v}}|{{--verbose}}|{{SolrCLI, bin/solr}}|
|{{-v}}|{{{{--value}}}}|{{ConfigTool}}|
|{{-V (cap)}}|{{{{--verbose}}}}|bin/solr|
|{{-v}}|{{--version}}|SolrCLI|
| |{{ }}| |
|{{-s}}|{{{{--shards}}}}|CreateTool|
|{{-s}}|{{--started}}|AssertTool|
|{{-s}}|{{--script}}|RunExampleTool|
|{{-s}}|{{--solr-url}}|bin/solr|
|{{-s}}|{{--solr-home}}|bin/solr|
| | | |
|{{-url}}|{{--solr-url}}|{{SolrCLI}}|
|(no short form)|{{--solr-url}}|{{ApiTool, StatusTool}}|
|{{-url}}|{{--solr-collection-url}}|{{PostLogsTool, ExportTool}}|
|{{-url}}|{{--solr-update-url}}|{{PostTool}}|
| | |{{ }}|
|{{-d}}|{{--conf-dir}}|{{CreateTool, ConfigSetUploadTool, bin/solr}}|
|{{-d}}|{{--delete-config}}|{{DeleteTool}}|
|{{-d}}|{{--delay}}|{{PostTool}}|
|{{-d}}|{{--server-dir}}|{{RunExampleTool}}|
|{{-d}}|{{--dir}}|{{bin/solr}}|
|{{ }}|{{ }}|{{ }}|
|{{-r}}|{{--recurse}}|{{SolrCLI}}|
|{{-r}}|{{--root}}|{{AssertTool}}|
|{{-r}}|{{--recursive}}|{{PostTool}}|
|{{ }}|{{ }}|{{ }}|
|{{-m}}|{{--memory}}|{{RunExampleTool, bin/solr}}|
|{{-m}}|{{--message}}|{{AssertTool}}|
|{{ }}|{{ }}|{{ }}|
|{{-t}}|{{--type}}|{{PostTool}}|
|{{-t}}|{{--timeout}}|{{AssertTool}}|
|{{-t}}|{{--data-home}}|{{bin/solr}}|
|{{ }}|{{ }}|{{ }}|
|{{-e}}|{{--example}}|{{bin/solr, RunExampleTool}}|
|{{-e}}|{{--exitcode}}|{{AssertTool}}|
|{{ }}|{{ }}|{{ }}|
|{{-n}}|{{--no-prompt}}|{{RunExampleTool}}|
|{{-y}}|{{--no-prompt}}|{{PackageTool}}|
|{{-noprompt}}|{{--no-prompt}}|{{bin/solr}}|
|{{-n}}|{{--conf-name}}|{{ConfigSetUploadTool, CreateTool, LinkConfigTool,
bin/solr}}|
|{{ }}|{{ }}|{{ }}|
|{{-a}}|{{--addlopts}}|{{{{RunExampleTool (see also }}}}SOLR-16757)|
|{{-a}}|{{--additional-options}}|{{bin/solr}}|
|{{-a}}|{{-action}}|{{ConfigTool}}|
|{{ }}|{{ }}|{{ }}|
|{{-p}}|{{--port}}|{{RunExampleTool, bin/solr}}|
|{{-p}}|{{--property}}|{{ConfigTool}}|
|{{-p}}|{{--param}}|{{PackageTool}}|
|{{-p}}|{{--params}}|{{PostTool}}|
|{{ }}|{{ }}|{{ }}|
|{{-f}}|{{--force}}|{{RunExampleTool, bin/solr}}|
|{{-f}}|{{--force-delete-config}}|{{DeleteTool}}|
|{{-f}}|{{--format}}|{{PostTool}}|
|{{-f}}|{{--foreground}}|{{bin/solr}}|
|{{ }}|{{ }}|{{ }}|
|{{-h}}|{{--help}}|{{SolrCLI, bin/solr}}|
|{{-h}}|{{--host}}|{{RunExampleTool, bin/solr}}|
|{{ }}|{{ }}| |
|{{-u (not obvious)}}|{{--credentials}}|SolrCLI|
Noticable confusions for beginners may be:
*
{code:java}
bin/solr start -c -e techproducts # "creates" and starts a solr cloud instance
with example data, -c does not receive an argument
bin/solr create -c mycollection # "creates" a new collection in an existing
solr, -c requires a value{code}
*
{code:java}
bin/solr create -c mycollection # succeeds
bin/solr create --collection mycollection (fails?)
bin/solr create --name mycollection (succeeds){code}
*
{code:java}
bin/solr config -c ... --action set-user-property --property
update.autoCreateFields -v false # Does this set property to false or execute
command in verbose mode, or both{code}
We should consider for which arguments it is fine to have overlapping short
forms, which arguments can be unified and use same short and long-form to
improve learnability and which arguments should maybe not have a short form or
should use different wording to use different abbreviations.
> Resolve overlapping arguments
> -----------------------------
>
> Key: SOLR-17383
> URL: https://issues.apache.org/jira/browse/SOLR-17383
> Project: Solr
> Issue Type: Improvement
> Security Level: Public(Default Security Level. Issues are Public)
> Reporter: Christos Malliaridis
> Priority: Major
>
> With the changes from SOLR-16757 arguments were moved to java source code to
> simplify and merge shell script logic. We noticed many overlappings in
> arguments' short and long forms that cause confusion and possible unexpected
> results.
> Since commands are executed with "bin/solr", the user has a hard time
> learning the short form of each argument and the long form of the same
> argument may vary too, because it is often context-specific.
> Arguments that have conflicts are:
> ||Short Param||Long Param||Occurences||
> |{{-c}}|{{--name}}|{{HealthCheckTool, ConfigTool, CreateTool, DeleteTool,
> LinkConfigTool, PostTool}}|
> |{{-c}}|{{--cloud}}|{{AssertTool, RunExampleTool, bin/solr}}|
> |{{-c}}|{{--collection}}|{{PackageTool, bin/solr
> }}|
> |{{-c}}|{{--collections}}|? (unknown if there is a short form)|
> | | | |
> |{{-v}}|{{--verbose}}|{{SolrCLI, bin/solr}}|
> |{{-v}}|{{{{{}--value{}}}}}|{{ConfigTool}}|
> |{{-V (cap)}}|{{{{{}--verbose{}}}}}|bin/solr|
> |{{-v}}|{{--version}}|SolrCLI|
> | |{{ }}| |
> |{{-s}}|{{{{{}--shards{}}}}}|CreateTool|
> |{{-s}}|{{--started}}|AssertTool|
> |{{-s}}|{{--script}}|RunExampleTool|
> |{{-s}}|{{--solr-url}}|bin/solr|
> |{{-s}}|{{--solr-home}}|bin/solr|
> | | | |
> |{{-url}}|{{--solr-url}}|{{SolrCLI}}|
> |(no short form)|{{--solr-url}}|{{ApiTool, StatusTool}}|
> |{{-url}}|{{--solr-collection-url}}|{{PostLogsTool, ExportTool}}|
> |{{-url}}|{{--solr-update-url}}|{{PostTool}}|
> | | |{{ }}|
> |{{-d}}|{{--conf-dir}}|{{CreateTool, ConfigSetUploadTool, bin/solr}}|
> |{{-d}}|{{--delete-config}}|{{DeleteTool}}|
> |{{-d}}|{{--delay}}|{{PostTool}}|
> |{{-d}}|{{--server-dir}}|{{RunExampleTool}}|
> |{{-d}}|{{--dir}}|{{bin/solr}}|
> |{{ }}|{{ }}|{{ }}|
> |{{-r}}|{{--recurse}}|{{SolrCLI}}|
> |{{-r}}|{{--root}}|{{AssertTool}}|
> |{{-r}}|{{--recursive}}|{{PostTool}}|
> |{{ }}|{{ }}|{{ }}|
> |{{-m}}|{{--memory}}|{{RunExampleTool, bin/solr}}|
> |{{-m}}|{{--message}}|{{AssertTool}}|
> |{{ }}|{{ }}|{{ }}|
> |{{-t}}|{{--type}}|{{PostTool}}|
> |{{-t}}|{{--timeout}}|{{AssertTool}}|
> |{{-t}}|{{--data-home}}|{{bin/solr}}|
> |{{ }}|{{ }}|{{ }}|
> |{{-e}}|{{--example}}|{{bin/solr, RunExampleTool}}|
> |{{-e}}|{{--exitcode}}|{{AssertTool}}|
> |{{ }}|{{ }}|{{ }}|
> |{{-n}}|{{--no-prompt}}|{{RunExampleTool}}|
> |{{-y}}|{{--no-prompt}}|{{PackageTool}}|
> |{{-noprompt}}|{{--no-prompt}}|{{bin/solr}}|
> |{{-n}}|{{--conf-name}}|{{ConfigSetUploadTool, CreateTool, LinkConfigTool,
> bin/solr}}|
> |{{ }}|{{ }}|{{ }}|
> |{{-a}}|{{--addlopts}}|{\{{{RunExampleTool (see also }}}}SOLR-16757)|
> |{{-a}}|{{--additional-options}}|{{bin/solr}}|
> |{{-a}}|{{-action}}|{{ConfigTool}}|
> |{{ }}|{{ }}|{{ }}|
> |{{-p}}|{{--port}}|{{RunExampleTool, bin/solr}}|
> |{{-p}}|{{--property}}|{{ConfigTool}}|
> |{{-p}}|{{--param}}|{{PackageTool}}|
> |{{-p}}|{{--params}}|{{PostTool}}|
> |{{ }}|{{ }}|{{ }}|
> |{{-f}}|{{--force}}|{{RunExampleTool, bin/solr}}|
> |{{-f}}|{{--force-delete-config}}|{{DeleteTool}}|
> |{{-f}}|{{--format}}|{{PostTool}}|
> |{{-f}}|{{--foreground}}|{{bin/solr}}|
> |{{ }}|{{ }}|{{ }}|
> |{{-h}}|{{--help}}|{{SolrCLI, bin/solr}}|
> |{{-h}}|{{--host}}|{{RunExampleTool, bin/solr}}|
> |{{ }}|{{ }}| |
> |{{-u (not obvious)}}|{{--credentials}}|SolrCLI|
> Noticable confusions for beginners may be:
> *
> {code:java}
> bin/solr start -c -e techproducts # "creates" and starts a solr cloud
> instance with example data, -c does not receive an argument
> bin/solr create -c mycollection # "creates" a new collection in an existing
> solr, -c requires a value{code}
> *
> {code:java}
> bin/solr create -c mycollection # succeeds
> bin/solr create --collection mycollection (fails?)
> bin/solr create --name mycollection (succeeds){code}
> *
> {code:java}
> bin/solr config -c ... --action set-user-property --property
> update.autoCreateFields -v false # Does this set property to false or execute
> command in verbose mode, or both{code}
> We should consider for which arguments it is fine to have overlapping short
> forms, which arguments can be unified and use same short and long-form to
> improve learnability and which arguments should maybe not have a short form
> or should use different wording to use different abbreviations.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscr...@solr.apache.org
For additional commands, e-mail: issues-h...@solr.apache.org
