Jan Høydahl created SOLR-18518:
----------------------------------
Summary: Port Snapshot tools to PicoCli
Key: SOLR-18518
URL: https://issues.apache.org/jira/browse/SOLR-18518
Project: Solr
Issue Type: Improvement
Components: cli
Reporter: Jan Høydahl
Port {{SnapshotCreateTool}}, {{SnapshotDeleteTool}}, {{SnapshotListTool}},
{{SnapshotDescribeTool}} and {{SnapshotExportTool}} to picocli. One issue and
one PR, because they share an option surface and a restructuring decision.
*Covers:* a new {{bin/solr snapshot <sub-command>}} group, replacing the five
top-level {{snapshot-*}} commands
h3. Restructure into sub-commands
Rather than five sibling top-level commands, these become a sub-command group
following the {{ZkTool}} pattern — a small parent {{SnapshotTool}} carrying
{{@Command(subcommands = \{...\})}}, a {{HelpMixin}}, and a {{call()}} that
prints usage:
* {{bin/solr snapshot create \-c <collection> \-\-snapshot-name <snapshot>}}
* {{bin/solr snapshot delete \-c <collection> \-\-snapshot-name <snapshot>}}
* {{bin/solr snapshot list \-c <collection>}}
* {{bin/solr snapshot describe \-c <collection> \-\-snapshot-name <snapshot>}}
* {{bin/solr snapshot export \-c <collection> \-\-snapshot-name <snapshot>
\-\-dest-dir <dir> \-\-backup-repo-name <repo> \-\-async-id <id>}}
Every one takes {{\-c}} / {{\-\-name}}, and all but {{list}} take
{{\-\-snapshot-name}}, so a small shared {{@Mixin}} for that pair is the
natural first step.
h3. Keep the old spellings working, hidden
Implement the five existing top-level commands — {{snapshot-create}},
{{snapshot-delete}}, {{snapshot-list}}, {{snapshot-describe}},
{{snapshot-export}} — as thin shims that delegate to the new sub-commands, so
existing scripts keep working. They should be:
* {{@Deprecated(since = "<the version the PR actually lands in>")}} from the
outset — read the current {{baseVersion}} in {{build.gradle}} when you write
the patch rather than assuming a number, since this issue may well be picked up
after the next major is cut;
* {{hidden = true}}, so they appear neither in {{\-\-help}} output nor in the
generated ref-guide pages;
* removed in the major release following the one they are deprecated in.
If a shim turns out not to be workable for some command, say so on this issue
rather than dropping back-compat silently.
h3. Document the break
This is a user-visible change to a documented command surface, so add an
upgrade note to the {{major-changes-in-solr-<N>.adoc}} page under
{{solr/solr-ref-guide/modules/upgrade-notes/pages/}} for whichever major
version the change lands in, stating that the {{snapshot-*}} commands are
deprecated in favour of {{bin/solr snapshot <sub-command>}} and naming the
release in which they will be removed. The changelog entry should call it out
too.
*Acceptance criteria*
* The new {{bin/solr snapshot <sub-command>}} group and all its options work
with {{SOLR_PICOCLI=true}}, and the commons-cli path is left behaviourally
unchanged.
* The five {{snapshot-*}} spellings still work as hidden, deprecated shims.
* Picocli test twins subclass the existing tests and override only the
{{runTool}} hook, so the inherited assertions run through both parsers.
* The upgrade note and changelog entry are included.
* {{./gradlew :solr:solr-ref-guide:generateCliDocs}} is re-run and the
generated CLI pages are committed, so {{checkCliDocsUpToDate}} passes.
Note: this issue is deliberately *not* labelled {{newdev}} — the back-compat
design decision makes it a poor first task.
*AI assistance:* a coding-agent prompt template encoding the patterns already
established by the ported tools is available at
[https://gist.github.com/janhoy/a3fe0dbcaadf24b3493558946cc549d9] — name the
five {{Snapshot*Tool}} classes in its Assignment line up front and the rest of
the prompt adapts. Please review agent output as carefully as hand-written code.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
