doc: update sign.md for OCI image manifest support (notaryproject#540)

updates: - Update the flag name per community discussion - Update the description for using OCI image manifest Signed-off-by: Yi Zha <[email protected]>
patrickzheng200 · Feb 9, 2023 · 86aeb0c · 86aeb0c
1 parent 4f573af
commit 86aeb0c
Showing 1 changed file with 17 additions and 25 deletions.
diff --git a/specs/commandline/sign.md b/specs/commandline/sign.md
@@ -28,25 +28,27 @@ Usage:
   notation sign [flags] <reference>
 
 Flags:
-  -d,  --debug                       debug mode
-  -e,  --expiry duration             optional expiry that provides a "best by use" time for the artifact. The duration is specified in minutes(m) and/or hours(h). For example: 12h, 30m, 3h20m
-  -h,  --help                        help for sign
-  -k,  --key string                  signing key name, for a key previously added to notation's key list.
-  -p,  --password string             password for registry operations (default to $NOTATION_PASSWORD if not specified)
-       --plain-http                  registry access via plain HTTP
-       --plugin-config stringArray   {key}={value} pairs that are passed as it is to a plugin, refer plugin's documentation to set appropriate values
-       --signature-format string     signature envelope format, options: 'jws', 'cose' (default "jws")
-       --signature-manifest string   manifest type for signatures. options: artifact, image (default "artifact")
-  -u,  --username string             username for registry operations (default to $NOTATION_USERNAME if not specified)
-  -m,  --user-metadata stringArray   {key}={value} pairs that are added to the signature payload
-  -v,  --verbose                  verbose mode
+  -d,  --debug                      debug mode
+  -e,  --expiry duration            optional expiry that provides a "best by use" time for the artifact. The duration is specified in minutes(m) and/or hours(h). For example: 12h, 30m, 3h20m
+  -h,  --help                       help for sign
+  -k,  --key string                 signing key name, for a key previously added to notation's key list.
+  -p,  --password string            password for registry operations (default to $NOTATION_PASSWORD if not specified)
+       --plain-http                 registry access via plain HTTP
+       --plugin-config stringArray  {key}={value} pairs that are passed as it is to a plugin, refer plugin's documentation to set appropriate values
+       --signature-format string    signature envelope format, options: "jws", "cose" (default "jws")
+       --signature-manifest string  manifest type for signature, options: "image", "artifact" (default "artifact")
+  -u,  --username string            username for registry operations (default to $NOTATION_USERNAME if not specified)
+  -m,  --user-metadata stringArray  {key}={value} pairs that are added to the signature payload
+  -v,  --verbose                    verbose mode
 ```
 
 ## Use OCI image manifest to store signatures
 
-By default, Notation uses [OCI artifact manifest][oci-artifact-manifest] to store signatures in registries. For backward compatibility, Notation supports using `OCI image manifest` to store signatures in registries that partially implement the [OCI Image specification v1.1][oci-image-spec]. Use flag `--signature-manifest image` to force Notation to store the signatures using OCI image manifest.
+By default, Notation uses [OCI artifact manifest][oci-artifact-manifest] to store signatures in registries. For registries that don't support `OCI artifact` or [Referrers API][oci-referers-api] is not enabled, users SHOULD use flag `--signature-manifest image` to force Notation to store the signatures using [OCI image manifest][oci-image-spec].
 
-Registries MAY not implement or enable the `Referrers API`, which is used by clients to fetch referrers. In the context of Notation, the referrers are signatures. Notation follows the fallback procedure defined in [OCI distribution spec][oci-backward-compatibility] if `Referrers API` is unavailable.
+Note that there is no deterministic way to determine whether a registry supports `OCI artifact` or not. The following response status contained in error messages MAY indicate that the registry doesn't support `OCI artifact`.
+
+- Response status `400 BAD Request` with error code `MANIFEST_INVALID` or `UNSUPPORTED`
 
 ### Set config property for OCI image manifest
 
@@ -62,14 +64,6 @@ Notation uses empty JSON object `{}` as the default configuration content, and t
 }
 ```
 
-### When to use OCI image manifest
-
-[Registry support][registry-support] lists registries with different compatibilities. For registries not supporting `OCI artifact manifest`, users can use flag `--signature-manifest image` to sign artifacts stored in those registries.
-
-For registries not listed in the page, users can consider using flag `--signature-manifest image` by checking the error message. Note that there is no deterministic way to determine whether a registry supports `OCI artifact manifest` or not. The error message is just for reference. The following response status contained in error messages MAY indicate that the registry doesn't support `OCI artifact manifest`:
-
-- Response status `400 BAD Request` with error code `MANIFEST_INVALID` or `UNSUPPORTED`
-
 ## Usage
 
 ### Sign an OCI artifact
@@ -168,6 +162,4 @@ notation sign --signature-manifest image <registry>/<repository>@<digest>
 
 [oci-artifact-manifest]: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc2/artifact.md
 [oci-image-spec]: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc2/spec.md
-[oci-backward-compatibility]: https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc1/spec.md#backwards-compatibility
-[registry-support]: https://notaryproject.dev/docs/registrysupport/
-[oras-land]: https://oras.land/
+[oci-referers-api]: https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc1/spec.md#listing-referrers