doc(spec): add subcommands to Notation plugin spec

[duffney]

Spec changes to improve the UX for plugin installation and removal using the NotationCLI.

[shizhMSFT]

Linking the parent issue #549

[codecov-commenter]

Codecov Report

Merging #555 (378e92c) into main (54b42cb) will decrease coverage by 1.98%.
The diff coverage is n/a.

📣 This organization is not using Codecov’s GitHub App Integration. We recommend you install it so Codecov can continue to function properly for your repositories. Learn more

@@            Coverage Diff             @@
##             main     #555      +/-   ##
==========================================
- Coverage   36.34%   34.36%   -1.98%     
==========================================
  Files          30       32       +2     
  Lines        1607     1848     +241     
==========================================
+ Hits          584      635      +51     
- Misses       1002     1192     +190     
  Partials       21       21              

see 4 files with indirect coverage changes

📣 We’re building smart automated test selection to slash your CI/CD build times. Learn more

[yizha1]

@duffney Could you fix the DCO issue, see below check results.

[yizha1]

@duffney Could you resolve the comments, so that we can move on?

[duffney]

@duffney Could you resolve the comments, so that we can move on?

I resolved the open comments, but there are a few unanswered questions around the --plugin-name argument. Mainly around what to do when the option isn't provided and how notation would handle plugin-names that doesn't follow the naming standard.

[yizha1]

@duffney Could you resolve the comments, so that we can move on?

I resolved the open comments, but there are a few unanswered questions around the --plugin-name argument. Mainly around what to do when the option isn't provided and how notation would handle plugin-names that doesn't follow the naming standard.

@duffney I think it is connected to the previous comment from Shiwei, see here #555 (comment). The --plugin-name is optional and used to confirm it is the plugin that users want to install. That is to say, Users cannot use a different name for the plugin. I would suggest the explanation text for the --plugin-name would be used for confirming it is the right plugin, not a new name that users can use.

Here is a copy with additional comments added from me. IMO, Case-1 is the most common case.

Case-1: Name is retrieved from the plugin metadata, but need users to confirm it is the right one.
$ notation plugin install notation-example-foo.tgz
The NEW plugin example-foo will be installed.
Do you want to continue? [y/N] y
The plugin example-foo is successfully installed.

Case-2: users specify the name which is the same as the name from plugin metadata, then it will be installed directly
$ notation plugin install --name example-bar notation-example-bar.tgz
The plugin example-bar is successfully installed.

Case-3: users specify the name, which is not the same from plugin metadata
$ notation plugin install --name example-hello notation-example-foo.tgz
Error: notation-example-foo.tgz: example-hello not found

[yizha1]

@duffney Could you resolve the comments? The RC-4 release (Previous RC-3) is planned by end of this Month. Hope we can get the spec merged next week, then we can start the implementation.

[duffney]

@duffney Could you resolve the comments, so that we can move on?

I resolved the open comments, but there are a few unanswered questions around the --plugin-name argument. Mainly around what to do when the option isn't provided and how notation would handle plugin-names that doesn't follow the naming standard.

@duffney I think it is connected to the previous comment from Shiwei, see here #555 (comment). The --plugin-name is optional and used to confirm it is the plugin that users want to install. That is to say, Users cannot use a different name for the plugin. I would suggest the explanation text for the --plugin-name would be used for confirming it is the right plugin, not a new name that users can use.

Here is a copy with additional comments added from me. IMO, Case-1 is the most common case.

Case-1: Name is retrieved from the plugin metadata, but need users to confirm it is the right one. $ notation plugin install notation-example-foo.tgz The NEW plugin example-foo will be installed. Do you want to continue? [y/N] y The plugin example-foo is successfully installed.

Case-2: users specify the name which is the same as the name from plugin metadata, then it will be installed directly $ notation plugin install --name example-bar notation-example-bar.tgz The plugin example-bar is successfully installed.

Case-3: users specify the name, which is not the same from plugin metadata $ notation plugin install --name example-hello notation-example-foo.tgz Error: notation-example-foo.tgz: example-hello not found

@yizha1 having the name option confirm the correct plugin name makes perfect sense to me, thanks for the clarification. :)

[shizhMSFT]

LGTM

[patrickzheng200]

LGTM

[JeyJeyGao]

LGTM

[patrickzheng200]

LGTM

[priteshbandi]

LGTM with a nitpick that Shiwei called out.

[shizhMSFT]

LGTM

[patrickzheng200]

LGTM