From 5b1f2eab6acb48472310af13a10d793119fd26fe Mon Sep 17 00:00:00 2001 From: Feynman Zhou Date: Fri, 27 Oct 2023 11:58:19 +0800 Subject: [PATCH 01/21] update plugin spec Signed-off-by: Feynman Zhou --- specs/commandline/plugin.md | 65 +++++++++++++++++++++++++++++-------- 1 file changed, 51 insertions(+), 14 deletions(-) diff --git a/specs/commandline/plugin.md b/specs/commandline/plugin.md index be34979ef..713f767cf 100644 --- a/specs/commandline/plugin.md +++ b/specs/commandline/plugin.md @@ -2,7 +2,7 @@ ## Description -Use `notation plugin` to manage plugins. See notation [plugin documentation](https://github.com/notaryproject/notaryproject/blob/main/specs/plugin-extensibility.md) for more details. The `notation plugin` command by itself performs no action. In order to operate on a plugin, one of the subcommands must be used. +Use `notation plugin` to manage plugins. See notation [plugin documentation](https://github.com/notaryproject/notaryproject/blob/main/specs/plugin-extensibility.md) for more details. The `notation plugin` command by itself performs no action. In order to manage notation plugins, one of the subcommands must be used. ## Outline @@ -17,7 +17,8 @@ Usage: Available Commands: list List installed plugins install Installs a plugin - remove Removes a plugin + uninstall Uninstall a plugin + upgrade Upgrade a plugin Flags: -h, --help help for plugin @@ -41,51 +42,87 @@ Aliases: ### notation plugin install ```text -Installs a plugin +Install a plugin Usage: - notation plugin install [flags] + notation plugin install [flags] Flags: -h, --help help for install -f, --force force the installation of a plugin - + --checksum verify the checksum digest of a plugin + --source string the location of plugin installation file, options: "file", "url","registry" (default "file") Aliases: install, add ``` -### notation plugin remove +### notation plugin uninstall ```text -Removes a plugin +Uninstall a plugin Usage: - notation plugin remove [flags] + notation plugin uninstall [flags] Flags: -h, --help help for remove Aliases: - remove, rm, uninstall, delete + remove, rm, uninstall ``` ## Usage -### Install a plugin +## Install a plugin + +### Install a plugin from a local file + +```shell +$ notation plugin install --checksum +``` + +Upon successful execution, the plugin is copied to plugin directory. The name and version of the installed plugin is displayed as follows. + +```console +Successfully installed plugin , version +``` + +If the plugin directory does not exist, it will be created. When an existing plugin is detected and the version is the same as the installing plugin, it fails to install and returns the error as follows. Users can use a flag `--force` to skip version check and force the installation a specified version. + +```console +Error: failed to install the plugin, already installed +``` + +### Install a plugin from URL ```shell -notation plugin install +$ notation plugin install --source url --checksum ``` -Upon successful execution, the plugin is copied to plugins directory and name+version of plugin is displayed. If the plugin directory does not exist, it will be created. When an existing plugin is detected, the versions are compared and if the existing plugin is a lower version then it is replaced by the newer version. +### Install a plugin as an OCI artifact from a registry + +```shell +$ notation plugin install --source registry +``` ### Uninstall a plugin ```shell -notation plugin remove +notation plugin uninstall ``` -Upon successful execution, the plugin is removed from the plugins directory. If the plugin is not found, an error is returned showing the syntax for the plugin list command to show the installed plugins. +Upon successful execution, the plugin is uninstalled from the plugin directory. + +``` +Are you sure you want to uninstall plugin ""? [y/N] y +Successfully uninstalled +``` + +If the plugin is not found, an error is returned showing the syntax for the plugin list command to show the installed plugins. + +``` +Error: does not exist +``` ### List installed plugins From 7656cffee29a356c56b4bfd90c79387e5b479a75 Mon Sep 17 00:00:00 2001 From: Feynman Zhou Date: Wed, 1 Nov 2023 15:40:09 +0800 Subject: [PATCH 02/21] update plugin spec based on the comments Signed-off-by: Feynman Zhou --- specs/commandline/plugin.md | 31 ++++++++++++++++++------------- 1 file changed, 18 insertions(+), 13 deletions(-) diff --git a/specs/commandline/plugin.md b/specs/commandline/plugin.md index 713f767cf..ad89a227b 100644 --- a/specs/commandline/plugin.md +++ b/specs/commandline/plugin.md @@ -18,7 +18,6 @@ Available Commands: list List installed plugins install Installs a plugin uninstall Uninstall a plugin - upgrade Upgrade a plugin Flags: -h, --help help for plugin @@ -45,12 +44,12 @@ Aliases: Install a plugin Usage: - notation plugin install [flags] + notation plugin install [flags] Flags: -h, --help help for install -f, --force force the installation of a plugin - --checksum verify the checksum digest of a plugin + --checksum string must match SHA256 of the plugin source --source string the location of plugin installation file, options: "file", "url","registry" (default "file") Aliases: install, add @@ -62,11 +61,11 @@ Aliases: Uninstall a plugin Usage: - notation plugin uninstall [flags] + notation plugin uninstall [flags] Flags: -h, --help help for remove - + -y, --yes do not prompt for confirmation Aliases: remove, rm, uninstall ``` @@ -75,10 +74,10 @@ Aliases: ## Install a plugin -### Install a plugin from a local file +### Install a plugin from a file system ```shell -$ notation plugin install --checksum +$ notation plugin install --file --checksum ``` Upon successful execution, the plugin is copied to plugin directory. The name and version of the installed plugin is displayed as follows. @@ -87,7 +86,7 @@ Upon successful execution, the plugin is copied to plugin directory. The name an Successfully installed plugin , version ``` -If the plugin directory does not exist, it will be created. When an existing plugin is detected and the version is the same as the installing plugin, it fails to install and returns the error as follows. Users can use a flag `--force` to skip version check and force the installation a specified version. +If the plugin directory does not exist, it will be created. When an existing plugin is detected and the version is the same as the installing plugin, it fails to install and returns the error as follows. Users can use a flag `--force` to skip existence check and force the installation with a specified version. ```console Error: failed to install the plugin, already installed @@ -96,13 +95,13 @@ Error: failed to install the plugin, already installed ### Install a plugin from URL ```shell -$ notation plugin install --source url --checksum +$ notation plugin install --source --checksum ``` -### Install a plugin as an OCI artifact from a registry +### Install a plugin as an OCI artifact from a registry (for future iteration) ```shell -$ notation plugin install --source registry +$ notation plugin install --source registry ``` ### Uninstall a plugin @@ -113,14 +112,20 @@ notation plugin uninstall Upon successful execution, the plugin is uninstalled from the plugin directory. -``` +```shell Are you sure you want to uninstall plugin ""? [y/N] y Successfully uninstalled ``` -If the plugin is not found, an error is returned showing the syntax for the plugin list command to show the installed plugins. +Uninstall the plugin without prompt for confirmation. +```shell +notation plugin uninstall --yes ``` + +If the plugin is not found, an error is returned showing the syntax for the plugin list command to show the installed plugins. + +```shell Error: does not exist ``` From 5a149137ae0e71c16c777605e13ca1b53f2790d2 Mon Sep 17 00:00:00 2001 From: Feynman Zhou Date: Wed, 1 Nov 2023 15:41:47 +0800 Subject: [PATCH 03/21] update plugin spec based on the comments Signed-off-by: Feynman Zhou --- specs/commandline/plugin.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/commandline/plugin.md b/specs/commandline/plugin.md index ad89a227b..21e65a4a3 100644 --- a/specs/commandline/plugin.md +++ b/specs/commandline/plugin.md @@ -80,7 +80,7 @@ Aliases: $ notation plugin install --file --checksum ``` -Upon successful execution, the plugin is copied to plugin directory. The name and version of the installed plugin is displayed as follows. +Upon successful execution, the plugin is copied to Notation's plugin directory. The name and version of the installed plugin is displayed as follows. ```console Successfully installed plugin , version From 487d5ff350adda844194504d470330d600c18fab Mon Sep 17 00:00:00 2001 From: Feynman Zhou Date: Wed, 1 Nov 2023 15:44:49 +0800 Subject: [PATCH 04/21] update plugin spec based on the comments Signed-off-by: Feynman Zhou --- specs/commandline/plugin.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/specs/commandline/plugin.md b/specs/commandline/plugin.md index 21e65a4a3..f9a5d2eff 100644 --- a/specs/commandline/plugin.md +++ b/specs/commandline/plugin.md @@ -74,7 +74,7 @@ Aliases: ## Install a plugin -### Install a plugin from a file system +### Install a plugin from file system ```shell $ notation plugin install --file --checksum @@ -107,26 +107,26 @@ $ notation plugin install --source registry ### Uninstall a plugin ```shell -notation plugin uninstall +notation plugin uninstall ``` Upon successful execution, the plugin is uninstalled from the plugin directory. ```shell Are you sure you want to uninstall plugin ""? [y/N] y -Successfully uninstalled +Successfully uninstalled ``` Uninstall the plugin without prompt for confirmation. ```shell -notation plugin uninstall --yes +notation plugin uninstall --yes ``` If the plugin is not found, an error is returned showing the syntax for the plugin list command to show the installed plugins. ```shell -Error: does not exist +Error: does not exist ``` ### List installed plugins From 755272ef9cd5adf424bff949464f1873ba3fc574 Mon Sep 17 00:00:00 2001 From: Feynman Zhou Date: Wed, 1 Nov 2023 17:14:56 +0800 Subject: [PATCH 05/21] update plugin spec Signed-off-by: Feynman Zhou --- specs/commandline/plugin.md | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/specs/commandline/plugin.md b/specs/commandline/plugin.md index f9a5d2eff..1ddb56e4c 100644 --- a/specs/commandline/plugin.md +++ b/specs/commandline/plugin.md @@ -76,8 +76,16 @@ Aliases: ### Install a plugin from file system +Install a Notation plugin from file system and verify the plugin checksum. + ```shell -$ notation plugin install --file --checksum +$ notation plugin install --source file --checksum +``` + +If the user doesn't specify the `--source` flag, Notation will install the plugin from file system by default. + +```shell +$ notation plugin install --checksum ``` Upon successful execution, the plugin is copied to Notation's plugin directory. The name and version of the installed plugin is displayed as follows. @@ -94,12 +102,16 @@ Error: failed to install the plugin, already installed ### Install a plugin from URL +Install a Notation plugin from a remote shared address and verify the plugin checksum. + ```shell -$ notation plugin install --source --checksum +$ notation plugin install --source url --checksum ``` ### Install a plugin as an OCI artifact from a registry (for future iteration) +Install a Notation plugin from a registry. Users can verify the plugin's signature with `notation verify` before the plugin installation. + ```shell $ notation plugin install --source registry ``` From df157c2ccd2fc712d3af9964aaa0fc229a6c12c2 Mon Sep 17 00:00:00 2001 From: Feynman Zhou Date: Wed, 1 Nov 2023 20:42:15 +0800 Subject: [PATCH 06/21] add plugin upgrade and update plugin list output Signed-off-by: Feynman Zhou --- specs/commandline/plugin.md | 46 ++++++++++++++++++++++++++++++++++--- 1 file changed, 43 insertions(+), 3 deletions(-) diff --git a/specs/commandline/plugin.md b/specs/commandline/plugin.md index 1ddb56e4c..53ad83e94 100644 --- a/specs/commandline/plugin.md +++ b/specs/commandline/plugin.md @@ -55,6 +55,20 @@ Aliases: install, add ``` +### notation plugin upgrade + +```text +Upgrade a plugin + +Usage: + notation plugin upgrade [flags] + +Flags: + -h, --help help for install + --checksum string must match SHA256 of the plugin source + --source string the location of plugin installation file, options: "file", "url","registry" (default "file") +``` + ### notation plugin uninstall ```text @@ -97,7 +111,13 @@ Successfully installed plugin , version If the plugin directory does not exist, it will be created. When an existing plugin is detected and the version is the same as the installing plugin, it fails to install and returns the error as follows. Users can use a flag `--force` to skip existence check and force the installation with a specified version. ```console -Error: failed to install the plugin, already installed +Error: failed to install the plugin, already installed +``` + +If the entered plugin checksum digest doesn't match the published checksum, Notation will return an error message and will not start installation. + +```console +Error: failed to install the plugin, input checksum does not match the published checksum, expected ``` ### Install a plugin from URL @@ -116,6 +136,26 @@ Install a Notation plugin from a registry. Users can verify the plugin's signatu $ notation plugin install --source registry ``` +### Upgrade a plugin to a higher version from file system + +Upgrade a Notation plugin to a higher version from file system and verify the plugin checksum. + +```shell +$ notation plugin upgrade --source file --checksum +``` + +Upon successful execution, the plugin is copied to Notation's plugin directory. The name and version of the installed plugin is displayed as follows. + +```console +Successfully upgraded plugin to version +``` + +If the upgrade version is equal to or lower than an existing plugin, Notation will return an error message and will not start upgrade. + +```console +Error: failed to upgrade the plugin, version should be higher than +``` + ### Uninstall a plugin ```shell @@ -153,6 +193,6 @@ An example of output from `notation plugin list`: ```text NAME DESCRIPTION VERSION CAPABILITIES ERROR -azure-kv Sign artifacts with keys in Azure Key Vault v0.5.0-rc.1 [SIGNATURE_GENERATOR.RAW] -com.amazonaws.signer.notation.plugin AWS Signer plugin for Notation 1.0.290 [SIGNATURE_GENERATOR.ENVELOPE SIGNATURE_VERIFIER.TRUSTED_IDENTITY SIGNATURE_VERIFIER.REVOCATION_CHECK] +azure-kv Sign artifacts with keys in Azure Key Vault v1.0.0 Signature generation +com.amazonaws.signer.notation.plugin AWS Signer plugin for Notation 1.0.290 Signature envelope generation, Trusted Identity validation, Certificate chain revocation check ``` From 0bd9501f53a58e624f41530359a7ddce5833788d Mon Sep 17 00:00:00 2001 From: Feynman Zhou Date: Wed, 1 Nov 2023 20:48:19 +0800 Subject: [PATCH 07/21] update plugin spec Signed-off-by: Feynman Zhou --- specs/commandline/plugin.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/specs/commandline/plugin.md b/specs/commandline/plugin.md index 53ad83e94..2035abbeb 100644 --- a/specs/commandline/plugin.md +++ b/specs/commandline/plugin.md @@ -16,7 +16,8 @@ Usage: Available Commands: list List installed plugins - install Installs a plugin + install Install a plugin + upgrade Upgrade a plugin uninstall Uninstall a plugin Flags: From 49f2d6a3778771c6127ec206a67f5a9cdac8cd1f Mon Sep 17 00:00:00 2001 From: Feynman Zhou Date: Thu, 2 Nov 2023 22:41:23 +0800 Subject: [PATCH 08/21] update plugin spec, resolve comments Signed-off-by: Feynman Zhou --- specs/commandline/plugin.md | 25 ++++++++++++++++--------- 1 file changed, 16 insertions(+), 9 deletions(-) diff --git a/specs/commandline/plugin.md b/specs/commandline/plugin.md index 2035abbeb..b95476fc8 100644 --- a/specs/commandline/plugin.md +++ b/specs/commandline/plugin.md @@ -15,10 +15,11 @@ Usage: notation plugin [command] Available Commands: - list List installed plugins install Install a plugin - upgrade Upgrade a plugin + list List installed plugins uninstall Uninstall a plugin + upgrade Upgrade a plugin + Flags: -h, --help help for plugin @@ -51,7 +52,7 @@ Flags: -h, --help help for install -f, --force force the installation of a plugin --checksum string must match SHA256 of the plugin source - --source string the location of plugin installation file, options: "file", "url","registry" (default "file") + --source string the plugin installation source, options: "file", "url","registry" (default "file") Aliases: install, add ``` @@ -65,9 +66,9 @@ Usage: notation plugin upgrade [flags] Flags: - -h, --help help for install + -h, --help help for upgrade --checksum string must match SHA256 of the plugin source - --source string the location of plugin installation file, options: "file", "url","registry" (default "file") + --source string the plugin installation source, options: "file", "url","registry" (default "file") ``` ### notation plugin uninstall @@ -94,13 +95,13 @@ Aliases: Install a Notation plugin from file system and verify the plugin checksum. ```shell -$ notation plugin install --source file --checksum +$ notation plugin install --source file --checksum ``` If the user doesn't specify the `--source` flag, Notation will install the plugin from file system by default. ```shell -$ notation plugin install --checksum +$ notation plugin install --checksum ``` Upon successful execution, the plugin is copied to Notation's plugin directory. The name and version of the installed plugin is displayed as follows. @@ -109,7 +110,7 @@ Upon successful execution, the plugin is copied to Notation's plugin directory. Successfully installed plugin , version ``` -If the plugin directory does not exist, it will be created. When an existing plugin is detected and the version is the same as the installing plugin, it fails to install and returns the error as follows. Users can use a flag `--force` to skip existence check and force the installation with a specified version. +If the plugin directory does not exist, it will be created. When an existing plugin is detected, it fails to install and returns the error as follows. Users can use a flag `--force` to skip existence check and force the installation. ```console Error: failed to install the plugin, already installed @@ -157,6 +158,12 @@ If the upgrade version is equal to or lower than an existing plugin, Notation wi Error: failed to upgrade the plugin, version should be higher than ``` +If the plugin does not exist, Notation will return an error message and will not start upgrade. + +``` +Error: failed to upgrade the plugin, version +``` + ### Uninstall a plugin ```shell @@ -179,7 +186,7 @@ notation plugin uninstall --yes If the plugin is not found, an error is returned showing the syntax for the plugin list command to show the installed plugins. ```shell -Error: does not exist +Error: does not exist. Please install the plugin using 'notation plugin install' first. ``` ### List installed plugins From 12ef65ec7bcd4435af10ba2f9b9b24f46ea42477 Mon Sep 17 00:00:00 2001 From: Feynman Zhou Date: Mon, 6 Nov 2023 23:28:59 +0800 Subject: [PATCH 09/21] update spec Signed-off-by: Feynman Zhou --- specs/commandline/plugin.md | 28 ++++++++++------------------ 1 file changed, 10 insertions(+), 18 deletions(-) diff --git a/specs/commandline/plugin.md b/specs/commandline/plugin.md index b95476fc8..2d62f751a 100644 --- a/specs/commandline/plugin.md +++ b/specs/commandline/plugin.md @@ -19,7 +19,6 @@ Available Commands: list List installed plugins uninstall Uninstall a plugin upgrade Upgrade a plugin - Flags: -h, --help help for plugin @@ -51,8 +50,8 @@ Usage: Flags: -h, --help help for install -f, --force force the installation of a plugin - --checksum string must match SHA256 of the plugin source - --source string the plugin installation source, options: "file", "url","registry" (default "file") + --checksum string must match SHA256 of the plugin source + Aliases: install, add ``` @@ -67,8 +66,7 @@ Usage: Flags: -h, --help help for upgrade - --checksum string must match SHA256 of the plugin source - --source string the plugin installation source, options: "file", "url","registry" (default "file") + --checksum string must match SHA256 of the plugin source ``` ### notation plugin uninstall @@ -83,7 +81,7 @@ Flags: -h, --help help for remove -y, --yes do not prompt for confirmation Aliases: - remove, rm, uninstall + uninstall, remove, rm ``` ## Usage @@ -92,16 +90,10 @@ Aliases: ### Install a plugin from file system -Install a Notation plugin from file system and verify the plugin checksum. - -```shell -$ notation plugin install --source file --checksum -``` - -If the user doesn't specify the `--source` flag, Notation will install the plugin from file system by default. +Install a Notation plugin from file system. ```shell -$ notation plugin install --checksum +$ notation plugin install ``` Upon successful execution, the plugin is copied to Notation's plugin directory. The name and version of the installed plugin is displayed as follows. @@ -124,10 +116,10 @@ Error: failed to install the plugin, input checksum does not match the published ### Install a plugin from URL -Install a Notation plugin from a remote shared address and verify the plugin checksum. +Install a Notation plugin from a remote shared address and verify the plugin checksum. Notation only supports installing plugins from an HTTPS URL. ```shell -$ notation plugin install --source url --checksum +$ notation plugin install --checksum ``` ### Install a plugin as an OCI artifact from a registry (for future iteration) @@ -135,7 +127,7 @@ $ notation plugin install --source url --checksum Install a Notation plugin from a registry. Users can verify the plugin's signature with `notation verify` before the plugin installation. ```shell -$ notation plugin install --source registry +$ notation plugin install /@ ``` ### Upgrade a plugin to a higher version from file system @@ -143,7 +135,7 @@ $ notation plugin install --source registry Upgrade a Notation plugin to a higher version from file system and verify the plugin checksum. ```shell -$ notation plugin upgrade --source file --checksum +$ notation plugin upgrade --checksum ``` Upon successful execution, the plugin is copied to Notation's plugin directory. The name and version of the installed plugin is displayed as follows. From 9b5b7a27d033f02634e850a3db89b840b768e12e Mon Sep 17 00:00:00 2001 From: Feynman Zhou Date: Mon, 6 Nov 2023 23:32:13 +0800 Subject: [PATCH 10/21] update spec Signed-off-by: Feynman Zhou --- specs/commandline/plugin.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/commandline/plugin.md b/specs/commandline/plugin.md index 2d62f751a..fc4528bf3 100644 --- a/specs/commandline/plugin.md +++ b/specs/commandline/plugin.md @@ -178,7 +178,7 @@ notation plugin uninstall --yes If the plugin is not found, an error is returned showing the syntax for the plugin list command to show the installed plugins. ```shell -Error: does not exist. Please install the plugin using 'notation plugin install' first. +Error: does not exist. Please check the plugin information using 'notation plugin list' first. ``` ### List installed plugins From ace5ef0158bbc5896f7ced5e8223c4c6adc90b0e Mon Sep 17 00:00:00 2001 From: Feynman Zhou Date: Wed, 8 Nov 2023 11:24:24 +0800 Subject: [PATCH 11/21] resolve comments Signed-off-by: Feynman Zhou --- specs/commandline/plugin.md | 24 ++++++++++++++++++++---- 1 file changed, 20 insertions(+), 4 deletions(-) diff --git a/specs/commandline/plugin.md b/specs/commandline/plugin.md index fc4528bf3..f9db3be30 100644 --- a/specs/commandline/plugin.md +++ b/specs/commandline/plugin.md @@ -90,7 +90,7 @@ Aliases: ### Install a plugin from file system -Install a Notation plugin from file system. +Install a Notation plugin from file system. The checksum validation is optional for this case. ```shell $ notation plugin install @@ -119,7 +119,7 @@ Error: failed to install the plugin, input checksum does not match the published Install a Notation plugin from a remote shared address and verify the plugin checksum. Notation only supports installing plugins from an HTTPS URL. ```shell -$ notation plugin install --checksum +$ notation plugin install --checksum ``` ### Install a plugin as an OCI artifact from a registry (for future iteration) @@ -135,7 +135,7 @@ $ notation plugin install /@ Upgrade a Notation plugin to a higher version from file system and verify the plugin checksum. ```shell -$ notation plugin upgrade --checksum +$ notation plugin upgrade ``` Upon successful execution, the plugin is copied to Notation's plugin directory. The name and version of the installed plugin is displayed as follows. @@ -156,6 +156,22 @@ If the plugin does not exist, Notation will return an error message and will not Error: failed to upgrade the plugin, version ``` +### Upgrade a plugin from URL + +Upgrade a Notation plugin from a remote shared address and verify the plugin checksum. Notation only supports upgrade plugins from an HTTPS URL. + +```shell +$ notation plugin upgrade --checksum +``` + +### Upgrade a plugin as an OCI artifact from a registry (for future iteration) + +Upgrade a Notation plugin from a registry. Users can verify the plugin's signature with `notation verify` before the plugin installation. + +```shell +$ notation plugin upgrade /@ +``` + ### Uninstall a plugin ```shell @@ -193,6 +209,6 @@ An example of output from `notation plugin list`: ```text NAME DESCRIPTION VERSION CAPABILITIES ERROR -azure-kv Sign artifacts with keys in Azure Key Vault v1.0.0 Signature generation +azure-kv Sign artifacts with keys in Azure Key Vault v1.0.0 Signature generation com.amazonaws.signer.notation.plugin AWS Signer plugin for Notation 1.0.290 Signature envelope generation, Trusted Identity validation, Certificate chain revocation check ``` From 9e0d216d9d61187645bfaa68b81df784fbade478 Mon Sep 17 00:00:00 2001 From: Feynman Zhou Date: Mon, 13 Nov 2023 11:11:37 +0800 Subject: [PATCH 12/21] update plugin spec Signed-off-by: Feynman Zhou --- specs/commandline/plugin.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/specs/commandline/plugin.md b/specs/commandline/plugin.md index f9db3be30..84ade958c 100644 --- a/specs/commandline/plugin.md +++ b/specs/commandline/plugin.md @@ -50,7 +50,7 @@ Usage: Flags: -h, --help help for install -f, --force force the installation of a plugin - --checksum string must match SHA256 of the plugin source + --sha256sum string must match SHA256 of the plugin source Aliases: install, add @@ -66,7 +66,7 @@ Usage: Flags: -h, --help help for upgrade - --checksum string must match SHA256 of the plugin source + --sha256sum string must match SHA256 of the plugin source ``` ### notation plugin uninstall @@ -119,7 +119,7 @@ Error: failed to install the plugin, input checksum does not match the published Install a Notation plugin from a remote shared address and verify the plugin checksum. Notation only supports installing plugins from an HTTPS URL. ```shell -$ notation plugin install --checksum +$ notation plugin install --sha256sum ``` ### Install a plugin as an OCI artifact from a registry (for future iteration) @@ -161,7 +161,7 @@ Error: failed to upgrade the plugin, version Upgrade a Notation plugin from a remote shared address and verify the plugin checksum. Notation only supports upgrade plugins from an HTTPS URL. ```shell -$ notation plugin upgrade --checksum +$ notation plugin upgrade --sha256sum ``` ### Upgrade a plugin as an OCI artifact from a registry (for future iteration) @@ -194,7 +194,7 @@ notation plugin uninstall --yes If the plugin is not found, an error is returned showing the syntax for the plugin list command to show the installed plugins. ```shell -Error: does not exist. Please check the plugin information using 'notation plugin list' first. +Error: unable to find plugin . To view a list of installed plugins, use "notation plugin list". ``` ### List installed plugins From 8217219f450ee412b7597fcbb8ec231b23186bb2 Mon Sep 17 00:00:00 2001 From: Feynman Zhou Date: Mon, 13 Nov 2023 17:55:02 +0800 Subject: [PATCH 13/21] refine the error logs Signed-off-by: Feynman Zhou --- specs/commandline/plugin.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/specs/commandline/plugin.md b/specs/commandline/plugin.md index 84ade958c..4dcbd4db0 100644 --- a/specs/commandline/plugin.md +++ b/specs/commandline/plugin.md @@ -105,7 +105,9 @@ Successfully installed plugin , version If the plugin directory does not exist, it will be created. When an existing plugin is detected, it fails to install and returns the error as follows. Users can use a flag `--force` to skip existence check and force the installation. ```console -Error: failed to install the plugin, already installed +Error: failed to install the plugin, already installed. +To view a list of installed plugins, use "notation plugin list". +To force the installation, use a flag `--force`. ``` If the entered plugin checksum digest doesn't match the published checksum, Notation will return an error message and will not start installation. @@ -152,8 +154,9 @@ Error: failed to upgrade the plugin, version should be higher than If the plugin does not exist, Notation will return an error message and will not start upgrade. -``` -Error: failed to upgrade the plugin, version +```console +Error: failed to upgrade the plugin, does not exist. +To install a plugin, use "notation plugin install". ``` ### Upgrade a plugin from URL @@ -194,7 +197,8 @@ notation plugin uninstall --yes If the plugin is not found, an error is returned showing the syntax for the plugin list command to show the installed plugins. ```shell -Error: unable to find plugin . To view a list of installed plugins, use "notation plugin list". +Error: unable to find plugin . +To view a list of installed plugins, use "notation plugin list". ``` ### List installed plugins From c226bdcf18eb7d1814c97c66c18e018d63afde3e Mon Sep 17 00:00:00 2001 From: Feynman Zhou Date: Tue, 14 Nov 2023 07:38:50 +0800 Subject: [PATCH 14/21] update plugin spec Signed-off-by: Feynman Zhou --- specs/commandline/plugin.md | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/specs/commandline/plugin.md b/specs/commandline/plugin.md index 4dcbd4db0..c5bd0b07f 100644 --- a/specs/commandline/plugin.md +++ b/specs/commandline/plugin.md @@ -65,7 +65,9 @@ Usage: notation plugin upgrade [flags] Flags: - -h, --help help for upgrade + -h, --help help for upgrade + --plugin-name string plugin name + --plugin-version plugin version --sha256sum string must match SHA256 of the plugin source ``` @@ -161,7 +163,19 @@ To install a plugin, use "notation plugin install". ### Upgrade a plugin from URL -Upgrade a Notation plugin from a remote shared address and verify the plugin checksum. Notation only supports upgrade plugins from an HTTPS URL. +When upgrading a Notation plugin from GitHub release page, Notation upgrades the plugin to the latest version by default. + +``` +$ notation plugin upgrade --plugin-name +``` + +When upgrading a Notation plugin from GitHub release page, users can also specify a plugin version to upgrade. + +``` +$ notation plugin upgrade --plugin-version +``` + +Upgrade a Notation plugin from a remote shared address (e.g, object storage) and verify the plugin checksum. Notation only supports upgrade a plugin from an HTTPS URL. ```shell $ notation plugin upgrade --sha256sum @@ -172,7 +186,7 @@ $ notation plugin upgrade --sha256sum Upgrade a Notation plugin from a registry. Users can verify the plugin's signature with `notation verify` before the plugin installation. ```shell -$ notation plugin upgrade /@ +$ notation plugin upgrade --plugin-name ``` ### Uninstall a plugin From 6687de412e562b95e45d03b41b8af2673a155f8c Mon Sep 17 00:00:00 2001 From: Feynman Zhou Date: Wed, 15 Nov 2023 16:35:31 +0800 Subject: [PATCH 15/21] update plugin spec Signed-off-by: Feynman Zhou --- specs/commandline/plugin.md | 104 +++++++----------------------------- 1 file changed, 20 insertions(+), 84 deletions(-) diff --git a/specs/commandline/plugin.md b/specs/commandline/plugin.md index c5bd0b07f..abb88f230 100644 --- a/specs/commandline/plugin.md +++ b/specs/commandline/plugin.md @@ -18,7 +18,6 @@ Available Commands: install Install a plugin list List installed plugins uninstall Uninstall a plugin - upgrade Upgrade a plugin Flags: -h, --help help for plugin @@ -48,29 +47,16 @@ Usage: notation plugin install [flags] Flags: + --file install a plugin from a local file -h, --help help for install -f, --force force the installation of a plugin - --sha256sum string must match SHA256 of the plugin source + --sha256sum string must match SHA256 of the plugin source + --url install a plugin from a remote HTTPS address Aliases: install, add ``` -### notation plugin upgrade - -```text -Upgrade a plugin - -Usage: - notation plugin upgrade [flags] - -Flags: - -h, --help help for upgrade - --plugin-name string plugin name - --plugin-version plugin version - --sha256sum string must match SHA256 of the plugin source -``` - ### notation plugin uninstall ```text @@ -92,101 +78,51 @@ Aliases: ### Install a plugin from file system -Install a Notation plugin from file system. The checksum validation is optional for this case. +Install a Notation plugin from file system. Plugin file supports `.zip` and `.tar.gz` format. The checksum validation is optional for this case. ```shell -$ notation plugin install +$ notation plugin install --file ``` -Upon successful execution, the plugin is copied to Notation's plugin directory. The name and version of the installed plugin is displayed as follows. +Upon successful execution, the plugin is copied to Notation's plugin directory. If the plugin directory does not exist, it will be created. The name and version of the installed plugin are displayed as follows. ```console Successfully installed plugin , version ``` -If the plugin directory does not exist, it will be created. When an existing plugin is detected, it fails to install and returns the error as follows. Users can use a flag `--force` to skip existence check and force the installation. - -```console -Error: failed to install the plugin, already installed. -To view a list of installed plugins, use "notation plugin list". -To force the installation, use a flag `--force`. -``` - If the entered plugin checksum digest doesn't match the published checksum, Notation will return an error message and will not start installation. ```console Error: failed to install the plugin, input checksum does not match the published checksum, expected ``` -### Install a plugin from URL - -Install a Notation plugin from a remote shared address and verify the plugin checksum. Notation only supports installing plugins from an HTTPS URL. - -```shell -$ notation plugin install --sha256sum -``` - -### Install a plugin as an OCI artifact from a registry (for future iteration) - -Install a Notation plugin from a registry. Users can verify the plugin's signature with `notation verify` before the plugin installation. - -```shell -$ notation plugin install /@ -``` - -### Upgrade a plugin to a higher version from file system - -Upgrade a Notation plugin to a higher version from file system and verify the plugin checksum. - -```shell -$ notation plugin upgrade -``` - -Upon successful execution, the plugin is copied to Notation's plugin directory. The name and version of the installed plugin is displayed as follows. +If the plugin version is higher than the existing plugin, Notation will start installation and overwrite the existing plugin. ```console -Successfully upgraded plugin to version +Successfully installed plugin , updated the version from to ``` -If the upgrade version is equal to or lower than an existing plugin, Notation will return an error message and will not start upgrade. +If the plugin version is equal to the existing plugin, Notation will not start installation and return the following message. Users can use a flag `--force` to skip plugin version check and force the installation. ```console -Error: failed to upgrade the plugin, version should be higher than +Plugin - already exists. +To view a list of installed plugins, use "notation plugin list". +If you want to install the same version, use "notation plugin uninstall" to uninstall it before re-installing the same version or use "--force" to force the installation ``` -If the plugin does not exist, Notation will return an error message and will not start upgrade. +If the plugin version is lower than the existing plugin, Notation will return an error message and will not start installation. Users can use a flag `--force` to skip plugin version check and force the installation. ```console -Error: failed to upgrade the plugin, does not exist. -To install a plugin, use "notation plugin install". -``` - -### Upgrade a plugin from URL - -When upgrading a Notation plugin from GitHub release page, Notation upgrades the plugin to the latest version by default. - -``` -$ notation plugin upgrade --plugin-name -``` - -When upgrading a Notation plugin from GitHub release page, users can also specify a plugin version to upgrade. - -``` -$ notation plugin upgrade --plugin-version -``` - -Upgrade a Notation plugin from a remote shared address (e.g, object storage) and verify the plugin checksum. Notation only supports upgrade a plugin from an HTTPS URL. - -```shell -$ notation plugin upgrade --sha256sum +Error: failed to install the plugin, plugin version is lower than the existing plugin. +To view a list of installed plugins, use "notation plugin list". +If you want to install an old version, use "notation plugin uninstall" to uninstall the existing plugin before installation or use "--force" to force the installation ``` +### Install a plugin from URL -### Upgrade a plugin as an OCI artifact from a registry (for future iteration) - -Upgrade a Notation plugin from a registry. Users can verify the plugin's signature with `notation verify` before the plugin installation. +Install a Notation plugin from a remote shared address and verify the plugin checksum. Notation only supports installing plugins from an HTTPS URL. ```shell -$ notation plugin upgrade --plugin-name +$ notation plugin install --sha256sum --url ``` ### Uninstall a plugin @@ -198,7 +134,7 @@ notation plugin uninstall Upon successful execution, the plugin is uninstalled from the plugin directory. ```shell -Are you sure you want to uninstall plugin ""? [y/N] y +Are you sure you want to uninstall plugin ""? [y/n] y Successfully uninstalled ``` From 2c98595952126d3f7bad6fbd0fcd778d7c3e136c Mon Sep 17 00:00:00 2001 From: Feynman Zhou Date: Fri, 17 Nov 2023 11:26:46 +0800 Subject: [PATCH 16/21] refine error messages Signed-off-by: Feynman Zhou --- specs/commandline/plugin.md | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/specs/commandline/plugin.md b/specs/commandline/plugin.md index abb88f230..af8baa01e 100644 --- a/specs/commandline/plugin.md +++ b/specs/commandline/plugin.md @@ -44,14 +44,14 @@ Aliases: Install a plugin Usage: - notation plugin install [flags] + notation plugin install [flags] <--file|--url> Flags: - --file install a plugin from a local file + --file install plugin from a file in file system -h, --help help for install -f, --force force the installation of a plugin --sha256sum string must match SHA256 of the plugin source - --url install a plugin from a remote HTTPS address + --url install plugin from an HTTPS URL Aliases: install, add @@ -93,7 +93,7 @@ Successfully installed plugin , version If the entered plugin checksum digest doesn't match the published checksum, Notation will return an error message and will not start installation. ```console -Error: failed to install the plugin, input checksum does not match the published checksum, expected +Error: failed to install the plugin: plugin checksum does not match user input. Expecting ``` If the plugin version is higher than the existing plugin, Notation will start installation and overwrite the existing plugin. @@ -105,17 +105,15 @@ Successfully installed plugin , updated the version from to If the plugin version is equal to the existing plugin, Notation will not start installation and return the following message. Users can use a flag `--force` to skip plugin version check and force the installation. ```console -Plugin - already exists. -To view a list of installed plugins, use "notation plugin list". -If you want to install the same version, use "notation plugin uninstall" to uninstall it before re-installing the same version or use "--force" to force the installation +Plugin with version already exists. +To view a list of installed plugins, use "notation plugin list" ``` If the plugin version is lower than the existing plugin, Notation will return an error message and will not start installation. Users can use a flag `--force` to skip plugin version check and force the installation. ```console -Error: failed to install the plugin, plugin version is lower than the existing plugin. -To view a list of installed plugins, use "notation plugin list". -If you want to install an old version, use "notation plugin uninstall" to uninstall the existing plugin before installation or use "--force" to force the installation +Error: failed to install the plugin: . The installing version is lower than the existing plugin. +To view a list of installed plugins, use "notation plugin list". It is not recommended to install older versions. Use "--force" to force the installation if you want to install an old version in a certain scenario. ``` ### Install a plugin from URL From 79ec155bc545d0f9046148449768774edd5617cd Mon Sep 17 00:00:00 2001 From: Feynman Zhou Date: Fri, 17 Nov 2023 11:52:07 +0800 Subject: [PATCH 17/21] refine plugin spec Signed-off-by: Feynman Zhou --- specs/commandline/plugin.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/specs/commandline/plugin.md b/specs/commandline/plugin.md index af8baa01e..18bec8959 100644 --- a/specs/commandline/plugin.md +++ b/specs/commandline/plugin.md @@ -47,11 +47,13 @@ Usage: notation plugin install [flags] <--file|--url> Flags: - --file install plugin from a file in file system - -h, --help help for install - -f, --force force the installation of a plugin - --sha256sum string must match SHA256 of the plugin source - --url install plugin from an HTTPS URL + -d, --debug debug mode + --file install plugin from a file in file system + --force force the installation of a plugin + -h, --help help for install + --sha256sum string must match SHA256 of the plugin source + --url install plugin from an HTTPS URL + -v, --verbose verbose mode Aliases: install, add @@ -112,8 +114,8 @@ To view a list of installed plugins, use "notation plugin list" If the plugin version is lower than the existing plugin, Notation will return an error message and will not start installation. Users can use a flag `--force` to skip plugin version check and force the installation. ```console -Error: failed to install the plugin: . The installing version is lower than the existing plugin. -To view a list of installed plugins, use "notation plugin list". It is not recommended to install older versions. Use "--force" to force the installation if you want to install an old version in a certain scenario. +Error: failed to install the plugin: . The installing version is lower than the existing plugin with version . +It is not recommended to install an older version. Use "--force" to force the installation if you want to do so. To view a list of installed plugins, use "notation plugin list" ``` ### Install a plugin from URL @@ -146,7 +148,7 @@ If the plugin is not found, an error is returned showing the syntax for the plug ```shell Error: unable to find plugin . -To view a list of installed plugins, use "notation plugin list". +To view a list of installed plugins, use "notation plugin list" ``` ### List installed plugins From 11f56b4883dabb4a9270a20fc7c824aec7ec60ce Mon Sep 17 00:00:00 2001 From: Feynman Zhou Date: Fri, 17 Nov 2023 11:52:51 +0800 Subject: [PATCH 18/21] refine plugin spec Signed-off-by: Feynman Zhou --- specs/commandline/plugin.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/commandline/plugin.md b/specs/commandline/plugin.md index 18bec8959..d4e06cf90 100644 --- a/specs/commandline/plugin.md +++ b/specs/commandline/plugin.md @@ -114,7 +114,7 @@ To view a list of installed plugins, use "notation plugin list" If the plugin version is lower than the existing plugin, Notation will return an error message and will not start installation. Users can use a flag `--force` to skip plugin version check and force the installation. ```console -Error: failed to install the plugin: . The installing version is lower than the existing plugin with version . +Error: failed to install the plugin: . The installing version is lower than the existing plugin version . It is not recommended to install an older version. Use "--force" to force the installation if you want to do so. To view a list of installed plugins, use "notation plugin list" ``` ### Install a plugin from URL From 54d8f85f82bf966a43838387a6658756d90df7e5 Mon Sep 17 00:00:00 2001 From: Feynman Zhou Date: Fri, 17 Nov 2023 17:48:21 +0800 Subject: [PATCH 19/21] resolve comments Signed-off-by: Feynman Zhou --- specs/commandline/plugin.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/specs/commandline/plugin.md b/specs/commandline/plugin.md index d4e06cf90..25277c5ad 100644 --- a/specs/commandline/plugin.md +++ b/specs/commandline/plugin.md @@ -107,19 +107,18 @@ Successfully installed plugin , updated the version from to If the plugin version is equal to the existing plugin, Notation will not start installation and return the following message. Users can use a flag `--force` to skip plugin version check and force the installation. ```console -Plugin with version already exists. -To view a list of installed plugins, use "notation plugin list" +Error: Plugin with version already exists. ``` If the plugin version is lower than the existing plugin, Notation will return an error message and will not start installation. Users can use a flag `--force` to skip plugin version check and force the installation. ```console -Error: failed to install the plugin: . The installing version is lower than the existing plugin version . -It is not recommended to install an older version. Use "--force" to force the installation if you want to do so. To view a list of installed plugins, use "notation plugin list" +Error: failed to install the plugin: . The installing plugin version is lower than the existing plugin version . +It is not recommended to install an older version. To force the installation, use the "--force" option. ``` ### Install a plugin from URL -Install a Notation plugin from a remote shared address and verify the plugin checksum. Notation only supports installing plugins from an HTTPS URL. +Installs a Notation plugin from a remote location and verify the plugin checksum. Notation only supports installing plugins from an HTTPS URL, which means that the URL must start with "https://". ```shell $ notation plugin install --sha256sum --url From 8570d71a8f522e868d3d507fed553751dfb3b679 Mon Sep 17 00:00:00 2001 From: Feynman Zhou Date: Fri, 17 Nov 2023 17:55:53 +0800 Subject: [PATCH 20/21] resolve comments Signed-off-by: Feynman Zhou --- specs/commandline/plugin.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/commandline/plugin.md b/specs/commandline/plugin.md index 25277c5ad..6aec3f18d 100644 --- a/specs/commandline/plugin.md +++ b/specs/commandline/plugin.md @@ -118,7 +118,7 @@ It is not recommended to install an older version. To force the installation, us ``` ### Install a plugin from URL -Installs a Notation plugin from a remote location and verify the plugin checksum. Notation only supports installing plugins from an HTTPS URL, which means that the URL must start with "https://". +Install a Notation plugin from a remote location and verify the plugin checksum. Notation only supports installing plugins from an HTTPS URL, which means that the URL must start with "https://". ```shell $ notation plugin install --sha256sum --url From 9481477f5d4c89c61d2190e4f7547617e5dfe52c Mon Sep 17 00:00:00 2001 From: Feynman Zhou Date: Mon, 20 Nov 2023 16:17:23 +0800 Subject: [PATCH 21/21] refine plugin spec Signed-off-by: Feynman Zhou --- specs/commandline/plugin.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/commandline/plugin.md b/specs/commandline/plugin.md index 6aec3f18d..9cfdea42e 100644 --- a/specs/commandline/plugin.md +++ b/specs/commandline/plugin.md @@ -107,7 +107,7 @@ Successfully installed plugin , updated the version from to If the plugin version is equal to the existing plugin, Notation will not start installation and return the following message. Users can use a flag `--force` to skip plugin version check and force the installation. ```console -Error: Plugin with version already exists. +Error: failed to install the plugin: with version already exists. ``` If the plugin version is lower than the existing plugin, Notation will return an error message and will not start installation. Users can use a flag `--force` to skip plugin version check and force the installation.