From 4cc8ea3a1cdf811d2dec614379ac2b5c0bf6a407 Mon Sep 17 00:00:00 2001
From: Samir Kakkar <83560495+iamsamirzon@users.noreply.github.com>
Date: Tue, 17 Jan 2023 16:30:00 -0800
Subject: [PATCH 1/2] Update sign.md for an automatic fallback method

---
 specs/commandline/sign.md | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/specs/commandline/sign.md b/specs/commandline/sign.md
index b8ea9c9f4..181605e09 100644
--- a/specs/commandline/sign.md
+++ b/specs/commandline/sign.md
@@ -41,11 +41,15 @@ Flags:
   -m,  --user-metadata strings    {key}={value} pairs that are added to the signature payload
 ```
 
-## Use OCI image manifest to store signatures
+## User expereince when signing and storing 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 `--image-spec v1.1-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. However, 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]. Notation supports both an explicit and implicit method for backward compatability. 
 
-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.
+### For Implicit
+In the default approach, if pushing the signature using the OCI Artifact manifest results in Notation getting an error code 405 - Method not allowed or error code 415 - Unsupported media type, Notation will automatically try to push the signature with the implicit method. 
+
+### For Explicit
+Use flag `--image-spec v1.1-image` to force Notation to store the signatures using OCI image manifest explicitly. In this case Notation will not even try to store the signature using the "OCI Artifact Manifest"
 
 ### Set config property for OCI image manifest
 
@@ -61,7 +65,7 @@ Notation uses empty JSON object `{}` as the default configuration content, and t
 }
 ```
 
-### When to use OCI image manifest
+#### When to use OCI image manifest explicit method
 
 [Registry support][registry-support] lists registries with different compatibilities. For registries not supporting `OCI artifact manifest`, users can use flag `--image-spec v1.1-image` to sign artifacts stored in those registries.
 

From e94f9a841132aba2cb34613ae230c2cc2ec6a528 Mon Sep 17 00:00:00 2001
From: Samir Kakkar <83560495+iamsamirzon@users.noreply.github.com>
Date: Tue, 17 Jan 2023 16:57:15 -0800
Subject: [PATCH 2/2] Update sign.md

---
 specs/commandline/sign.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/specs/commandline/sign.md b/specs/commandline/sign.md
index 181605e09..8026729f9 100644
--- a/specs/commandline/sign.md
+++ b/specs/commandline/sign.md
@@ -46,7 +46,7 @@ Flags:
 By default, Notation uses [OCI artifact manifest][oci-artifact-manifest] to store signatures in registries. However, 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]. Notation supports both an explicit and implicit method for backward compatability. 
 
 ### For Implicit
-In the default approach, if pushing the signature using the OCI Artifact manifest results in Notation getting an error code 405 - Method not allowed or error code 415 - Unsupported media type, Notation will automatically try to push the signature with the implicit method. 
+In the default approach, if pushing the signature using the OCI Artifact manifest results in Notation getting an error code 405 - Method not allowed or error code 415 - Unsupported media type, Notation will automatically try to push the signature with the Image spec method.
 
 ### For Explicit
 Use flag `--image-spec v1.1-image` to force Notation to store the signatures using OCI image manifest explicitly. In this case Notation will not even try to store the signature using the "OCI Artifact Manifest"