From aa34c23a28998b6de6965ae148138e3066ee444c Mon Sep 17 00:00:00 2001
From: Feynman Zhou <feynmanzhou@microsoft.com>
Date: Tue, 10 Jan 2023 11:58:38 +0800
Subject: [PATCH 01/37] doc: add ORAS CLI proposal doc

Signed-off-by: Feynman Zhou <feynmanzhou@microsoft.com>
---
 docs/proposals/compatibility-mode.md | 61 ++++++++++++++++++++++++++++
 1 file changed, 61 insertions(+)
 create mode 100644 docs/proposals/compatibility-mode.md

diff --git a/docs/proposals/compatibility-mode.md b/docs/proposals/compatibility-mode.md
new file mode 100644
index 000000000..be63cf26b
--- /dev/null
+++ b/docs/proposals/compatibility-mode.md
@@ -0,0 +1,61 @@
+# Proposal: Provide a compatibility mode for ORAS
+
+This document is for adding a proposal to enable compatibility mode for ORAS CLI and solve [issue #720](https://github.com/oras-project/oras/issues/720).
+
+## Background
+
+OCI group announced the release of v1.1 for [Image-spec](https://github.com/opencontainers/image-spec/blob/main/artifact.md) and [Distribution-spec](https://github.com/opencontainers/distribution-spec) in Sep 2022. It supports the OCI artifact manifest and provides a new referrers discovery API that allows artifact references.
+
+Since 0.16.0, ORAS supports pushing OCI artifact manifest to OCI v1.0 compliant registries. However, the new manifest type may not be supported on the consumer side (e.g. self-crafted scripts) or in those OCI v1.0 compliant registries. To enable ORAS to work with popular registries, it provides backward compatibility which supports two types of manifest and allows fallback to upload the OCI image manifest to OCI v1.0 compliant registries or enabled OCI image manifest storage. 
+
+## Challenge
+
+However, the ORAS fallback may fail as there is no deterministic way to confirm if a registry supporting OCI artifact manifest and no consistent error response. On the other hand, users may want to force-push a specific manifest type to a registry for some reason.
+
+![This table is captured from [https://toddysm.com/2023/01/05/oci-artifct-manifests-oci-referrers-api-and-their-support-across-registries-part-1/](https://toddysm.com/2023/01/05/oci-artifct-manifests-oci-referrers-api-and-their-support-across-registries-part-1/)](Proposal%20Provide%20Compatibility%20mode%20for%20ORAS%20a1e29245ea014b10a9711bae0d04db3c/Untitled.png)
+
+This table is captured from [https://toddysm.com/2023/01/05/oci-artifct-manifests-oci-referrers-api-and-their-support-across-registries-part-1/](https://toddysm.com/2023/01/05/oci-artifct-manifests-oci-referrers-api-and-their-support-across-registries-part-1/)
+
+The current workaround for enabling the compatibility mode is to specify a `--config` flag when using `oras push`. Since the OCI Artifact Manifest does not have a `config`, it will push an OCI image manifest instead. It is not user-friendly and is a bit hacky. It would be better if we can provide a compatibility mode for switching the manifest uploading behavior.
+
+## Goals
+
+- Enable ORAS to work with more registries
+- Provide different options to allow users to customize the behaviors of uploading manifest to the registry
+- Provide an easy-to-use and secure user experience when switching the behaviors
+
+## Solution
+
+Adding a new flag `--compatibility` under CLI commands `oras push` and `oras attach` with different variables to configure the behaviors of uploading manifest. We will only use `oras push` to demonstrate the examples below.
+
+### Use case A
+
+If users want to force-push the OCI Artifact Manifest to registries whether they are compliant with OCI v1.0 or v1.1, using `--compatibility artifact-manifest` will only upload OCI Image Manifest to registries. Users might choose it for security requirements, such as pushing a signature to a registry without changing its digest.
+
+```bash
+oras push localhost:5000/hello-artifact:v1 --artifact-type sbom/example --compatibility artifact-manifest sbom.json 
+```
+
+### Use case B
+
+If users want to force-push the OCI Image Manifest to registries whether they are compliant with OCI v1.0 or v1.1, using `--compatibility image-manifest` will only upload OCI Image Manifest to registries. This option is helpful when users have concerns to use OCI Artifact Manifest or migrate content to OCI v1.0 compliant registries.
+
+```bash
+oras push localhost:5000/hello-artifact:v1 --artifact-type sbom/example --compatibility image-manifest sbom.json 
+```
+
+### Use case C
+
+Disable backward compatibility and only upload OCI Artifact Manifest to a registry. This flag `--compatibility min` will be commonly used with the OCI v1.1 compliant registries or registries that support storing OCI Artifact Manifest, such as Zot, Azure Container Registry, and Docker Hub. This is the most strict option for the behavior of uploading manifest. Users might choose it for security requirements. 
+
+```bash
+oras push localhost:5000/hello-artifact:v1 --artifact-type sbom/example --compatibility min sbom.json 
+```
+
+### Use case D
+
+If users want to upload manifest to OCI v1.0 compliant registries like Harbor, GitHub Container Registry, etc, using `--compatibility max` will upload OCI Image Manifest first and Referrals tag schema. This option enables maximum backward compatibility for registries. If it uploads fails, it will try to upload OCI Artifact Manifest. If it still uploads fails, which means ORAS is not compatible with the registry.
+
+```bash
+oras push localhost:5000/hello-artifact:v1 --artifact-type sbom/example --compatibility max sbom.json 
+```
\ No newline at end of file

From 5e058388cac34857ced90f01740931ace333d94a Mon Sep 17 00:00:00 2001
From: Feynman Zhou <feynmanzhou@microsoft.com>
Date: Tue, 10 Jan 2023 12:13:35 +0800
Subject: [PATCH 02/37] doc: add ORAS CLI proposal doc

Signed-off-by: Feynman Zhou <feynmanzhou@microsoft.com>
---
 docs/proposals/compatibility-mode.md | 9 +++------
 1 file changed, 3 insertions(+), 6 deletions(-)

diff --git a/docs/proposals/compatibility-mode.md b/docs/proposals/compatibility-mode.md
index be63cf26b..26a02a88c 100644
--- a/docs/proposals/compatibility-mode.md
+++ b/docs/proposals/compatibility-mode.md
@@ -10,13 +10,10 @@ Since 0.16.0, ORAS supports pushing OCI artifact manifest to OCI v1.0 compliant
 
 ## Challenge
 
-However, the ORAS fallback may fail as there is no deterministic way to confirm if a registry supporting OCI artifact manifest and no consistent error response. On the other hand, users may want to force-push a specific manifest type to a registry for some reason.
+However, the ORAS fallback may fail as there is no deterministic way to confirm if a registry supporting OCI artifact manifest and no consistent error response. 
+You can find the testing result of the implementation result for OCI Spec from this [blog](https://toddysm.com/2023/01/05/oci-artifct-manifests-oci-referrers-api-and-their-support-across-registries-part-1/). On the other hand, users may want to force-push a specific manifest type to a registry for some reason.
 
-![This table is captured from [https://toddysm.com/2023/01/05/oci-artifct-manifests-oci-referrers-api-and-their-support-across-registries-part-1/](https://toddysm.com/2023/01/05/oci-artifct-manifests-oci-referrers-api-and-their-support-across-registries-part-1/)](Proposal%20Provide%20Compatibility%20mode%20for%20ORAS%20a1e29245ea014b10a9711bae0d04db3c/Untitled.png)
-
-This table is captured from [https://toddysm.com/2023/01/05/oci-artifct-manifests-oci-referrers-api-and-their-support-across-registries-part-1/](https://toddysm.com/2023/01/05/oci-artifct-manifests-oci-referrers-api-and-their-support-across-registries-part-1/)
-
-The current workaround for enabling the compatibility mode is to specify a `--config` flag when using `oras push`. Since the OCI Artifact Manifest does not have a `config`, it will push an OCI image manifest instead. It is not user-friendly and is a bit hacky. It would be better if we can provide a compatibility mode for switching the manifest uploading behavior.
+The current workaround for enabling a kind of compatibility mode is to specify a `--config` flag when using `oras push`. Since the OCI Artifact Manifest does not have a `config`, it will push an OCI image manifest instead. It is not user-friendly and is a bit hacky. It would be better if we can provide a compatibility mode to easily customize and switch the manifest uploading behavior, and enable users to handle the incompatibility problem when using ORAS across different registries. 
 
 ## Goals
 

From cce1f66b1474c4e489ec1be560faf18242367888 Mon Sep 17 00:00:00 2001
From: Feynman Zhou <feynmanzhou@microsoft.com>
Date: Tue, 10 Jan 2023 18:30:07 +0800
Subject: [PATCH 03/37] doc: update the compatibility mode proposal

Signed-off-by: Feynman Zhou <feynmanzhou@microsoft.com>
---
 docs/proposals/compatibility-mode.md | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)

diff --git a/docs/proposals/compatibility-mode.md b/docs/proposals/compatibility-mode.md
index 26a02a88c..ba4bd5069 100644
--- a/docs/proposals/compatibility-mode.md
+++ b/docs/proposals/compatibility-mode.md
@@ -13,7 +13,7 @@ Since 0.16.0, ORAS supports pushing OCI artifact manifest to OCI v1.0 compliant
 However, the ORAS fallback may fail as there is no deterministic way to confirm if a registry supporting OCI artifact manifest and no consistent error response. 
 You can find the testing result of the implementation result for OCI Spec from this [blog](https://toddysm.com/2023/01/05/oci-artifct-manifests-oci-referrers-api-and-their-support-across-registries-part-1/). On the other hand, users may want to force-push a specific manifest type to a registry for some reason.
 
-The current workaround for enabling a kind of compatibility mode is to specify a `--config` flag when using `oras push`. Since the OCI Artifact Manifest does not have a `config`, it will push an OCI image manifest instead. It is not user-friendly and is a bit hacky. It would be better if we can provide a compatibility mode to easily customize and switch the manifest uploading behavior, and enable users to handle the incompatibility problem when using ORAS across different registries. 
+The current workaround for enabling a kind of compatibility mode is to specify a `--config` flag when using `oras push`. Since the OCI artifact manifest does not have a `config`, it will push an OCI image manifest instead. It is not user-friendly and is a bit hacky. It would be better if we can provide a compatibility mode to easily customize and switch the manifest uploading behavior, and enable users to handle the incompatibility problem when using ORAS across different registries. 
 
 ## Goals
 
@@ -27,7 +27,7 @@ Adding a new flag `--compatibility` under CLI commands `oras push` and `oras att
 
 ### Use case A
 
-If users want to force-push the OCI Artifact Manifest to registries whether they are compliant with OCI v1.0 or v1.1, using `--compatibility artifact-manifest` will only upload OCI Image Manifest to registries. Users might choose it for security requirements, such as pushing a signature to a registry without changing its digest.
+If users want to force-push the OCI artifact manifest to registries whether they are compliant with OCI v1.0 or v1.1, using `--compatibility artifact-manifest` will only upload OCI image manifest to registries. Users might choose it for security requirements, such as pushing a signature to a registry without changing its digest.
 
 ```bash
 oras push localhost:5000/hello-artifact:v1 --artifact-type sbom/example --compatibility artifact-manifest sbom.json 
@@ -35,7 +35,7 @@ oras push localhost:5000/hello-artifact:v1 --artifact-type sbom/example --compat
 
 ### Use case B
 
-If users want to force-push the OCI Image Manifest to registries whether they are compliant with OCI v1.0 or v1.1, using `--compatibility image-manifest` will only upload OCI Image Manifest to registries. This option is helpful when users have concerns to use OCI Artifact Manifest or migrate content to OCI v1.0 compliant registries.
+If users want to force-push the OCI image manifest to registries whether they are compliant with OCI v1.0 or v1.1, using `--compatibility image-manifest` will only upload OCI image manifest to registries. This option is helpful when users have concerns to use OCI artifact manifest or migrate content to OCI v1.0 compliant registries.
 
 ```bash
 oras push localhost:5000/hello-artifact:v1 --artifact-type sbom/example --compatibility image-manifest sbom.json 
@@ -43,7 +43,7 @@ oras push localhost:5000/hello-artifact:v1 --artifact-type sbom/example --compat
 
 ### Use case C
 
-Disable backward compatibility and only upload OCI Artifact Manifest to a registry. This flag `--compatibility min` will be commonly used with the OCI v1.1 compliant registries or registries that support storing OCI Artifact Manifest, such as Zot, Azure Container Registry, and Docker Hub. This is the most strict option for the behavior of uploading manifest. Users might choose it for security requirements. 
+Disable backward compatibility and only upload OCI artifact manifest to a registry. This flag `--compatibility min` will be commonly used with the OCI v1.1 compliant registries or registries that support storing OCI artifact manifest, such as Zot, Azure Container Registry, and Docker Hub. ORAS will push OCI artifact manifest only and no further actions for maintaining artifact references in registries. This is the most strict option for the behavior of uploading manifest. Users might choose it for security requirements. 
 
 ```bash
 oras push localhost:5000/hello-artifact:v1 --artifact-type sbom/example --compatibility min sbom.json 
@@ -51,8 +51,10 @@ oras push localhost:5000/hello-artifact:v1 --artifact-type sbom/example --compat
 
 ### Use case D
 
-If users want to upload manifest to OCI v1.0 compliant registries like Harbor, GitHub Container Registry, etc, using `--compatibility max` will upload OCI Image Manifest first and Referrals tag schema. This option enables maximum backward compatibility for registries. If it uploads fails, it will try to upload OCI Artifact Manifest. If it still uploads fails, which means ORAS is not compatible with the registry.
+If users want to upload manifest to OCI v1.0 compliant registries like Harbor, GitHub Container Registry, etc, using `--compatibility max` will push OCI image manifest and then push Referrals tag schema if the `subject` field of the OCI image manifest is not empty. This option enables maximum backward compatibility for registries. It allows `oras push` or `oras attach` to work with the OCI v1.0 compliant registries even though the registries return non-404 response code.
 
 ```bash
 oras push localhost:5000/hello-artifact:v1 --artifact-type sbom/example --compatibility max sbom.json 
-```
\ No newline at end of file
+```
+
+

From 0066516df1ba38f3e904fea292d24d3549fea816 Mon Sep 17 00:00:00 2001
From: Feynman Zhou <feynmanzhou@microsoft.com>
Date: Sat, 28 Jan 2023 12:36:13 +0800
Subject: [PATCH 04/37] update compatibility doc

Signed-off-by: Feynman Zhou <feynmanzhou@microsoft.com>
---
 docs/proposals/compatibility-mode.md | 74 +++++++++++++++++++---------
 1 file changed, 52 insertions(+), 22 deletions(-)

diff --git a/docs/proposals/compatibility-mode.md b/docs/proposals/compatibility-mode.md
index ba4bd5069..74784c1e6 100644
--- a/docs/proposals/compatibility-mode.md
+++ b/docs/proposals/compatibility-mode.md
@@ -1,60 +1,90 @@
-# Proposal: Provide a compatibility mode for ORAS
+# Compatibility mode for ORAS
 
-This document is for adding a proposal to enable compatibility mode for ORAS CLI and solve [issue #720](https://github.com/oras-project/oras/issues/720).
+This document is for adding a document to elaborate the compatibility mode for ORAS CLI which was prosed in [issue #720](https://github.com/oras-project/oras/issues/720).
 
 ## Background
 
 OCI group announced the release of v1.1 for [Image-spec](https://github.com/opencontainers/image-spec/blob/main/artifact.md) and [Distribution-spec](https://github.com/opencontainers/distribution-spec) in Sep 2022. It supports the OCI artifact manifest and provides a new referrers discovery API that allows artifact references.
 
-Since 0.16.0, ORAS supports pushing OCI artifact manifest to OCI v1.0 compliant registries. However, the new manifest type may not be supported on the consumer side (e.g. self-crafted scripts) or in those OCI v1.0 compliant registries. To enable ORAS to work with popular registries, it provides backward compatibility which supports two types of manifest and allows fallback to upload the OCI image manifest to OCI v1.0 compliant registries or enabled OCI image manifest storage. 
+Since 0.16.0, ORAS supports pushing OCI artifact manifest to OCI v1.0 compliant registries. However, the new manifest type may not be supported on the consumer side (e.g. self-crafted scripts) or in those OCI v1.0 compliant registries. To enable ORAS to work with popular registries, it provides backward compatibility which supports two types of manifest and allows fallback to upload the OCI image manifest to OCI v1.0 compliant registries or those which enabled OCI image manifest storage. 
 
 ## Challenge
 
-However, the ORAS fallback may fail as there is no deterministic way to confirm if a registry supporting OCI artifact manifest and no consistent error response. 
+However, ORAS fallback may fail as there is no deterministic way to confirm if a registry supporting OCI artifact manifest and no consistent error response. 
+
 You can find the testing result of the implementation result for OCI Spec from this [blog](https://toddysm.com/2023/01/05/oci-artifct-manifests-oci-referrers-api-and-their-support-across-registries-part-1/). On the other hand, users may want to force-push a specific manifest type to a registry for some reason.
 
 The current workaround for enabling a kind of compatibility mode is to specify a `--config` flag when using `oras push`. Since the OCI artifact manifest does not have a `config`, it will push an OCI image manifest instead. It is not user-friendly and is a bit hacky. It would be better if we can provide a compatibility mode to easily customize and switch the manifest uploading behavior, and enable users to handle the incompatibility problem when using ORAS across different registries. 
 
 ## Goals
 
-- Enable ORAS to work with more registries
-- Provide different options to allow users to customize the behaviors of uploading manifest to the registry
+- Provide different options to allow users to customize the manifest uploading behavior to the registry
 - Provide an easy-to-use and secure user experience when switching the behaviors
+- Enable ORAS to work with more registries flexibly 
 
 ## Solution
 
-Adding a new flag `--compatibility` under CLI commands `oras push` and `oras attach` with different variables to configure the behaviors of uploading manifest. We will only use `oras push` to demonstrate the examples below.
+Adding new flags to `oras push` and `oras attach` respectively with different variables to configure the manifest uploading behaviors. 
 
-### Use case A
+- Adding a flag `--image-spec` to `oras push` and `oras attach` to force uploading a specific manifest type to registry
+- Adding a flag  `--distribution-spec` to `oras attach` to configure compatibility with registry
 
-If users want to force-push the OCI artifact manifest to registries whether they are compliant with OCI v1.0 or v1.1, using `--compatibility artifact-manifest` will only upload OCI image manifest to registries. Users might choose it for security requirements, such as pushing a signature to a registry without changing its digest.
+### Force uploading a specific manifest type using a flag `--image-spec`
 
-```bash
-oras push localhost:5000/hello-artifact:v1 --artifact-type sbom/example --compatibility artifact-manifest sbom.json 
-```
+It follows `--image-spec <spec version>-<manifest type>` to enable configuration of using which spec version and manifest type. Currently, it only supports specifying v1.1 as the spec version. 
 
-### Use case B
+| registry support                        | v1.1-artifact | v1.1-image | 
+| :-------------------------------------- | ----------------- | -------------- | 
+| OCI spec 1.0                            | no                | yes[^footnote] |
+| OCI spec 1.1 without referrers API      | yes               | yes            | 
+| OCI spec 1.1 with referrers API support | yes               | yes            | 
 
-If users want to force-push the OCI image manifest to registries whether they are compliant with OCI v1.0 or v1.1, using `--compatibility image-manifest` will only upload OCI image manifest to registries. This option is helpful when users have concerns to use OCI artifact manifest or migrate content to OCI v1.0 compliant registries.
+> [^footnote]: It only works when the registry returns error code 404 for [referrers API](https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc1/spec.md#listing-referrers). 
+
+If users want to force pushing a specific version of OCI artifact manifest to a registry, they can use `--image-spec v1.1-artifact`. An OCI artifact manifest will be packed and uploaded. Users might choose it for security requirements, such as pushing a signature to a registry without changing its digest. For example:
 
 ```bash
-oras push localhost:5000/hello-artifact:v1 --artifact-type sbom/example --compatibility image-manifest sbom.json 
+oras push localhost:5000/hello-artifact:v1 \
+--image-spec v1.1-artifact
+--artifact-type sbom/example \
+sbom.json 
 ```
 
-### Use case C
-
-Disable backward compatibility and only upload OCI artifact manifest to a registry. This flag `--compatibility min` will be commonly used with the OCI v1.1 compliant registries or registries that support storing OCI artifact manifest, such as Zot, Azure Container Registry, and Docker Hub. ORAS will push OCI artifact manifest only and no further actions for maintaining artifact references in registries. This is the most strict option for the behavior of uploading manifest. Users might choose it for security requirements. 
+If users want to force pushing an OCI image manifest, no matter whether the registry is compliant with the OCI Spec v1.0 or v1.1, using `--image-spec v1.1-image` will only upload the OCI image manifest to a registry. This option is useful when users have concerns to use OCI artifact manifest or need to migrate content to OCI v1.0 compliant registry. For example:
 
 ```bash
-oras push localhost:5000/hello-artifact:v1 --artifact-type sbom/example --compatibility min sbom.json 
+oras push localhost:5000/hello-artifact:v1 \
+--image-spec v1.1-image \
+--artifact-type sbom/example \
+sbom.json \
 ```
 
-### Use case D
+### Configure compatibility with OCI registry using a flag `--distribution-spec`
 
-If users want to upload manifest to OCI v1.0 compliant registries like Harbor, GitHub Container Registry, etc, using `--compatibility max` will push OCI image manifest and then push Referrals tag schema if the `subject` field of the OCI image manifest is not empty. This option enables maximum backward compatibility for registries. It allows `oras push` or `oras attach` to work with the OCI v1.0 compliant registries even though the registries return non-404 response code.
+Based on the Referrers API status in the registry, users can use flag `--distribution-spec <spec version>-<api>-<option>` to configure compatibility with registry. This flag is only applicable to `oras attach`.
+
+| registry support                        |  v1.1-referrers-api | v1.1-referrers-tag |
+| :-------------------------------------- | --- | --- | 
+| OCI spec 1.0                            | no  | yes |
+| OCI spec 1.1 without referrers API      | no  | yes |
+| OCI spec 1.1 with referrers API support | yes | yes |
+
+Using a flag `--distribution-spec v1.1-referrers-api` to disable backward compatibility. It only allows uploading OCI artifact manifest to OCI v1.1 compliant registry with Referrers API enabled. This is the most strict option for setting compatibility with the registry. Users might choose it for security requirements. 
+
+For example, using this flag, ORAS will attach OCI artifact manifest only to an OCI v1.1 compliant registry with Referrers API enabled and no further actions for maintaining artifact references in registries.  
 
 ```bash
-oras push localhost:5000/hello-artifact:v1 --artifact-type sbom/example --compatibility max sbom.json 
+oras attach localhost:5000/hello-artifact:v1 \
+--artifact-type sbom/example \
+--distribution-spec v1.1-referrers-api \
+sbom.json 
 ```
 
+Using `--distribution-spec v1.1-referrers-tag` to enable maximum backward compatibility with the registry. It will upload OCI image manifest and [referrers tag schema](https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc1/spec.md#referrers-tag-schema) regardless of whether the registry complies with the OCI Spec v1.0 or v1.1 or support Referrers API. For example: 
 
+```bash
+oras attach localhost:5000/hello-artifact:v1 \
+--artifact-type sbom/example \
+--compatibility v1.1-referrers-tag \
+sbom.json 
+```
\ No newline at end of file

From 49a20b0b4e8c538c54e68b16fbd61a5406542a1b Mon Sep 17 00:00:00 2001
From: Feynman Zhou <feynmanzhou@microsoft.com>
Date: Sun, 29 Jan 2023 12:13:56 +0800
Subject: [PATCH 05/37] update compatibility doc to resolve Billy's comments

Signed-off-by: Feynman Zhou <feynmanzhou@microsoft.com>
---
 docs/proposals/compatibility-mode.md | 16 +++++++++-------
 1 file changed, 9 insertions(+), 7 deletions(-)

diff --git a/docs/proposals/compatibility-mode.md b/docs/proposals/compatibility-mode.md
index 74784c1e6..fe402246b 100644
--- a/docs/proposals/compatibility-mode.md
+++ b/docs/proposals/compatibility-mode.md
@@ -27,7 +27,7 @@ The current workaround for enabling a kind of compatibility mode is to specify a
 Adding new flags to `oras push` and `oras attach` respectively with different variables to configure the manifest uploading behaviors. 
 
 - Adding a flag `--image-spec` to `oras push` and `oras attach` to force uploading a specific manifest type to registry
-- Adding a flag  `--distribution-spec` to `oras attach` to configure compatibility with registry
+- Adding a flag `--distribution-spec` to `oras attach`, `oras attach`, `oras cp`, and `oras manifest push` to configure compatibility with registry when pushing or copying an image/artifact manifest. This flag is also applicable to `oras discover` for filtering the referrers.
 
 ### Force uploading a specific manifest type using a flag `--image-spec`
 
@@ -35,12 +35,10 @@ It follows `--image-spec <spec version>-<manifest type>` to enable configuration
 
 | registry support                        | v1.1-artifact | v1.1-image | 
 | :-------------------------------------- | ----------------- | -------------- | 
-| OCI spec 1.0                            | no                | yes[^footnote] |
+| OCI spec 1.0                            | no                | yes |
 | OCI spec 1.1 without referrers API      | yes               | yes            | 
 | OCI spec 1.1 with referrers API support | yes               | yes            | 
 
-> [^footnote]: It only works when the registry returns error code 404 for [referrers API](https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc1/spec.md#listing-referrers). 
-
 If users want to force pushing a specific version of OCI artifact manifest to a registry, they can use `--image-spec v1.1-artifact`. An OCI artifact manifest will be packed and uploaded. Users might choose it for security requirements, such as pushing a signature to a registry without changing its digest. For example:
 
 ```bash
@@ -61,14 +59,16 @@ sbom.json \
 
 ### Configure compatibility with OCI registry using a flag `--distribution-spec`
 
-Based on the Referrers API status in the registry, users can use flag `--distribution-spec <spec version>-<api>-<option>` to configure compatibility with registry. This flag is only applicable to `oras attach`.
+Based on the Referrers API status in the registry, users can use flag `--distribution-spec <spec version>-<api>-<option>` to configure compatibility with registry. 
 
 | registry support                        |  v1.1-referrers-api | v1.1-referrers-tag |
 | :-------------------------------------- | --- | --- | 
-| OCI spec 1.0                            | no  | yes |
+| OCI spec 1.0                            | no  | yes[^footnote] |
 | OCI spec 1.1 without referrers API      | no  | yes |
 | OCI spec 1.1 with referrers API support | yes | yes |
 
+> [^footnote]: It only works when the registry returns error code 404 for [referrers API](https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc1/spec.md#listing-referrers). 
+
 Using a flag `--distribution-spec v1.1-referrers-api` to disable backward compatibility. It only allows uploading OCI artifact manifest to OCI v1.1 compliant registry with Referrers API enabled. This is the most strict option for setting compatibility with the registry. Users might choose it for security requirements. 
 
 For example, using this flag, ORAS will attach OCI artifact manifest only to an OCI v1.1 compliant registry with Referrers API enabled and no further actions for maintaining artifact references in registries.  
@@ -87,4 +87,6 @@ oras attach localhost:5000/hello-artifact:v1 \
 --artifact-type sbom/example \
 --compatibility v1.1-referrers-tag \
 sbom.json 
-```
\ No newline at end of file
+```
+
+Similarly, users can use `oras cp`, and `oras manifest push` with the flag `--distribution-spec` to configure compatibility with registry when pushing or copying an image/artifact manifest, or use `oras discover` with the flag `--distribution-spec` for filtering the referrers in the view.
\ No newline at end of file

From 9addaa3f8567dd830212083d7f00a4e0dfd6dc16 Mon Sep 17 00:00:00 2001
From: Feynman Zhou <feynmanzhou@microsoft.com>
Date: Mon, 30 Jan 2023 14:29:58 +0800
Subject: [PATCH 06/37] update the compatibility doc to resolve Shiwei's
 comments

Signed-off-by: Feynman Zhou <feynmanzhou@microsoft.com>
---
 docs/proposals/compatibility-mode.md | 24 +++++++++++-------------
 1 file changed, 11 insertions(+), 13 deletions(-)

diff --git a/docs/proposals/compatibility-mode.md b/docs/proposals/compatibility-mode.md
index fe402246b..f76a736cb 100644
--- a/docs/proposals/compatibility-mode.md
+++ b/docs/proposals/compatibility-mode.md
@@ -1,16 +1,16 @@
 # Compatibility mode for ORAS
 
-This document is for adding a document to elaborate the compatibility mode for ORAS CLI which was prosed in [issue #720](https://github.com/oras-project/oras/issues/720).
+This document is for adding a document to elaborate the compatibility mode for ORAS CLI which was proposed in [issue #720](https://github.com/oras-project/oras/issues/720).
 
 ## Background
 
-OCI group announced the release of v1.1 for [Image-spec](https://github.com/opencontainers/image-spec/blob/main/artifact.md) and [Distribution-spec](https://github.com/opencontainers/distribution-spec) in Sep 2022. It supports the OCI artifact manifest and provides a new referrers discovery API that allows artifact references.
+OCI group announced the release of v1.1 for [Image-spec](https://github.com/opencontainers/image-spec/blob/v1.1.0-rc1/artifact.md) and [Distribution-spec](https://github.com/opencontainers/distribution-spec) in Sep 2022. It supports the OCI artifact manifest and provides a new referrers discovery API that allows artifact references.
 
 Since 0.16.0, ORAS supports pushing OCI artifact manifest to OCI v1.0 compliant registries. However, the new manifest type may not be supported on the consumer side (e.g. self-crafted scripts) or in those OCI v1.0 compliant registries. To enable ORAS to work with popular registries, it provides backward compatibility which supports two types of manifest and allows fallback to upload the OCI image manifest to OCI v1.0 compliant registries or those which enabled OCI image manifest storage. 
 
 ## Challenge
 
-However, ORAS fallback may fail as there is no deterministic way to confirm if a registry supporting OCI artifact manifest and no consistent error response. 
+The fallback attempted by ORAS may fail since there is no deterministic way to confirm if a registry supporting OCI artifact manifest due to no consistent error response. 
 
 You can find the testing result of the implementation result for OCI Spec from this [blog](https://toddysm.com/2023/01/05/oci-artifct-manifests-oci-referrers-api-and-their-support-across-registries-part-1/). On the other hand, users may want to force-push a specific manifest type to a registry for some reason.
 
@@ -35,7 +35,7 @@ It follows `--image-spec <spec version>-<manifest type>` to enable configuration
 
 | registry support                        | v1.1-artifact | v1.1-image | 
 | :-------------------------------------- | ----------------- | -------------- | 
-| OCI spec 1.0                            | no                | yes |
+| OCI spec 1.0                            | no                | yes            |
 | OCI spec 1.1 without referrers API      | yes               | yes            | 
 | OCI spec 1.1 with referrers API support | yes               | yes            | 
 
@@ -43,9 +43,9 @@ If users want to force pushing a specific version of OCI artifact manifest to a
 
 ```bash
 oras push localhost:5000/hello-artifact:v1 \
---image-spec v1.1-artifact
+--image-spec v1.1-artifact \
 --artifact-type sbom/example \
-sbom.json 
+  sbom.json 
 ```
 
 If users want to force pushing an OCI image manifest, no matter whether the registry is compliant with the OCI Spec v1.0 or v1.1, using `--image-spec v1.1-image` will only upload the OCI image manifest to a registry. This option is useful when users have concerns to use OCI artifact manifest or need to migrate content to OCI v1.0 compliant registry. For example:
@@ -54,7 +54,7 @@ If users want to force pushing an OCI image manifest, no matter whether the regi
 oras push localhost:5000/hello-artifact:v1 \
 --image-spec v1.1-image \
 --artifact-type sbom/example \
-sbom.json \
+  sbom.json
 ```
 
 ### Configure compatibility with OCI registry using a flag `--distribution-spec`
@@ -63,12 +63,10 @@ Based on the Referrers API status in the registry, users can use flag `--distrib
 
 | registry support                        |  v1.1-referrers-api | v1.1-referrers-tag |
 | :-------------------------------------- | --- | --- | 
-| OCI spec 1.0                            | no  | yes[^footnote] |
+| OCI spec 1.0                            | no  | yes |
 | OCI spec 1.1 without referrers API      | no  | yes |
 | OCI spec 1.1 with referrers API support | yes | yes |
 
-> [^footnote]: It only works when the registry returns error code 404 for [referrers API](https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc1/spec.md#listing-referrers). 
-
 Using a flag `--distribution-spec v1.1-referrers-api` to disable backward compatibility. It only allows uploading OCI artifact manifest to OCI v1.1 compliant registry with Referrers API enabled. This is the most strict option for setting compatibility with the registry. Users might choose it for security requirements. 
 
 For example, using this flag, ORAS will attach OCI artifact manifest only to an OCI v1.1 compliant registry with Referrers API enabled and no further actions for maintaining artifact references in registries.  
@@ -77,7 +75,7 @@ For example, using this flag, ORAS will attach OCI artifact manifest only to an
 oras attach localhost:5000/hello-artifact:v1 \
 --artifact-type sbom/example \
 --distribution-spec v1.1-referrers-api \
-sbom.json 
+  sbom.json 
 ```
 
 Using `--distribution-spec v1.1-referrers-tag` to enable maximum backward compatibility with the registry. It will upload OCI image manifest and [referrers tag schema](https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc1/spec.md#referrers-tag-schema) regardless of whether the registry complies with the OCI Spec v1.0 or v1.1 or support Referrers API. For example: 
@@ -85,8 +83,8 @@ Using `--distribution-spec v1.1-referrers-tag` to enable maximum backward compat
 ```bash
 oras attach localhost:5000/hello-artifact:v1 \
 --artifact-type sbom/example \
---compatibility v1.1-referrers-tag \
-sbom.json 
+--distribution-spec v1.1-referrers-tag \
+  sbom.json 
 ```
 
 Similarly, users can use `oras cp`, and `oras manifest push` with the flag `--distribution-spec` to configure compatibility with registry when pushing or copying an image/artifact manifest, or use `oras discover` with the flag `--distribution-spec` for filtering the referrers in the view.
\ No newline at end of file

From e4d1922dd40130d32056914e9f9b6f7efba7fd0d Mon Sep 17 00:00:00 2001
From: Feynman Zhou <feynmanzhou@microsoft.com>
Date: Mon, 30 Jan 2023 16:18:22 +0800
Subject: [PATCH 07/37] update the compatibility doc to resolve Shiwei's
 comments

Signed-off-by: Feynman Zhou <feynmanzhou@microsoft.com>
---
 docs/proposals/compatibility-mode.md | 22 ++++++++++++----------
 1 file changed, 12 insertions(+), 10 deletions(-)

diff --git a/docs/proposals/compatibility-mode.md b/docs/proposals/compatibility-mode.md
index f76a736cb..90c5d61fd 100644
--- a/docs/proposals/compatibility-mode.md
+++ b/docs/proposals/compatibility-mode.md
@@ -35,16 +35,18 @@ It follows `--image-spec <spec version>-<manifest type>` to enable configuration
 
 | registry support                        | v1.1-artifact | v1.1-image | 
 | :-------------------------------------- | ----------------- | -------------- | 
-| OCI spec 1.0                            | no                | yes            |
+| OCI spec 1.0                            | no                | yes[^footnote] |
 | OCI spec 1.1 without referrers API      | yes               | yes            | 
 | OCI spec 1.1 with referrers API support | yes               | yes            | 
 
+> [^footnote]: It may fail when the OCI spec 1.0 compliant registry doesn't accept the `subject` field included in the image manifest.
+
 If users want to force pushing a specific version of OCI artifact manifest to a registry, they can use `--image-spec v1.1-artifact`. An OCI artifact manifest will be packed and uploaded. Users might choose it for security requirements, such as pushing a signature to a registry without changing its digest. For example:
 
 ```bash
 oras push localhost:5000/hello-artifact:v1 \
---image-spec v1.1-artifact \
---artifact-type sbom/example \
+  --image-spec v1.1-artifact \
+  --artifact-type sbom/example \
   sbom.json 
 ```
 
@@ -52,8 +54,8 @@ If users want to force pushing an OCI image manifest, no matter whether the regi
 
 ```bash
 oras push localhost:5000/hello-artifact:v1 \
---image-spec v1.1-image \
---artifact-type sbom/example \
+  --image-spec v1.1-image \
+  --artifact-type sbom/example \
   sbom.json
 ```
 
@@ -73,17 +75,17 @@ For example, using this flag, ORAS will attach OCI artifact manifest only to an
 
 ```bash
 oras attach localhost:5000/hello-artifact:v1 \
---artifact-type sbom/example \
---distribution-spec v1.1-referrers-api \
+  --artifact-type sbom/example \
+  --distribution-spec v1.1-referrers-api \
   sbom.json 
 ```
 
-Using `--distribution-spec v1.1-referrers-tag` to enable maximum backward compatibility with the registry. It will upload OCI image manifest and [referrers tag schema](https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc1/spec.md#referrers-tag-schema) regardless of whether the registry complies with the OCI Spec v1.0 or v1.1 or support Referrers API. For example: 
+Using `--distribution-spec v1.1-referrers-tag` to enable maximum backward compatibility with the registry. It will first attempt to upload the OCI artifact manifest with the [referrers tag schema](https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc1/spec.md#referrers-tag-schema) regardless of whether the registry complies with the OCI Spec v1.0 or v1.1 or supports Referrers API. For example: 
 
 ```bash
 oras attach localhost:5000/hello-artifact:v1 \
---artifact-type sbom/example \
---distribution-spec v1.1-referrers-tag \
+  --artifact-type sbom/example \
+  --distribution-spec v1.1-referrers-tag \
   sbom.json 
 ```
 

From c5bc0bfd3c513797ff14b0cda803bce6c0a1ade9 Mon Sep 17 00:00:00 2001
From: Feynman Zhou <feynmanzhou@microsoft.com>
Date: Thu, 27 Apr 2023 23:41:24 +0800
Subject: [PATCH 08/37] fix broken logo link

Signed-off-by: Feynman Zhou <feynmanzhou@microsoft.com>
---
 README.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 689225c26..445862202 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,9 @@
 [![codecov](https://codecov.io/gh/oras-project/oras/branch/main/graph/badge.svg)](https://codecov.io/gh/oras-project/oras)
 
 
-![ORAS](https://github.com/oras-project/oras-www/raw/main/docs/assets/images/oras.png)
+<p align="left">
+<a href="https://oras.land/"><img src="https://oras.land/img/oras.svg" alt="banner" width="100px"></a>
+</p>
 
 ## Docs
 

From 0ec07035a076e8ebb0f793c737f6c09e2c99aa96 Mon Sep 17 00:00:00 2001
From: Feynman Zhou <feynmanzhou@microsoft.com>
Date: Thu, 2 Nov 2023 16:56:24 +0800
Subject: [PATCH 09/37] add error handling guide

Signed-off-by: Feynman Zhou <feynmanzhou@microsoft.com>
---
 docs/proposals/error-handling-guideline.md | 50 ++++++++++++++++++++++
 1 file changed, 50 insertions(+)
 create mode 100644 docs/proposals/error-handling-guideline.md

diff --git a/docs/proposals/error-handling-guideline.md b/docs/proposals/error-handling-guideline.md
new file mode 100644
index 000000000..4924bbe52
--- /dev/null
+++ b/docs/proposals/error-handling-guideline.md
@@ -0,0 +1,50 @@
+# ORAS CLI Error Handling Guidelines
+
+This document aims to provide the guidelines for ORAS contributors to improve existing error messages and error handling method as well as the new error output format. It will also provide recommendations for ORAS CLI contributors for how to write friendly and standard error messages and avoid inconsistent error handling & messages.
+
+## General guiding principles
+
+A clear and actionable error message is very important when raising an error, so make sure your error message describes clearly what the error is and tells users what they need to do if possible.
+
+First and foremost, make the error messages descriptive and informative. Error messages are expected to be helpful to troubleshoot where the user has done something wrong and the program is guiding them in the right direction. A great error message is recommended to contain the following:
+
+- Error code
+- Error title
+- Error description 
+- How to fix the error (Optional)
+- URL for more information (Optional, it can be a TSG document link)
+
+Second, when necessary, it is highly suggested for ORAS CLI contributors to provide recommendations for users how to resolve the problems based on the error messages they encountered. Showing descriptive words and straightforward prompt with executable commands as a potential solution is a good practice for error messages.
+
+Third, for unhandled errors you didn’t expect the user to run into. For that, have a way to view full traceback information as well as full debug or verbose logs output, and instructions on how to submit a bug.
+
+Forth, signal-to-noise ratio is crucial. The more irrelevant output you produce, the longer it’s going to take the user to figure out what they did wrong. If your program produces multiple errors of the same type, consider grouping them under a single explanatory header instead of printing many similar-looking lines.
+
+Last, error logs can also be useful for post-mortem debugging but make sure they have timestamps, truncate them occasionally so they don’t eat up space on disk, and make sure they don’t contain ansi color codes. Thereby, error logs can be written to a file.
+
+## How to write error message
+
+Here is an sample structure of an error message:
+
+```text
+Error: [Error description] : [Error code] ：[Error title]
+Help: [Recommended solution], [TSG]
+```
+
+See an example:
+
+```
+$ oras pull docker.io/nginx:latest
+Error: failed to resolve the resource: pull access denied for docker.io/nginx:latest : response status code 401: unauthorized: requested access to the resource is denied
+Help: repository does not exist or namespace is missing, or may require 'oras login'. Consider trying "docker.io/library/nginx:latest".
+```
+
+## Error types
+
+TBD
+
+## Error Recommendation
+
+### Dos
+
+### Don'Ts
\ No newline at end of file

From 4b63f4a126dae8455a7ba79ec39d4b9918a353fc Mon Sep 17 00:00:00 2001
From: Feynman Zhou <feynmanzhou@microsoft.com>
Date: Fri, 10 Nov 2023 09:45:36 +0800
Subject: [PATCH 10/37] update error message examples

Signed-off-by: Feynman Zhou <feynmanzhou@microsoft.com>
---
 docs/proposals/error-handling-guideline.md | 181 +++++++++++++++++++--
 1 file changed, 169 insertions(+), 12 deletions(-)

diff --git a/docs/proposals/error-handling-guideline.md b/docs/proposals/error-handling-guideline.md
index 4924bbe52..2bc91e0dd 100644
--- a/docs/proposals/error-handling-guideline.md
+++ b/docs/proposals/error-handling-guideline.md
@@ -1,4 +1,4 @@
-# ORAS CLI Error Handling Guidelines
+# ORAS CLI Error Handling and Message Guidelines
 
 This document aims to provide the guidelines for ORAS contributors to improve existing error messages and error handling method as well as the new error output format. It will also provide recommendations for ORAS CLI contributors for how to write friendly and standard error messages and avoid inconsistent error handling & messages.
 
@@ -11,7 +11,7 @@ First and foremost, make the error messages descriptive and informative. Error m
 - Error code
 - Error title
 - Error description 
-- How to fix the error (Optional)
+- How to fix the error
 - URL for more information (Optional, it can be a TSG document link)
 
 Second, when necessary, it is highly suggested for ORAS CLI contributors to provide recommendations for users how to resolve the problems based on the error messages they encountered. Showing descriptive words and straightforward prompt with executable commands as a potential solution is a good practice for error messages.
@@ -22,29 +22,186 @@ Forth, signal-to-noise ratio is crucial. The more irrelevant output you produce,
 
 Last, error logs can also be useful for post-mortem debugging but make sure they have timestamps, truncate them occasionally so they don’t eat up space on disk, and make sure they don’t contain ansi color codes. Thereby, error logs can be written to a file.
 
-## How to write error message
+## Error output recommendation
 
-Here is an sample structure of an error message:
+### Dos
+
+- Use the capital letter ahead of an error message
+- Print human readable error message. If the error message is mainly from the server and varies by different servers, tell users that the error response is from server. This implies that users may need to contact server side for troubleshooting.
+- Provide specific and actionable prompt message with argument suggestion or show the example usage for reference. (e.g, Instead of showing showing flag or argument options is missing, please provide available argument options and guide users to "--help" to view more examples)
+- If the actionable prompt message is too long to show in the CLI output, consider guide users to ORAS user guide or troubleshooting guide with the permanent link.
+- If the error message is not enough for troubleshooting, guide users to use "--verbose" to print much more detailed logs
+
+
+### Don'Ts
+
+- Do not use a formula-like or a programming expression in the error message. (e.g, `json: cannot unmarshal string into Go value of type map[string]map[string]string.`, or `Parameter 'xyz' must conform to the following pattern: '^[-\\w\\._\\(\\)]+$'`)
+- Do not use ambiguous expressions which mean nothing to users. (e.g, `Something unexpected happens`, or `Error: accepts 2 arg(s), received 0`)
+- Do not print irrelevant error message to make the output noisy. The more irrelevant output you produce, the longer it’s going to take the user to figure out what they did wrong.
+
+## How to write friendly error message
+
+### Recommended error meesage structure
+
+Here is a sample structure of an error message:
 
 ```text
 Error: [Error description] : [Error code] ：[Error title]
+
+Usage: [Sample command]
 Help: [Recommended solution], [TSG]
 ```
 
-See an example:
+### Examples
+
+Here are some examples of writing error message with helpful prompt actionable information:
+
+- Example 1: when no reference provided in `oras copy`
+
+```
+$ oras cp
+Error: accepts 2 arg(s), received 0
+```
+
+Suggested error message:
+
+```
+$ oras cp
+Error: "oras copy" requires exactly 2 arguments.
+
+Usage: oras copy [flags] <from>{:<tag>|@<digest>} <to>[:<tag>[,<tag>][...]]
+Help: Copy artifacts from one target to another. Run "oras copy -h" for more options and examples
+```
+
+- Example 2: when reference is not matched with the expected format
+
+```
+$ oras tag list ghcr.io/oras-project/oras
+Error: unable to add tag for 'list': invalid reference: missing repository
+```
+
+Suggested error message:
+
+```
+$ oras tag list ghcr.io/oras-project/oras
+Error: unable to add tag for 'list': invalid reference: missing repository
+
+Usage: oras tag [flags] <name>{:<tag>|@<digest>} <new_tag> [...]
+Help: Tag a manifest in a registry or an OCI image layout. Run "oras tag -h" for more options and examples
+```
+
+- Example 3: When fetching a manifest if no manifest tag or digest is provided
+
+```
+$ oras manifest fetch --oci-layout /tmp/ginkgo1163328512 >>
+Error: "/tmp/ginkgo1163328512": no tag or digest when expecting <name:tag|name@digest>
+```
+
+Suggested error message:
+
+```
+$ oras manifest fetch --oci-layout /tmp/ginkgo1163328512 >>
+Error: "/tmp/ginkgo1163328512": no tag or digest specified
+
+Usage: oras manifest fetch [flags] <name>{:<tag>|@<digest>}
+Help: Fetch manifest of the target artifact. Run "oras manifest fetch -h" for more options and examples 
+```
+
+- Example 4: push a manifest if no media type flag provided
+
+```
+$ oras manifest push --oci-layout /tmp/ginkgo2167255592:mediatype-flag
+Error: media type is not recognized. 
+```
+
+Suggested error message:
+
+```
+$ oras manifest push --oci-layout /tmp/ginkgo2167255592:mediatype-flag
+Error: media type is not recognized. Specify an valid media type with "--media-type"
+```
+
+- Example 5: attach an artifact if the given option is unknown
+
+```
+$ oras attach --artifact-type oras/test localhost:7000/command/images:foobar --distribution-spec ???
+Error: unknown distribution specification flag: "???"
+```
+
+Suggested error message:
+
+```
+$ oras attach --artifact-type oras/test localhost:7000/command/images:foobar --distribution-spec ???
+Error: unknown distribution specification flag: "???". Available options: v1.1-referrers-api, v1.1-referrers-tag
+```
+
+- Example 6: when attaching an file, if no file reference or manifest annotation provided
+
+```
+$ oras attach --artifact-type oras/test /tmp/ginkgo2977244222:foobar >>
+Error: no blob or manifest annotation are provided
+```
+
+Suggested error message:
+
+```
+$ oras attach --artifact-type oras/test /tmp/ginkgo2977244222:foobar >>
+Error: no blob or manifest annotation are provided
+
+Usage: oras attach [flags] --artifact-type=<type> <name>{:<tag>|@<digest>} <file>[:<type>] [...]
+Help: Attach files to an existing artifact. Run "oras attach" for more options and examples
+```
+
+- Example 7: When pushing files, if the annotation file doesn't match the required format
+
+```
+$ oras push --annotation-file sbom.json ghcr.io/library/alpine:3.9
+Error: failed to load annotations from sbom.json: json: cannot unmarshal string into Go value of type map[string]map[string]string. Please refer to the document at https://oras.land/docs/how_to_guides/manifest_annotations.
+```
+
+Suggested error message:
+
+```
+$ oras push --annotation-file annotation.json ghcr.io/library/alpine:3.9
+Error: failed to load annotations from annotation.json: annotation file or syntax doesn't match the required format or syntax
+
+Help: Please refer to the document at https://oras.land/docs/how_to_guides/manifest_annotations.
+```
+
+- Example 8: When pushing files, if the annotation value doesn't match the required syntax
+
+```
+$ oras push --annotation "key:value" ghcr.io/library/alpine:3.9
+Error: missing key in `--annotation` flag: key:value
+```
+
+Suggested error message:
+
+```
+$ oras push --annotation "key:value" ghcr.io/library/alpine:3.9
+Error: annotation value  doesn't match the required format.
+
+Help: Try oras push --annotation "key=value" ghcr.io/library/alpine:3.9  
+```
+
+- Example 9: 
 
 ```
 $ oras pull docker.io/nginx:latest
-Error: failed to resolve the resource: pull access denied for docker.io/nginx:latest : response status code 401: unauthorized: requested access to the resource is denied
-Help: repository does not exist or namespace is missing, or may require 'oras login'. Consider trying "docker.io/library/nginx:latest".
+Error: failed to resolve latest: GET "https://registry-1.docker.io/v2/nginx/manifests/latest": response status code 401: unauthorized: authentication required: [map[Action:pull Class: Name:nginx Type:repository]]
 ```
 
-## Error types
+Suggested error message:
 
-TBD
+```
+$ oras pull ghcr.io/nginx:latest
+Error: failed to resolve the resource from server: pull access denied for ghcr.io/nginx:latest : response status code 401: unauthorized: requested access to the resource is denied
 
-## Error Recommendation
+Help: repository does not exist or namespace is missing, or may require 'oras login'. 
+```
 
-### Dos
+## Reference
 
-### Don'Ts
\ No newline at end of file
+- [Azure CLI Error Handling Guidelines](https://github.com/Azure/azure-cli/blob/dev/doc/error_handling_guidelines.md)
+- [Command Line Interface Guidelines](https://clig.dev/#errors)
+- [12 Factor CLI Apps](https://medium.com/@jdxcode/12-factor-cli-apps-dd3c227a0e46)
\ No newline at end of file

From 76db991af16188cf8f2572f1cecf9793a7949283 Mon Sep 17 00:00:00 2001
From: Feynman Zhou <feynmanzhou@microsoft.com>
Date: Fri, 10 Nov 2023 09:52:39 +0800
Subject: [PATCH 11/37] update error message examples

Signed-off-by: Feynman Zhou <feynmanzhou@microsoft.com>
---
 docs/proposals/error-handling-guideline.md | 34 ++++++++++++++++------
 1 file changed, 25 insertions(+), 9 deletions(-)

diff --git a/docs/proposals/error-handling-guideline.md b/docs/proposals/error-handling-guideline.md
index 2bc91e0dd..c1c2b0852 100644
--- a/docs/proposals/error-handling-guideline.md
+++ b/docs/proposals/error-handling-guideline.md
@@ -56,7 +56,9 @@ Help: [Recommended solution], [TSG]
 
 Here are some examples of writing error message with helpful prompt actionable information:
 
-- Example 1: when no reference provided in `oras copy`
+#### Example 1: when no reference provided in `oras copy`
+
+Current behavior and output:
 
 ```
 $ oras cp
@@ -73,7 +75,9 @@ Usage: oras copy [flags] <from>{:<tag>|@<digest>} <to>[:<tag>[,<tag>][...]]
 Help: Copy artifacts from one target to another. Run "oras copy -h" for more options and examples
 ```
 
-- Example 2: when reference is not matched with the expected format
+#### Example 2: when reference does not match with the expected format
+
+Current behavior and output:
 
 ```
 $ oras tag list ghcr.io/oras-project/oras
@@ -90,7 +94,9 @@ Usage: oras tag [flags] <name>{:<tag>|@<digest>} <new_tag> [...]
 Help: Tag a manifest in a registry or an OCI image layout. Run "oras tag -h" for more options and examples
 ```
 
-- Example 3: When fetching a manifest if no manifest tag or digest is provided
+#### Example 3: When fetching a manifest if no manifest tag or digest is provided
+
+Current behavior and output:
 
 ```
 $ oras manifest fetch --oci-layout /tmp/ginkgo1163328512 >>
@@ -107,7 +113,9 @@ Usage: oras manifest fetch [flags] <name>{:<tag>|@<digest>}
 Help: Fetch manifest of the target artifact. Run "oras manifest fetch -h" for more options and examples 
 ```
 
-- Example 4: push a manifest if no media type flag provided
+#### Example 4: push a manifest if no media type flag provided
+
+Current behavior and output:
 
 ```
 $ oras manifest push --oci-layout /tmp/ginkgo2167255592:mediatype-flag
@@ -121,7 +129,9 @@ $ oras manifest push --oci-layout /tmp/ginkgo2167255592:mediatype-flag
 Error: media type is not recognized. Specify an valid media type with "--media-type"
 ```
 
-- Example 5: attach an artifact if the given option is unknown
+#### Example 5: attach an artifact if the given option is unknown
+
+Current behavior and output:
 
 ```
 $ oras attach --artifact-type oras/test localhost:7000/command/images:foobar --distribution-spec ???
@@ -135,7 +145,9 @@ $ oras attach --artifact-type oras/test localhost:7000/command/images:foobar --d
 Error: unknown distribution specification flag: "???". Available options: v1.1-referrers-api, v1.1-referrers-tag
 ```
 
-- Example 6: when attaching an file, if no file reference or manifest annotation provided
+#### Example 6: when attaching an file, if no file reference or manifest annotation provided
+
+Current behavior and output:
 
 ```
 $ oras attach --artifact-type oras/test /tmp/ginkgo2977244222:foobar >>
@@ -152,7 +164,9 @@ Usage: oras attach [flags] --artifact-type=<type> <name>{:<tag>|@<digest>} <file
 Help: Attach files to an existing artifact. Run "oras attach" for more options and examples
 ```
 
-- Example 7: When pushing files, if the annotation file doesn't match the required format
+#### Example 7: When pushing files, if the annotation file doesn't match the required format
+
+Current behavior and output:
 
 ```
 $ oras push --annotation-file sbom.json ghcr.io/library/alpine:3.9
@@ -168,7 +182,9 @@ Error: failed to load annotations from annotation.json: annotation file or synta
 Help: Please refer to the document at https://oras.land/docs/how_to_guides/manifest_annotations.
 ```
 
-- Example 8: When pushing files, if the annotation value doesn't match the required syntax
+#### Example 8: When pushing files, if the annotation value doesn't match the required syntax
+
+Current behavior and output:
 
 ```
 $ oras push --annotation "key:value" ghcr.io/library/alpine:3.9
@@ -184,7 +200,7 @@ Error: annotation value  doesn't match the required format.
 Help: Try oras push --annotation "key=value" ghcr.io/library/alpine:3.9  
 ```
 
-- Example 9: 
+#### Example 9: when failed to pull files from a public registry
 
 ```
 $ oras pull docker.io/nginx:latest

From 39ff6ae7c1a257591d0307d2b2304aae78a68465 Mon Sep 17 00:00:00 2001
From: Feynman Zhou <feynmanzhou@microsoft.com>
Date: Fri, 10 Nov 2023 09:55:36 +0800
Subject: [PATCH 12/37] update error message examples

Signed-off-by: Feynman Zhou <feynmanzhou@microsoft.com>
---
 docs/proposals/error-handling-guideline.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/docs/proposals/error-handling-guideline.md b/docs/proposals/error-handling-guideline.md
index c1c2b0852..2ba06cd22 100644
--- a/docs/proposals/error-handling-guideline.md
+++ b/docs/proposals/error-handling-guideline.md
@@ -218,6 +218,8 @@ Help: repository does not exist or namespace is missing, or may require 'oras lo
 
 ## Reference
 
+Parts of the content are borrowed from these guidelines.
+
 - [Azure CLI Error Handling Guidelines](https://github.com/Azure/azure-cli/blob/dev/doc/error_handling_guidelines.md)
 - [Command Line Interface Guidelines](https://clig.dev/#errors)
 - [12 Factor CLI Apps](https://medium.com/@jdxcode/12-factor-cli-apps-dd3c227a0e46)
\ No newline at end of file

From 95ec9cb7fddad64ffc1a8d86c31aff45521bb151 Mon Sep 17 00:00:00 2001
From: Feynman Zhou <feynmanzhou@microsoft.com>
Date: Wed, 15 Nov 2023 18:34:14 +0800
Subject: [PATCH 13/37] resolve comments

Signed-off-by: Feynman Zhou <feynmanzhou@microsoft.com>
---
 docs/proposals/error-handling-guideline.md | 52 +++++++++++-----------
 1 file changed, 26 insertions(+), 26 deletions(-)

diff --git a/docs/proposals/error-handling-guideline.md b/docs/proposals/error-handling-guideline.md
index 2ba06cd22..14cdc8c40 100644
--- a/docs/proposals/error-handling-guideline.md
+++ b/docs/proposals/error-handling-guideline.md
@@ -1,24 +1,24 @@
 # ORAS CLI Error Handling and Message Guidelines
 
-This document aims to provide the guidelines for ORAS contributors to improve existing error messages and error handling method as well as the new error output format. It will also provide recommendations for ORAS CLI contributors for how to write friendly and standard error messages and avoid inconsistent error handling & messages.
+This document aims to provide the guidelines for ORAS contributors to improve existing error messages and error handling method as well as the new error output format. It will also provide recommendations and examples for ORAS CLI contributors for how to write friendly and standard error messages, avoid generating inconsistent and ambiguous error messages.
 
 ## General guiding principles
 
 A clear and actionable error message is very important when raising an error, so make sure your error message describes clearly what the error is and tells users what they need to do if possible.
 
-First and foremost, make the error messages descriptive and informative. Error messages are expected to be helpful to troubleshoot where the user has done something wrong and the program is guiding them in the right direction. A great error message is recommended to contain the following:
+First and foremost, make the error messages descriptive and informative. Error messages are expected to be helpful to troubleshoot where the user has done something wrong and the program is guiding them in the right direction. A great error message is recommended to contain the following elements:
 
-- Error code
+- Error code (When the logs are generated from the server side)
 - Error title
 - Error description 
 - How to fix the error
-- URL for more information (Optional, it can be a TSG document link)
+- Versioned document link for more information (Optional, it can be a troubleshooting or FAQ document link)
 
 Second, when necessary, it is highly suggested for ORAS CLI contributors to provide recommendations for users how to resolve the problems based on the error messages they encountered. Showing descriptive words and straightforward prompt with executable commands as a potential solution is a good practice for error messages.
 
 Third, for unhandled errors you didn’t expect the user to run into. For that, have a way to view full traceback information as well as full debug or verbose logs output, and instructions on how to submit a bug.
 
-Forth, signal-to-noise ratio is crucial. The more irrelevant output you produce, the longer it’s going to take the user to figure out what they did wrong. If your program produces multiple errors of the same type, consider grouping them under a single explanatory header instead of printing many similar-looking lines.
+Fourth, signal-to-noise ratio is crucial. The more irrelevant output you produce, the longer it’s going to take the user to figure out what they did wrong. If your program produces multiple errors of the same type, consider grouping them under a single explanatory header instead of printing many similar-looking lines.
 
 Last, error logs can also be useful for post-mortem debugging but make sure they have timestamps, truncate them occasionally so they don’t eat up space on disk, and make sure they don’t contain ansi color codes. Thereby, error logs can be written to a file.
 
@@ -26,12 +26,12 @@ Last, error logs can also be useful for post-mortem debugging but make sure they
 
 ### Dos
 
-- Use the capital letter ahead of an error message
+- Use the capital letter ahead of each line of any error message
 - Print human readable error message. If the error message is mainly from the server and varies by different servers, tell users that the error response is from server. This implies that users may need to contact server side for troubleshooting.
-- Provide specific and actionable prompt message with argument suggestion or show the example usage for reference. (e.g, Instead of showing showing flag or argument options is missing, please provide available argument options and guide users to "--help" to view more examples)
+- Provide specific and actionable prompt message with argument suggestion or show the example usage for reference. (e.g, Instead of showing flag or argument options is missing, please provide available argument options and guide users to "--help" to view more examples)
 - If the actionable prompt message is too long to show in the CLI output, consider guide users to ORAS user guide or troubleshooting guide with the permanent link.
 - If the error message is not enough for troubleshooting, guide users to use "--verbose" to print much more detailed logs
-
+- Provide full description if the user input does not match what ORAS CLI expected. A full description should include the actual input received from the user and expected input.
 
 ### Don'Ts
 
@@ -41,15 +41,14 @@ Last, error logs can also be useful for post-mortem debugging but make sure they
 
 ## How to write friendly error message
 
-### Recommended error meesage structure
+### Recommended error message structure
 
 Here is a sample structure of an error message:
 
 ```text
-Error: [Error description] : [Error code] ：[Error title]
-
-Usage: [Sample command]
-Help: [Recommended solution], [TSG]
+Error: [Error code] : [Error title] : [Error description] 
+Usage: [Command usage]
+[Recommended solution], [TSG]
 ```
 
 ### Examples
@@ -72,7 +71,7 @@ $ oras cp
 Error: "oras copy" requires exactly 2 arguments.
 
 Usage: oras copy [flags] <from>{:<tag>|@<digest>} <to>[:<tag>[,<tag>][...]]
-Help: Copy artifacts from one target to another. Run "oras copy -h" for more options and examples
+Copy artifacts from one target to another. Run "oras copy -h" for more options and examples
 ```
 
 #### Example 2: when reference does not match with the expected format
@@ -91,7 +90,7 @@ $ oras tag list ghcr.io/oras-project/oras
 Error: unable to add tag for 'list': invalid reference: missing repository
 
 Usage: oras tag [flags] <name>{:<tag>|@<digest>} <new_tag> [...]
-Help: Tag a manifest in a registry or an OCI image layout. Run "oras tag -h" for more options and examples
+Tag a manifest in a registry or an OCI image layout. Run "oras tag -h" for more options and examples
 ```
 
 #### Example 3: When fetching a manifest if no manifest tag or digest is provided
@@ -110,7 +109,7 @@ $ oras manifest fetch --oci-layout /tmp/ginkgo1163328512 >>
 Error: "/tmp/ginkgo1163328512": no tag or digest specified
 
 Usage: oras manifest fetch [flags] <name>{:<tag>|@<digest>}
-Help: Fetch manifest of the target artifact. Run "oras manifest fetch -h" for more options and examples 
+Fetch manifest of the target artifact. Run "oras manifest fetch -h" for more options and examples 
 ```
 
 #### Example 4: push a manifest if no media type flag provided
@@ -126,7 +125,8 @@ Suggested error message:
 
 ```
 $ oras manifest push --oci-layout /tmp/ginkgo2167255592:mediatype-flag
-Error: media type is not recognized. Specify an valid media type with "--media-type"
+Error: media type is not recognized. 
+Specify an valid media type with "--media-type"
 ```
 
 #### Example 5: attach an artifact if the given option is unknown
@@ -134,15 +134,16 @@ Error: media type is not recognized. Specify an valid media type with "--media-t
 Current behavior and output:
 
 ```
-$ oras attach --artifact-type oras/test localhost:7000/command/images:foobar --distribution-spec ???
-Error: unknown distribution specification flag: "???"
+$ oras attach --artifact-type oras/test localhost:7000/command/images:foobar --distribution-spec v1.0
+Error: unknown distribution specification flag: v1.0
 ```
 
 Suggested error message:
 
 ```
 $ oras attach --artifact-type oras/test localhost:7000/command/images:foobar --distribution-spec ???
-Error: unknown distribution specification flag: "???". Available options: v1.1-referrers-api, v1.1-referrers-tag
+Error: unknown distribution specification flag: "v1.0". 
+Available options: v1.1-referrers-api, v1.1-referrers-tag
 ```
 
 #### Example 6: when attaching an file, if no file reference or manifest annotation provided
@@ -161,7 +162,7 @@ $ oras attach --artifact-type oras/test /tmp/ginkgo2977244222:foobar >>
 Error: no blob or manifest annotation are provided
 
 Usage: oras attach [flags] --artifact-type=<type> <name>{:<tag>|@<digest>} <file>[:<type>] [...]
-Help: Attach files to an existing artifact. Run "oras attach" for more options and examples
+Attach files to an existing artifact. Run "oras attach -h" for more options and examples
 ```
 
 #### Example 7: When pushing files, if the annotation file doesn't match the required format
@@ -179,7 +180,7 @@ Suggested error message:
 $ oras push --annotation-file annotation.json ghcr.io/library/alpine:3.9
 Error: failed to load annotations from annotation.json: annotation file or syntax doesn't match the required format or syntax
 
-Help: Please refer to the document at https://oras.land/docs/how_to_guides/manifest_annotations.
+Please refer to the document at https://oras.land/docs/how_to_guides/manifest_annotations.
 ```
 
 #### Example 8: When pushing files, if the annotation value doesn't match the required syntax
@@ -197,7 +198,7 @@ Suggested error message:
 $ oras push --annotation "key:value" ghcr.io/library/alpine:3.9
 Error: annotation value  doesn't match the required format.
 
-Help: Try oras push --annotation "key=value" ghcr.io/library/alpine:3.9  
+Try oras push --annotation "key=value" ghcr.io/library/alpine:3.9  
 ```
 
 #### Example 9: when failed to pull files from a public registry
@@ -210,10 +211,9 @@ Error: failed to resolve latest: GET "https://registry-1.docker.io/v2/nginx/mani
 Suggested error message:
 
 ```
-$ oras pull ghcr.io/nginx:latest
+$ oras pull docker.io/nginx:latest
 Error: failed to resolve the resource from server: pull access denied for ghcr.io/nginx:latest : response status code 401: unauthorized: requested access to the resource is denied
-
-Help: repository does not exist or namespace is missing, or may require 'oras login'. 
+Namespace is missing, do you mean `oras pull docker.io/library/nginx:latest`? 
 ```
 
 ## Reference

From 16e86cffd8037cf60a08953df2468af4a6fd1cb8 Mon Sep 17 00:00:00 2001
From: Feynman Zhou <feynmanzhou@microsoft.com>
Date: Wed, 15 Nov 2023 23:55:13 +0800
Subject: [PATCH 14/37] resolve comments

Signed-off-by: Feynman Zhou <feynmanzhou@microsoft.com>
---
 docs/proposals/error-handling-guideline.md | 16 ++++++----------
 1 file changed, 6 insertions(+), 10 deletions(-)

diff --git a/docs/proposals/error-handling-guideline.md b/docs/proposals/error-handling-guideline.md
index 14cdc8c40..ce5097e74 100644
--- a/docs/proposals/error-handling-guideline.md
+++ b/docs/proposals/error-handling-guideline.md
@@ -88,7 +88,6 @@ Suggested error message:
 ```
 $ oras tag list ghcr.io/oras-project/oras
 Error: unable to add tag for 'list': invalid reference: missing repository
-
 Usage: oras tag [flags] <name>{:<tag>|@<digest>} <new_tag> [...]
 Tag a manifest in a registry or an OCI image layout. Run "oras tag -h" for more options and examples
 ```
@@ -146,23 +145,22 @@ Error: unknown distribution specification flag: "v1.0".
 Available options: v1.1-referrers-api, v1.1-referrers-tag
 ```
 
-#### Example 6: when attaching an file, if no file reference or manifest annotation provided
+#### Example 6: when attaching an file, if no file reference is provided
 
 Current behavior and output:
 
 ```
 $ oras attach --artifact-type oras/test /tmp/ginkgo2977244222:foobar >>
-Error: no blob or manifest annotation are provided
+Error: no blob is provided
 ```
 
 Suggested error message:
 
 ```
 $ oras attach --artifact-type oras/test /tmp/ginkgo2977244222:foobar >>
-Error: no blob or manifest annotation are provided
-
+Error: no blob is provided
 Usage: oras attach [flags] --artifact-type=<type> <name>{:<tag>|@<digest>} <file>[:<type>] [...]
-Attach files to an existing artifact. Run "oras attach -h" for more options and examples
+To attach files to an existing artifact, try "oras attach --artifact-type sbom/example oras/test /tmp/ginkgo2977244222:foobar sample.txt". Run "oras attach -h" for more options and examples
 ```
 
 #### Example 7: When pushing files, if the annotation file doesn't match the required format
@@ -179,7 +177,6 @@ Suggested error message:
 ```
 $ oras push --annotation-file annotation.json ghcr.io/library/alpine:3.9
 Error: failed to load annotations from annotation.json: annotation file or syntax doesn't match the required format or syntax
-
 Please refer to the document at https://oras.land/docs/how_to_guides/manifest_annotations.
 ```
 
@@ -196,9 +193,8 @@ Suggested error message:
 
 ```
 $ oras push --annotation "key:value" ghcr.io/library/alpine:3.9
-Error: annotation value  doesn't match the required format.
-
-Try oras push --annotation "key=value" ghcr.io/library/alpine:3.9  
+Error: annotation value doesn't match the required format.
+Try `oras push --annotation "key=value" ghcr.io/library/alpine:3.9`  
 ```
 
 #### Example 9: when failed to pull files from a public registry

From 764b9bb18cb2edf1d3c1ed8ac099a87146fbd3c6 Mon Sep 17 00:00:00 2001
From: Feynman Zhou <feynmanzhou@microsoft.com>
Date: Sat, 18 Nov 2023 00:42:40 +0800
Subject: [PATCH 15/37] resolve comments and update examples

Signed-off-by: Feynman Zhou <feynmanzhou@microsoft.com>
---
 docs/proposals/error-handling-guideline.md | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/docs/proposals/error-handling-guideline.md b/docs/proposals/error-handling-guideline.md
index ce5097e74..dde847b78 100644
--- a/docs/proposals/error-handling-guideline.md
+++ b/docs/proposals/error-handling-guideline.md
@@ -26,12 +26,12 @@ Last, error logs can also be useful for post-mortem debugging but make sure they
 
 ### Dos
 
+- Provide full description if the user input does not match what ORAS CLI expected. A full description should include the actual input received from the user and expected input
 - Use the capital letter ahead of each line of any error message
 - Print human readable error message. If the error message is mainly from the server and varies by different servers, tell users that the error response is from server. This implies that users may need to contact server side for troubleshooting.
 - Provide specific and actionable prompt message with argument suggestion or show the example usage for reference. (e.g, Instead of showing flag or argument options is missing, please provide available argument options and guide users to "--help" to view more examples)
 - If the actionable prompt message is too long to show in the CLI output, consider guide users to ORAS user guide or troubleshooting guide with the permanent link.
 - If the error message is not enough for troubleshooting, guide users to use "--verbose" to print much more detailed logs
-- Provide full description if the user input does not match what ORAS CLI expected. A full description should include the actual input received from the user and expected input.
 
 ### Don'Ts
 
@@ -87,7 +87,7 @@ Suggested error message:
 
 ```
 $ oras tag list ghcr.io/oras-project/oras
-Error: unable to add tag for 'list': invalid reference: missing repository
+Error: There is no "list" sub-command for "oras tag" command.
 Usage: oras tag [flags] <name>{:<tag>|@<digest>} <new_tag> [...]
 Tag a manifest in a registry or an OCI image layout. Run "oras tag -h" for more options and examples
 ```
@@ -97,14 +97,14 @@ Tag a manifest in a registry or an OCI image layout. Run "oras tag -h" for more
 Current behavior and output:
 
 ```
-$ oras manifest fetch --oci-layout /tmp/ginkgo1163328512 >>
+$ oras manifest fetch --oci-layout /tmp/ginkgo1163328512
 Error: "/tmp/ginkgo1163328512": no tag or digest when expecting <name:tag|name@digest>
 ```
 
 Suggested error message:
 
 ```
-$ oras manifest fetch --oci-layout /tmp/ginkgo1163328512 >>
+$ oras manifest fetch --oci-layout /tmp/ginkgo1163328512
 Error: "/tmp/ginkgo1163328512": no tag or digest specified
 
 Usage: oras manifest fetch [flags] <name>{:<tag>|@<digest>}
@@ -150,15 +150,15 @@ Available options: v1.1-referrers-api, v1.1-referrers-tag
 Current behavior and output:
 
 ```
-$ oras attach --artifact-type oras/test /tmp/ginkgo2977244222:foobar >>
+$ oras attach --artifact-type oras/test /tmp/ginkgo2977244222:foobar
 Error: no blob is provided
 ```
 
 Suggested error message:
 
 ```
-$ oras attach --artifact-type oras/test /tmp/ginkgo2977244222:foobar >>
-Error: no blob is provided
+$ oras attach --artifact-type oras/test /tmp/ginkgo2977244222:foobar
+Error: failed to attach a file. No file provided in the command.
 Usage: oras attach [flags] --artifact-type=<type> <name>{:<tag>|@<digest>} <file>[:<type>] [...]
 To attach files to an existing artifact, try "oras attach --artifact-type sbom/example oras/test /tmp/ginkgo2977244222:foobar sample.txt". Run "oras attach -h" for more options and examples
 ```

From 68c8907aaed50e3c567c659c237a971523cd44a7 Mon Sep 17 00:00:00 2001
From: Feynman Zhou <feynmanzhou@microsoft.com>
Date: Wed, 29 Nov 2023 09:59:01 +0800
Subject: [PATCH 16/37] update cli error guideline

Signed-off-by: Feynman Zhou <feynmanzhou@microsoft.com>
---
 docs/proposals/error-handling-guideline.md | 22 ++++++++++++----------
 1 file changed, 12 insertions(+), 10 deletions(-)

diff --git a/docs/proposals/error-handling-guideline.md b/docs/proposals/error-handling-guideline.md
index dde847b78..e4e989c8f 100644
--- a/docs/proposals/error-handling-guideline.md
+++ b/docs/proposals/error-handling-guideline.md
@@ -1,4 +1,4 @@
-# ORAS CLI Error Handling and Message Guidelines
+# ORAS CLI Error Handling and Message Guideline
 
 This document aims to provide the guidelines for ORAS contributors to improve existing error messages and error handling method as well as the new error output format. It will also provide recommendations and examples for ORAS CLI contributors for how to write friendly and standard error messages, avoid generating inconsistent and ambiguous error messages.
 
@@ -8,11 +8,9 @@ A clear and actionable error message is very important when raising an error, so
 
 First and foremost, make the error messages descriptive and informative. Error messages are expected to be helpful to troubleshoot where the user has done something wrong and the program is guiding them in the right direction. A great error message is recommended to contain the following elements:
 
-- Error code (When the logs are generated from the server side)
-- Error title
-- Error description 
-- How to fix the error
-- Versioned document link for more information (Optional, it can be a troubleshooting or FAQ document link)
+- Error code: optional, when the logs are generated from the server side
+- Error description: describe what the error is
+- Suggestion: How to fix the error. Versioned troubleshooting document link is nice to have.
 
 Second, when necessary, it is highly suggested for ORAS CLI contributors to provide recommendations for users how to resolve the problems based on the error messages they encountered. Showing descriptive words and straightforward prompt with executable commands as a potential solution is a good practice for error messages.
 
@@ -20,6 +18,8 @@ Third, for unhandled errors you didn’t expect the user to run into. For that,
 
 Fourth, signal-to-noise ratio is crucial. The more irrelevant output you produce, the longer it’s going to take the user to figure out what they did wrong. If your program produces multiple errors of the same type, consider grouping them under a single explanatory header instead of printing many similar-looking lines.
 
+Fifth, CLI program termination should follow the standard [Exit Status conventions](https://www.gnu.org/software/libc/manual/html_node/Exit-Status.html) to report broad information about success or failure. 
+
 Last, error logs can also be useful for post-mortem debugging but make sure they have timestamps, truncate them occasionally so they don’t eat up space on disk, and make sure they don’t contain ansi color codes. Thereby, error logs can be written to a file.
 
 ## Error output recommendation
@@ -46,11 +46,15 @@ Last, error logs can also be useful for post-mortem debugging but make sure they
 Here is a sample structure of an error message:
 
 ```text
-Error: [Error code] : [Error title] : [Error description] 
+Error:[Status code]: [Error description] 
 Usage: [Command usage]
-[Recommended solution], [TSG]
+[Recommended solution]
 ```
 
+- Status code is an optional information. If the error message is generated from the server side, it may include error code or [warn code](https://www.rfc-editor.org/rfc/rfc7234#section-5.5). It could be printed out alongside the error description.
+- Command usage is also an optional information but it's recommended to be printed out when user input doesn't follow the standard usage or examples. 
+- Recommended solution is required and should follow the general guiding principles described above.
+
 ### Examples
 
 Here are some examples of writing error message with helpful prompt actionable information:
@@ -69,7 +73,6 @@ Suggested error message:
 ```
 $ oras cp
 Error: "oras copy" requires exactly 2 arguments.
-
 Usage: oras copy [flags] <from>{:<tag>|@<digest>} <to>[:<tag>[,<tag>][...]]
 Copy artifacts from one target to another. Run "oras copy -h" for more options and examples
 ```
@@ -106,7 +109,6 @@ Suggested error message:
 ```
 $ oras manifest fetch --oci-layout /tmp/ginkgo1163328512
 Error: "/tmp/ginkgo1163328512": no tag or digest specified
-
 Usage: oras manifest fetch [flags] <name>{:<tag>|@<digest>}
 Fetch manifest of the target artifact. Run "oras manifest fetch -h" for more options and examples 
 ```

From c74a6d3ffafe17be992af14ae534b92d7ccf357d Mon Sep 17 00:00:00 2001
From: Feynman Zhou <feynmanzhou@microsoft.com>
Date: Wed, 29 Nov 2023 22:59:58 +0800
Subject: [PATCH 17/37] refine CLI error guideline

Signed-off-by: Feynman Zhou <feynmanzhou@microsoft.com>
---
 docs/proposals/error-handling-guideline.md | 19 ++++++++++---------
 1 file changed, 10 insertions(+), 9 deletions(-)

diff --git a/docs/proposals/error-handling-guideline.md b/docs/proposals/error-handling-guideline.md
index e4e989c8f..7be00ce50 100644
--- a/docs/proposals/error-handling-guideline.md
+++ b/docs/proposals/error-handling-guideline.md
@@ -18,7 +18,7 @@ Third, for unhandled errors you didn’t expect the user to run into. For that,
 
 Fourth, signal-to-noise ratio is crucial. The more irrelevant output you produce, the longer it’s going to take the user to figure out what they did wrong. If your program produces multiple errors of the same type, consider grouping them under a single explanatory header instead of printing many similar-looking lines.
 
-Fifth, CLI program termination should follow the standard [Exit Status conventions](https://www.gnu.org/software/libc/manual/html_node/Exit-Status.html) to report broad information about success or failure. 
+Fifth, CLI program termination should follow the standard [Exit Status conventions](https://www.gnu.org/software/libc/manual/html_node/Exit-Status.html) to report execution status information about success or failure. 
 
 Last, error logs can also be useful for post-mortem debugging but make sure they have timestamps, truncate them occasionally so they don’t eat up space on disk, and make sure they don’t contain ansi color codes. Thereby, error logs can be written to a file.
 
@@ -118,16 +118,17 @@ Fetch manifest of the target artifact. Run "oras manifest fetch -h" for more opt
 Current behavior and output:
 
 ```
-$ oras manifest push --oci-layout /tmp/ginkgo2167255592:mediatype-flag
+$ oras manifest push --oci-layout /sample/images:foobar:mediatype
 Error: media type is not recognized. 
 ```
 
 Suggested error message:
 
 ```
-$ oras manifest push --oci-layout /tmp/ginkgo2167255592:mediatype-flag
+$ oras manifest push --oci-layout /sample/images:foobar:mediatype
 Error: media type is not recognized. 
-Specify an valid media type with "--media-type"
+Usage: oras manifest push [flags] <name>[:<tag>[,<tag>][...]|@<digest>] <file>
+Specify an valid media type with the "--media-type" flag.
 ```
 
 #### Example 5: attach an artifact if the given option is unknown
@@ -135,14 +136,14 @@ Specify an valid media type with "--media-type"
 Current behavior and output:
 
 ```
-$ oras attach --artifact-type oras/test localhost:7000/command/images:foobar --distribution-spec v1.0
+$ oras attach --artifact-type oras/test localhost:5000/command/images:foobar --distribution-spec v1.0
 Error: unknown distribution specification flag: v1.0
 ```
 
 Suggested error message:
 
 ```
-$ oras attach --artifact-type oras/test localhost:7000/command/images:foobar --distribution-spec ???
+$ oras attach --artifact-type oras/test localhost:5000/sample/images:foobar --distribution-spec ???
 Error: unknown distribution specification flag: "v1.0". 
 Available options: v1.1-referrers-api, v1.1-referrers-tag
 ```
@@ -152,17 +153,17 @@ Available options: v1.1-referrers-api, v1.1-referrers-tag
 Current behavior and output:
 
 ```
-$ oras attach --artifact-type oras/test /tmp/ginkgo2977244222:foobar
+$ oras attach --artifact-type sbom/example localhost:5000/sample/images:foobar
 Error: no blob is provided
 ```
 
 Suggested error message:
 
 ```
-$ oras attach --artifact-type oras/test /tmp/ginkgo2977244222:foobar
+$ oras attach --artifact-type sbom/example localhost:5000/sample/images:foobar
 Error: failed to attach a file. No file provided in the command.
 Usage: oras attach [flags] --artifact-type=<type> <name>{:<tag>|@<digest>} <file>[:<type>] [...]
-To attach files to an existing artifact, try "oras attach --artifact-type sbom/example oras/test /tmp/ginkgo2977244222:foobar sample.txt". Run "oras attach -h" for more options and examples
+To attach files to an existing artifact, try "oras attach --artifact-type sbom/example localhost:5000/sample/images:foobar sample.json". Run "oras attach -h" for more options and examples
 ```
 
 #### Example 7: When pushing files, if the annotation file doesn't match the required format

From 3510594db50418718a8935ebf5d274390b681255 Mon Sep 17 00:00:00 2001
From: Feynman Zhou <feynmanzhou@microsoft.com>
Date: Tue, 5 Dec 2023 12:12:19 +0800
Subject: [PATCH 18/37] refine examples

Signed-off-by: Feynman Zhou <feynmanzhou@microsoft.com>
---
 docs/proposals/error-handling-guideline.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/proposals/error-handling-guideline.md b/docs/proposals/error-handling-guideline.md
index 7be00ce50..da9322ad5 100644
--- a/docs/proposals/error-handling-guideline.md
+++ b/docs/proposals/error-handling-guideline.md
@@ -74,7 +74,7 @@ Suggested error message:
 $ oras cp
 Error: "oras copy" requires exactly 2 arguments.
 Usage: oras copy [flags] <from>{:<tag>|@<digest>} <to>[:<tag>[,<tag>][...]]
-Copy artifacts from one target to another. Run "oras copy -h" for more options and examples
+You need to specify two arguments as source and destination respectively. Run "oras copy -h" for more options and examples
 ```
 
 #### Example 2: when reference does not match with the expected format
@@ -92,7 +92,7 @@ Suggested error message:
 $ oras tag list ghcr.io/oras-project/oras
 Error: There is no "list" sub-command for "oras tag" command.
 Usage: oras tag [flags] <name>{:<tag>|@<digest>} <new_tag> [...]
-Tag a manifest in a registry or an OCI image layout. Run "oras tag -h" for more options and examples
+If you want to tag a manifest in a registry or an OCI image layout, use "oras tag". If you want to list available tags in a repository, use "oras repo show tags" 
 ```
 
 #### Example 3: When fetching a manifest if no manifest tag or digest is provided
@@ -110,7 +110,7 @@ Suggested error message:
 $ oras manifest fetch --oci-layout /tmp/ginkgo1163328512
 Error: "/tmp/ginkgo1163328512": no tag or digest specified
 Usage: oras manifest fetch [flags] <name>{:<tag>|@<digest>}
-Fetch manifest of the target artifact. Run "oras manifest fetch -h" for more options and examples 
+You need to specify an artifact reference in the form of "<name>:<tag>" or "<name>@<digest>". Run "oras manifest fetch -h" for more options and examples 
 ```
 
 #### Example 4: push a manifest if no media type flag provided
@@ -128,7 +128,7 @@ Suggested error message:
 $ oras manifest push --oci-layout /sample/images:foobar:mediatype
 Error: media type is not recognized. 
 Usage: oras manifest push [flags] <name>[:<tag>[,<tag>][...]|@<digest>] <file>
-Specify an valid media type with the "--media-type" flag.
+You need to specify a valid media type "mediaType" in the manifest JSON or via the "--media-type" flag.
 ```
 
 #### Example 5: attach an artifact if the given option is unknown

From 1792ab0d9cebb440fa0366092ef4ac79101edb64 Mon Sep 17 00:00:00 2001
From: Feynman Zhou <feynmanzhou@microsoft.com>
Date: Mon, 11 Dec 2023 21:24:24 +0800
Subject: [PATCH 19/37] update cli guideline

Signed-off-by: Feynman Zhou <feynmanzhou@microsoft.com>
---
 docs/proposals/error-handling-guideline.md | 36 +++++++++++-----------
 1 file changed, 18 insertions(+), 18 deletions(-)

diff --git a/docs/proposals/error-handling-guideline.md b/docs/proposals/error-handling-guideline.md
index da9322ad5..79599938e 100644
--- a/docs/proposals/error-handling-guideline.md
+++ b/docs/proposals/error-handling-guideline.md
@@ -10,17 +10,17 @@ First and foremost, make the error messages descriptive and informative. Error m
 
 - Error code: optional, when the logs are generated from the server side
 - Error description: describe what the error is
-- Suggestion: How to fix the error. Versioned troubleshooting document link is nice to have.
+- Suggestion: for those errors that have potential solution, print out the recommended solution. Versioned troubleshooting document link is nice to have.
 
 Second, when necessary, it is highly suggested for ORAS CLI contributors to provide recommendations for users how to resolve the problems based on the error messages they encountered. Showing descriptive words and straightforward prompt with executable commands as a potential solution is a good practice for error messages.
 
-Third, for unhandled errors you didn’t expect the user to run into. For that, have a way to view full traceback information as well as full debug or verbose logs output, and instructions on how to submit a bug.
+Third, for unhandled errors you didn't expect the user to run into. For that, have a way to view full traceback information as well as full debug or verbose logs output, and instructions on how to submit a bug.
 
-Fourth, signal-to-noise ratio is crucial. The more irrelevant output you produce, the longer it’s going to take the user to figure out what they did wrong. If your program produces multiple errors of the same type, consider grouping them under a single explanatory header instead of printing many similar-looking lines.
+Fourth, signal-to-noise ratio is crucial. The more irrelevant output you produce, the longer it's going to take the user to figure out what they did wrong. If your program produces multiple errors of the same type, consider grouping them under a single explanatory header instead of printing many similar-looking lines.
 
 Fifth, CLI program termination should follow the standard [Exit Status conventions](https://www.gnu.org/software/libc/manual/html_node/Exit-Status.html) to report execution status information about success or failure. 
 
-Last, error logs can also be useful for post-mortem debugging but make sure they have timestamps, truncate them occasionally so they don’t eat up space on disk, and make sure they don’t contain ansi color codes. Thereby, error logs can be written to a file.
+Last, error logs can also be useful for post-mortem debugging, truncate them occasionally so they don't eat up space on disk, and make sure they don't contain ansi color codes. Thereby, error logs can be written to a file.
 
 ## Error output recommendation
 
@@ -37,7 +37,7 @@ Last, error logs can also be useful for post-mortem debugging but make sure they
 
 - Do not use a formula-like or a programming expression in the error message. (e.g, `json: cannot unmarshal string into Go value of type map[string]map[string]string.`, or `Parameter 'xyz' must conform to the following pattern: '^[-\\w\\._\\(\\)]+$'`)
 - Do not use ambiguous expressions which mean nothing to users. (e.g, `Something unexpected happens`, or `Error: accepts 2 arg(s), received 0`)
-- Do not print irrelevant error message to make the output noisy. The more irrelevant output you produce, the longer it’s going to take the user to figure out what they did wrong.
+- Do not print irrelevant error message to make the output noisy. The more irrelevant output you produce, the longer it's going to take the user to figure out what they did wrong.
 
 ## How to write friendly error message
 
@@ -46,14 +46,14 @@ Last, error logs can also be useful for post-mortem debugging but make sure they
 Here is a sample structure of an error message:
 
 ```text
-Error:[Status code]: [Error description] 
-Usage: [Command usage]
-[Recommended solution]
+Error: [{Status code}:] {Error description}
+[Usage: {Command usage}]
+[{Recommended solution}]
 ```
 
-- Status code is an optional information. If the error message is generated from the server side, it may include error code or [warn code](https://www.rfc-editor.org/rfc/rfc7234#section-5.5). It could be printed out alongside the error description.
-- Command usage is also an optional information but it's recommended to be printed out when user input doesn't follow the standard usage or examples. 
-- Recommended solution is required and should follow the general guiding principles described above.
+- Status code is an optional information. Printed out the status code if the error message is generated from the server side. 
+- Command usage is also an optional information but it's recommended to be printed out when user input doesn't follow the standard usage or examples.
+- Recommended solution (if any) should follow the general guiding principles described above.
 
 ### Examples
 
@@ -148,7 +148,7 @@ Error: unknown distribution specification flag: "v1.0".
 Available options: v1.1-referrers-api, v1.1-referrers-tag
 ```
 
-#### Example 6: when attaching an file, if no file reference is provided
+#### Example 6: when attaching an file, if no file reference or annotation is provided
 
 Current behavior and output:
 
@@ -161,9 +161,9 @@ Suggested error message:
 
 ```
 $ oras attach --artifact-type sbom/example localhost:5000/sample/images:foobar
-Error: failed to attach a file. No file provided in the command.
+Error: no file or annotation provided in the command
 Usage: oras attach [flags] --artifact-type=<type> <name>{:<tag>|@<digest>} <file>[:<type>] [...]
-To attach files to an existing artifact, try "oras attach --artifact-type sbom/example localhost:5000/sample/images:foobar sample.json". Run "oras attach -h" for more options and examples
+To attach to an existing artifact, please provide files via argument or annotations via flag. Run "oras attach -h" for more options and examples
 ```
 
 #### Example 7: When pushing files, if the annotation file doesn't match the required format
@@ -172,15 +172,15 @@ Current behavior and output:
 
 ```
 $ oras push --annotation-file sbom.json ghcr.io/library/alpine:3.9
-Error: failed to load annotations from sbom.json: json: cannot unmarshal string into Go value of type map[string]map[string]string. Please refer to the document at https://oras.land/docs/how_to_guides/manifest_annotations.
+Error: failed to load annotations from sbom.json: json: cannot unmarshal string into Go value of type map[string]map[string]string. Please refer to the document at https://oras.land/docs/how_to_guides/manifest_annotations
 ```
 
 Suggested error message:
 
 ```
 $ oras push --annotation-file annotation.json ghcr.io/library/alpine:3.9
-Error: failed to load annotations from annotation.json: annotation file or syntax doesn't match the required format or syntax
-Please refer to the document at https://oras.land/docs/how_to_guides/manifest_annotations.
+Error response from registry: failed to load annotations from sbom.json: json: cannot unmarshal string into Go value of type map[string]map[string]string. 
+Annotation file doesn't match the required format. Please refer to the document at https://oras.land/docs/how_to_guides/manifest_annotations
 ```
 
 #### Example 8: When pushing files, if the annotation value doesn't match the required syntax
@@ -211,7 +211,7 @@ Suggested error message:
 
 ```
 $ oras pull docker.io/nginx:latest
-Error: failed to resolve the resource from server: pull access denied for ghcr.io/nginx:latest : response status code 401: unauthorized: requested access to the resource is denied
+Error response from registry: pull access denied for docker.io/nginx:latest : response status code 401: unauthorized: requested access to the resource is denied
 Namespace is missing, do you mean `oras pull docker.io/library/nginx:latest`? 
 ```
 

From b4f8c26de7682d5648f6a2bad082c07524d97e87 Mon Sep 17 00:00:00 2001
From: Feynman Zhou <feynmanzhou@microsoft.com>
Date: Mon, 11 Dec 2023 21:28:42 +0800
Subject: [PATCH 20/37] resolve comments

Signed-off-by: Feynman Zhou <feynmanzhou@microsoft.com>
---
 docs/proposals/error-handling-guideline.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/proposals/error-handling-guideline.md b/docs/proposals/error-handling-guideline.md
index 79599938e..ba14e06ec 100644
--- a/docs/proposals/error-handling-guideline.md
+++ b/docs/proposals/error-handling-guideline.md
@@ -163,7 +163,7 @@ Suggested error message:
 $ oras attach --artifact-type sbom/example localhost:5000/sample/images:foobar
 Error: no file or annotation provided in the command
 Usage: oras attach [flags] --artifact-type=<type> <name>{:<tag>|@<digest>} <file>[:<type>] [...]
-To attach to an existing artifact, please provide files via argument or annotations via flag. Run "oras attach -h" for more options and examples
+To attach to an existing artifact, please provide files via argument or annotations via flag "--annotation". Run "oras attach -h" for more options and examples
 ```
 
 #### Example 7: When pushing files, if the annotation file doesn't match the required format

From 7adf1aacc2c2b2821c4a961c798b8a9ca13511cb Mon Sep 17 00:00:00 2001
From: Feynman Zhou <feynmanzhou@microsoft.com>
Date: Wed, 13 Dec 2023 11:10:16 +0800
Subject: [PATCH 21/37] update CLI error guideline

Signed-off-by: Feynman Zhou <feynmanzhou@microsoft.com>
---
 docs/proposals/error-handling-guideline.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/proposals/error-handling-guideline.md b/docs/proposals/error-handling-guideline.md
index ba14e06ec..39a3f1be2 100644
--- a/docs/proposals/error-handling-guideline.md
+++ b/docs/proposals/error-handling-guideline.md
@@ -72,9 +72,9 @@ Suggested error message:
 
 ```
 $ oras cp
-Error: "oras copy" requires exactly 2 arguments.
+Error: "oras copy" requires exactly 2 arguments but received 0.
 Usage: oras copy [flags] <from>{:<tag>|@<digest>} <to>[:<tag>[,<tag>][...]]
-You need to specify two arguments as source and destination respectively. Run "oras copy -h" for more options and examples
+Please specify 2 arguments as source and destination respectively. Run "oras copy -h" for more options and examples
 ```
 
 #### Example 2: when reference does not match with the expected format
@@ -179,7 +179,7 @@ Suggested error message:
 
 ```
 $ oras push --annotation-file annotation.json ghcr.io/library/alpine:3.9
-Error response from registry: failed to load annotations from sbom.json: json: cannot unmarshal string into Go value of type map[string]map[string]string. 
+Error: invalid annotation json file: failed to load annotations from annotation.json.
 Annotation file doesn't match the required format. Please refer to the document at https://oras.land/docs/how_to_guides/manifest_annotations
 ```
 

From 5ac34afd82b62b79eb3c97572fa6198b4331493f Mon Sep 17 00:00:00 2001
From: Feynman Zhou <feynmanzhou@microsoft.com>
Date: Mon, 18 Dec 2023 11:57:37 +0800
Subject: [PATCH 22/37] resolve comments

Signed-off-by: Feynman Zhou <feynmanzhou@microsoft.com>
---
 docs/proposals/error-handling-guideline.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/proposals/error-handling-guideline.md b/docs/proposals/error-handling-guideline.md
index 39a3f1be2..957fc911b 100644
--- a/docs/proposals/error-handling-guideline.md
+++ b/docs/proposals/error-handling-guideline.md
@@ -148,7 +148,7 @@ Error: unknown distribution specification flag: "v1.0".
 Available options: v1.1-referrers-api, v1.1-referrers-tag
 ```
 
-#### Example 6: when attaching an file, if no file reference or annotation is provided
+#### Example 6: when attaching, if neither file reference nor annotation is provided
 
 Current behavior and output:
 
@@ -161,7 +161,7 @@ Suggested error message:
 
 ```
 $ oras attach --artifact-type sbom/example localhost:5000/sample/images:foobar
-Error: no file or annotation provided in the command
+Error: neither file nor annotation provided in the command
 Usage: oras attach [flags] --artifact-type=<type> <name>{:<tag>|@<digest>} <file>[:<type>] [...]
 To attach to an existing artifact, please provide files via argument or annotations via flag "--annotation". Run "oras attach -h" for more options and examples
 ```

From 6669a4e0b790a523df33f675d23d0885c7144afd Mon Sep 17 00:00:00 2001
From: Feynman Zhou <feynmanzhou@microsoft.com>
Date: Mon, 18 Dec 2023 14:11:53 +0800
Subject: [PATCH 23/37] resolve comments

Signed-off-by: Feynman Zhou <feynmanzhou@microsoft.com>
---
 docs/proposals/error-handling-guideline.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/proposals/error-handling-guideline.md b/docs/proposals/error-handling-guideline.md
index 957fc911b..1eec1056d 100644
--- a/docs/proposals/error-handling-guideline.md
+++ b/docs/proposals/error-handling-guideline.md
@@ -18,7 +18,7 @@ Third, for unhandled errors you didn't expect the user to run into. For that, ha
 
 Fourth, signal-to-noise ratio is crucial. The more irrelevant output you produce, the longer it's going to take the user to figure out what they did wrong. If your program produces multiple errors of the same type, consider grouping them under a single explanatory header instead of printing many similar-looking lines.
 
-Fifth, CLI program termination should follow the standard [Exit Status conventions](https://www.gnu.org/software/libc/manual/html_node/Exit-Status.html) to report execution status information about success or failure. 
+Fifth, CLI program termination should follow the standard [Exit Status conventions](https://www.gnu.org/software/libc/manual/html_node/Exit-Status.html) to report execution status information about success or failure. ORAS returns `EXIT_FAILURE` if and only if ORAS reports one or more errors.
 
 Last, error logs can also be useful for post-mortem debugging, truncate them occasionally so they don't eat up space on disk, and make sure they don't contain ansi color codes. Thereby, error logs can be written to a file.
 

From 52870476787caaeec94c701765ff9d56502348be Mon Sep 17 00:00:00 2001
From: Feynman Zhou <feynmanzhou@microsoft.com>
Date: Wed, 20 Dec 2023 15:43:58 +0800
Subject: [PATCH 24/37] add more examples

Signed-off-by: Feynman Zhou <feynmanzhou@microsoft.com>
---
 docs/proposals/error-handling-guideline.md | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/docs/proposals/error-handling-guideline.md b/docs/proposals/error-handling-guideline.md
index 1eec1056d..81ed515be 100644
--- a/docs/proposals/error-handling-guideline.md
+++ b/docs/proposals/error-handling-guideline.md
@@ -215,6 +215,24 @@ Error response from registry: pull access denied for docker.io/nginx:latest : re
 Namespace is missing, do you mean `oras pull docker.io/library/nginx:latest`? 
 ```
 
+#### Example 10: 
+
+Current behavior and output:
+
+```
+$ oras push /oras --format json
+Error: Head "https:///v2/oras/manifests/sha256:ffa50b27cd0096150c0338779c5090db41ba50d01179d851d68afa50b393c3a3": http: no Host in request URL
+```
+
+Suggested error message:
+
+```
+$ oras push /oras --format json
+Error: 
+Usage: 
+please specify a registry or OCI image layout folder to push
+```
+
 ## Reference
 
 Parts of the content are borrowed from these guidelines.

From 5e31ce2c716c5f4847de476b01f2f3f50a06fa24 Mon Sep 17 00:00:00 2001
From: Feynman Zhou <feynmanzhou@microsoft.com>
Date: Fri, 22 Dec 2023 16:10:18 +0800
Subject: [PATCH 25/37] resolve comments and add more examples

Signed-off-by: Feynman Zhou <feynmanzhou@microsoft.com>
---
 docs/proposals/error-handling-guideline.md | 49 +++++++++++++++++++---
 1 file changed, 43 insertions(+), 6 deletions(-)

diff --git a/docs/proposals/error-handling-guideline.md b/docs/proposals/error-handling-guideline.md
index 81ed515be..39e2cdee6 100644
--- a/docs/proposals/error-handling-guideline.md
+++ b/docs/proposals/error-handling-guideline.md
@@ -46,7 +46,7 @@ Last, error logs can also be useful for post-mortem debugging, truncate them occ
 Here is a sample structure of an error message:
 
 ```text
-Error: [{Status code}:] {Error description}
+Error: {Error|Error response from registry}: {Error description}
 [Usage: {Command usage}]
 [{Recommended solution}]
 ```
@@ -200,7 +200,7 @@ Error: annotation value doesn't match the required format.
 Try `oras push --annotation "key=value" ghcr.io/library/alpine:3.9`  
 ```
 
-#### Example 9: when failed to pull files from a public registry
+#### Example 9: When failed to pull files from a public registry
 
 ```
 $ oras pull docker.io/nginx:latest
@@ -215,7 +215,7 @@ Error response from registry: pull access denied for docker.io/nginx:latest : re
 Namespace is missing, do you mean `oras pull docker.io/library/nginx:latest`? 
 ```
 
-#### Example 10: 
+#### Example 10: Neither registry nor OCI image layout provided when pushing a folder 
 
 Current behavior and output:
 
@@ -228,9 +228,46 @@ Suggested error message:
 
 ```
 $ oras push /oras --format json
-Error: 
-Usage: 
-please specify a registry or OCI image layout folder to push
+Error: neither registry nor OCI image layout provided in the command 
+Usage: oras push [flags] <name>[:<tag>[,<tag>][...]] <file>[:<type>] [...]
+please specify a registry or an OCI image layout folder to push. Run "oras push -h" for more options and examples 
+```
+
+#### Example 11: Push a file or folder that doesn't exist
+
+Current behavior and output:
+
+```
+$ oras push localhost:5000/oras:v1 hello.txt
+Error: failed to stat /home/user/hello.txt: stat /home/user/hello.txt: no such file or directory
+```
+
+Suggested error message:
+
+```
+$ oras push localhost:5000/oras:v1 hello.txt
+Error: /home/user/hello.txt: no such file or directory
+```
+
+#### Example 12: Attach a file to an incompatible registry
+
+Current behavior and output:
+
+```
+$ oras attach docker.io/user/demo:v1 --artifact-type example/sbom sbom.spdx
+Uploading 6cb759c4296e sbom.spdx
+Uploaded  6cb759c4296e sbom.spdx
+Error: PUT "https://registry-1.docker.io/v2/user/demo/manifests/sha256:d2e409ed5674c9cf4fb5c13615288b130610ed893f97c78668ad233dc403976d": response status code 404: notfound: not found
+```
+
+Suggested error message:
+
+```
+$ oras attach docker.io/user/demo:v1 --artifact-type example/sbom sbom.spdx
+Uploading 6cb759c4296e sbom.spdx
+Uploaded  6cb759c4296e sbom.spdx
+Error response from registry: PUT "https://registry-1.docker.io/v2/user/demo/manifests/sha256:d2e409ed5674c9cf4fb5c13615288b130610ed893f97c78668ad233dc403976d": response status code 404: notfound:
+This registry doesn't support storing referrers
 ```
 
 ## Reference

From 7dccd6317e98532d33b82e3b391ed9ec68551d08 Mon Sep 17 00:00:00 2001
From: Feynman Zhou <feynmanzhou@microsoft.com>
Date: Fri, 22 Dec 2023 16:12:03 +0800
Subject: [PATCH 26/37] resolve comments and add more examples

Signed-off-by: Feynman Zhou <feynmanzhou@microsoft.com>
---
 docs/proposals/error-handling-guideline.md | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/docs/proposals/error-handling-guideline.md b/docs/proposals/error-handling-guideline.md
index 39e2cdee6..852f8e5f1 100644
--- a/docs/proposals/error-handling-guideline.md
+++ b/docs/proposals/error-handling-guideline.md
@@ -59,7 +59,7 @@ Error: {Error|Error response from registry}: {Error description}
 
 Here are some examples of writing error message with helpful prompt actionable information:
 
-#### Example 1: when no reference provided in `oras copy`
+#### Example 1: When no reference provided in `oras copy`
 
 Current behavior and output:
 
@@ -77,7 +77,7 @@ Usage: oras copy [flags] <from>{:<tag>|@<digest>} <to>[:<tag>[,<tag>][...]]
 Please specify 2 arguments as source and destination respectively. Run "oras copy -h" for more options and examples
 ```
 
-#### Example 2: when reference does not match with the expected format
+#### Example 2: When reference does not match with the expected format
 
 Current behavior and output:
 
@@ -113,7 +113,7 @@ Usage: oras manifest fetch [flags] <name>{:<tag>|@<digest>}
 You need to specify an artifact reference in the form of "<name>:<tag>" or "<name>@<digest>". Run "oras manifest fetch -h" for more options and examples 
 ```
 
-#### Example 4: push a manifest if no media type flag provided
+#### Example 4: Push a manifest if no media type flag provided
 
 Current behavior and output:
 
@@ -131,7 +131,7 @@ Usage: oras manifest push [flags] <name>[:<tag>[,<tag>][...]|@<digest>] <file>
 You need to specify a valid media type "mediaType" in the manifest JSON or via the "--media-type" flag.
 ```
 
-#### Example 5: attach an artifact if the given option is unknown
+#### Example 5: Attach an artifact if the given option is unknown
 
 Current behavior and output:
 
@@ -148,7 +148,7 @@ Error: unknown distribution specification flag: "v1.0".
 Available options: v1.1-referrers-api, v1.1-referrers-tag
 ```
 
-#### Example 6: when attaching, if neither file reference nor annotation is provided
+#### Example 6: When attaching, if neither file reference nor annotation is provided
 
 Current behavior and output:
 

From 1526f87a45855d2f27ea5314030426d3ab3b9812 Mon Sep 17 00:00:00 2001
From: Feynman Zhou <feynmanzhou@microsoft.com>
Date: Mon, 25 Dec 2023 17:51:17 +0800
Subject: [PATCH 27/37] resolve comments and refine error guideline

Signed-off-by: Feynman Zhou <feynmanzhou@microsoft.com>
---
 docs/proposals/error-handling-guideline.md | 71 +++++++++++-----------
 1 file changed, 35 insertions(+), 36 deletions(-)

diff --git a/docs/proposals/error-handling-guideline.md b/docs/proposals/error-handling-guideline.md
index 852f8e5f1..401e35d9f 100644
--- a/docs/proposals/error-handling-guideline.md
+++ b/docs/proposals/error-handling-guideline.md
@@ -8,9 +8,9 @@ A clear and actionable error message is very important when raising an error, so
 
 First and foremost, make the error messages descriptive and informative. Error messages are expected to be helpful to troubleshoot where the user has done something wrong and the program is guiding them in the right direction. A great error message is recommended to contain the following elements:
 
-- Error code: optional, when the logs are generated from the server side
+- Status code: optional, when the logs are generated from the server side, it's recommended to print the status code in the error description
 - Error description: describe what the error is
-- Suggestion: for those errors that have potential solution, print out the recommended solution. Versioned troubleshooting document link is nice to have.
+- Suggestion: for those errors that have potential solution, print out the recommended solution. Versioned troubleshooting document link is nice to have
 
 Second, when necessary, it is highly suggested for ORAS CLI contributors to provide recommendations for users how to resolve the problems based on the error messages they encountered. Showing descriptive words and straightforward prompt with executable commands as a potential solution is a good practice for error messages.
 
@@ -46,7 +46,7 @@ Last, error logs can also be useful for post-mortem debugging, truncate them occ
 Here is a sample structure of an error message:
 
 ```text
-Error: {Error|Error response from registry}: {Error description}
+{Error|Error response from registry}: {Error description}
 [Usage: {Command usage}]
 [{Recommended solution}]
 ```
@@ -63,50 +63,50 @@ Here are some examples of writing error message with helpful prompt actionable i
 
 Current behavior and output:
 
-```
+```console
 $ oras cp
 Error: accepts 2 arg(s), received 0
 ```
 
 Suggested error message:
 
-```
+```console
 $ oras cp
 Error: "oras copy" requires exactly 2 arguments but received 0.
 Usage: oras copy [flags] <from>{:<tag>|@<digest>} <to>[:<tag>[,<tag>][...]]
 Please specify 2 arguments as source and destination respectively. Run "oras copy -h" for more options and examples
 ```
 
-#### Example 2: When reference does not match with the expected format
+#### Example 2: When user mistakenly uses `tag list` command
 
 Current behavior and output:
 
-```
+```console
 $ oras tag list ghcr.io/oras-project/oras
 Error: unable to add tag for 'list': invalid reference: missing repository
 ```
 
 Suggested error message:
 
-```
+```console
 $ oras tag list ghcr.io/oras-project/oras
 Error: There is no "list" sub-command for "oras tag" command.
 Usage: oras tag [flags] <name>{:<tag>|@<digest>} <new_tag> [...]
-If you want to tag a manifest in a registry or an OCI image layout, use "oras tag". If you want to list available tags in a repository, use "oras repo show tags" 
+If you want to list available tags in a repository, use "oras repo tags" 
 ```
 
-#### Example 3: When fetching a manifest if no manifest tag or digest is provided
+#### Example 3: No tag or digest provided when fetching a manifest
 
 Current behavior and output:
 
-```
+```console
 $ oras manifest fetch --oci-layout /tmp/ginkgo1163328512
 Error: "/tmp/ginkgo1163328512": no tag or digest when expecting <name:tag|name@digest>
 ```
 
 Suggested error message:
 
-```
+```console
 $ oras manifest fetch --oci-layout /tmp/ginkgo1163328512
 Error: "/tmp/ginkgo1163328512": no tag or digest specified
 Usage: oras manifest fetch [flags] <name>{:<tag>|@<digest>}
@@ -117,32 +117,32 @@ You need to specify an artifact reference in the form of "<name>:<tag>" or "<nam
 
 Current behavior and output:
 
-```
+```console
 $ oras manifest push --oci-layout /sample/images:foobar:mediatype
 Error: media type is not recognized. 
 ```
 
 Suggested error message:
 
-```
+```console
 $ oras manifest push --oci-layout /sample/images:foobar:mediatype
 Error: media type is not recognized. 
 Usage: oras manifest push [flags] <name>[:<tag>[,<tag>][...]|@<digest>] <file>
-You need to specify a valid media type "mediaType" in the manifest JSON or via the "--media-type" flag.
+You need to specify a valid media type in the manifest JSON or via the "--media-type" flag.
 ```
 
 #### Example 5: Attach an artifact if the given option is unknown
 
 Current behavior and output:
 
-```
+```console
 $ oras attach --artifact-type oras/test localhost:5000/command/images:foobar --distribution-spec v1.0
 Error: unknown distribution specification flag: v1.0
 ```
 
 Suggested error message:
 
-```
+```console
 $ oras attach --artifact-type oras/test localhost:5000/sample/images:foobar --distribution-spec ???
 Error: unknown distribution specification flag: "v1.0". 
 Available options: v1.1-referrers-api, v1.1-referrers-tag
@@ -152,14 +152,14 @@ Available options: v1.1-referrers-api, v1.1-referrers-tag
 
 Current behavior and output:
 
-```
+```console
 $ oras attach --artifact-type sbom/example localhost:5000/sample/images:foobar
 Error: no blob is provided
 ```
 
 Suggested error message:
 
-```
+```console
 $ oras attach --artifact-type sbom/example localhost:5000/sample/images:foobar
 Error: neither file nor annotation provided in the command
 Usage: oras attach [flags] --artifact-type=<type> <name>{:<tag>|@<digest>} <file>[:<type>] [...]
@@ -170,14 +170,14 @@ To attach to an existing artifact, please provide files via argument or annotati
 
 Current behavior and output:
 
-```
+```console
 $ oras push --annotation-file sbom.json ghcr.io/library/alpine:3.9
 Error: failed to load annotations from sbom.json: json: cannot unmarshal string into Go value of type map[string]map[string]string. Please refer to the document at https://oras.land/docs/how_to_guides/manifest_annotations
 ```
 
 Suggested error message:
 
-```
+```console
 $ oras push --annotation-file annotation.json ghcr.io/library/alpine:3.9
 Error: invalid annotation json file: failed to load annotations from annotation.json.
 Annotation file doesn't match the required format. Please refer to the document at https://oras.land/docs/how_to_guides/manifest_annotations
@@ -187,29 +187,29 @@ Annotation file doesn't match the required format. Please refer to the document
 
 Current behavior and output:
 
-```
+```console
 $ oras push --annotation "key:value" ghcr.io/library/alpine:3.9
 Error: missing key in `--annotation` flag: key:value
 ```
 
 Suggested error message:
 
-```
+```console
 $ oras push --annotation "key:value" ghcr.io/library/alpine:3.9
 Error: annotation value doesn't match the required format.
-Try `oras push --annotation "key=value" ghcr.io/library/alpine:3.9`  
+Try --annotation "key=value"  
 ```
 
 #### Example 9: When failed to pull files from a public registry
 
-```
+```console
 $ oras pull docker.io/nginx:latest
 Error: failed to resolve latest: GET "https://registry-1.docker.io/v2/nginx/manifests/latest": response status code 401: unauthorized: authentication required: [map[Action:pull Class: Name:nginx Type:repository]]
 ```
 
 Suggested error message:
 
-```
+```console
 $ oras pull docker.io/nginx:latest
 Error response from registry: pull access denied for docker.io/nginx:latest : response status code 401: unauthorized: requested access to the resource is denied
 Namespace is missing, do you mean `oras pull docker.io/library/nginx:latest`? 
@@ -219,32 +219,32 @@ Namespace is missing, do you mean `oras pull docker.io/library/nginx:latest`?
 
 Current behavior and output:
 
-```
+```console
 $ oras push /oras --format json
 Error: Head "https:///v2/oras/manifests/sha256:ffa50b27cd0096150c0338779c5090db41ba50d01179d851d68afa50b393c3a3": http: no Host in request URL
 ```
 
 Suggested error message:
 
-```
+```console
 $ oras push /oras --format json
-Error: neither registry nor OCI image layout provided in the command 
+Error: "/oras" is an invalid reference
 Usage: oras push [flags] <name>[:<tag>[,<tag>][...]] <file>[:<type>] [...]
-please specify a registry or an OCI image layout folder to push. Run "oras push -h" for more options and examples 
+Please specify a valid reference in the form of <registry>/<repo>[:tag|@digest]
 ```
 
 #### Example 11: Push a file or folder that doesn't exist
 
 Current behavior and output:
 
-```
+```console
 $ oras push localhost:5000/oras:v1 hello.txt
 Error: failed to stat /home/user/hello.txt: stat /home/user/hello.txt: no such file or directory
 ```
 
 Suggested error message:
 
-```
+```console
 $ oras push localhost:5000/oras:v1 hello.txt
 Error: /home/user/hello.txt: no such file or directory
 ```
@@ -253,7 +253,7 @@ Error: /home/user/hello.txt: no such file or directory
 
 Current behavior and output:
 
-```
+```console
 $ oras attach docker.io/user/demo:v1 --artifact-type example/sbom sbom.spdx
 Uploading 6cb759c4296e sbom.spdx
 Uploaded  6cb759c4296e sbom.spdx
@@ -262,12 +262,11 @@ Error: PUT "https://registry-1.docker.io/v2/user/demo/manifests/sha256:d2e409ed5
 
 Suggested error message:
 
-```
+```console
 $ oras attach docker.io/user/demo:v1 --artifact-type example/sbom sbom.spdx
 Uploading 6cb759c4296e sbom.spdx
 Uploaded  6cb759c4296e sbom.spdx
-Error response from registry: PUT "https://registry-1.docker.io/v2/user/demo/manifests/sha256:d2e409ed5674c9cf4fb5c13615288b130610ed893f97c78668ad233dc403976d": response status code 404: notfound:
-This registry doesn't support storing referrers
+Error response from registry: This registry doesn't support storing referrers
 ```
 
 ## Reference

From 60f889e156131b33ce0ad144636ca67cdf303755 Mon Sep 17 00:00:00 2001
From: Feynman Zhou <feynmanzhou@microsoft.com>
Date: Mon, 25 Dec 2023 17:56:36 +0800
Subject: [PATCH 28/37] resolve comments

Signed-off-by: Feynman Zhou <feynmanzhou@microsoft.com>
---
 docs/proposals/error-handling-guideline.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/proposals/error-handling-guideline.md b/docs/proposals/error-handling-guideline.md
index 401e35d9f..5bf2a32e1 100644
--- a/docs/proposals/error-handling-guideline.md
+++ b/docs/proposals/error-handling-guideline.md
@@ -46,7 +46,7 @@ Last, error logs can also be useful for post-mortem debugging, truncate them occ
 Here is a sample structure of an error message:
 
 ```text
-{Error|Error response from registry}: {Error description}
+{Error|Error response from registry}: {Error description (status code can be printed out if any)}
 [Usage: {Command usage}]
 [{Recommended solution}]
 ```

From 7915e641427b303ba9e980fe66f7d8c363a649f4 Mon Sep 17 00:00:00 2001
From: Feynman Zhou <feynmanzhou@microsoft.com>
Date: Tue, 26 Dec 2023 17:01:33 +0800
Subject: [PATCH 29/37] resolve comments

Signed-off-by: Feynman Zhou <feynmanzhou@microsoft.com>
---
 docs/proposals/error-handling-guideline.md | 20 --------------------
 1 file changed, 20 deletions(-)

diff --git a/docs/proposals/error-handling-guideline.md b/docs/proposals/error-handling-guideline.md
index 5bf2a32e1..8aba5d484 100644
--- a/docs/proposals/error-handling-guideline.md
+++ b/docs/proposals/error-handling-guideline.md
@@ -249,26 +249,6 @@ $ oras push localhost:5000/oras:v1 hello.txt
 Error: /home/user/hello.txt: no such file or directory
 ```
 
-#### Example 12: Attach a file to an incompatible registry
-
-Current behavior and output:
-
-```console
-$ oras attach docker.io/user/demo:v1 --artifact-type example/sbom sbom.spdx
-Uploading 6cb759c4296e sbom.spdx
-Uploaded  6cb759c4296e sbom.spdx
-Error: PUT "https://registry-1.docker.io/v2/user/demo/manifests/sha256:d2e409ed5674c9cf4fb5c13615288b130610ed893f97c78668ad233dc403976d": response status code 404: notfound: not found
-```
-
-Suggested error message:
-
-```console
-$ oras attach docker.io/user/demo:v1 --artifact-type example/sbom sbom.spdx
-Uploading 6cb759c4296e sbom.spdx
-Uploaded  6cb759c4296e sbom.spdx
-Error response from registry: This registry doesn't support storing referrers
-```
-
 ## Reference
 
 Parts of the content are borrowed from these guidelines.

From 193ac35c2d8b812d56d4a76ca7ab4a90c18899fd Mon Sep 17 00:00:00 2001
From: Feynman Zhou <feynmanzhou@microsoft.com>
Date: Tue, 2 Jan 2024 15:44:22 +0800
Subject: [PATCH 30/37] resolve comments and refine spec

Signed-off-by: Feynman Zhou <feynmanzhou@microsoft.com>
---
 docs/proposals/error-handling-guideline.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/proposals/error-handling-guideline.md b/docs/proposals/error-handling-guideline.md
index 8aba5d484..65cfcab63 100644
--- a/docs/proposals/error-handling-guideline.md
+++ b/docs/proposals/error-handling-guideline.md
@@ -20,7 +20,7 @@ Fourth, signal-to-noise ratio is crucial. The more irrelevant output you produce
 
 Fifth, CLI program termination should follow the standard [Exit Status conventions](https://www.gnu.org/software/libc/manual/html_node/Exit-Status.html) to report execution status information about success or failure. ORAS returns `EXIT_FAILURE` if and only if ORAS reports one or more errors.
 
-Last, error logs can also be useful for post-mortem debugging, truncate them occasionally so they don't eat up space on disk, and make sure they don't contain ansi color codes. Thereby, error logs can be written to a file.
+Last, error logs can also be useful for post-mortem debugging and can also be written to a file, truncate them occasionally and make sure they don't contain ansi color codes.
 
 ## Error output recommendation
 
@@ -128,7 +128,7 @@ Suggested error message:
 $ oras manifest push --oci-layout /sample/images:foobar:mediatype
 Error: media type is not recognized. 
 Usage: oras manifest push [flags] <name>[:<tag>[,<tag>][...]|@<digest>] <file>
-You need to specify a valid media type in the manifest JSON or via the "--media-type" flag.
+You need to specify a valid media type in the manifest JSON or via the "--media-type" flag
 ```
 
 #### Example 5: Attach an artifact if the given option is unknown
@@ -197,7 +197,7 @@ Suggested error message:
 ```console
 $ oras push --annotation "key:value" ghcr.io/library/alpine:3.9
 Error: annotation value doesn't match the required format.
-Try --annotation "key=value"  
+Please use the correct format in the flag: --annotation "key=value"  
 ```
 
 #### Example 9: When failed to pull files from a public registry

From 15eb3ccc41dbcf3979e1f9da070418138ddf46e3 Mon Sep 17 00:00:00 2001
From: Feynman Zhou <feynmanzhou@microsoft.com>
Date: Tue, 2 Jan 2024 18:00:09 +0800
Subject: [PATCH 31/37] add two examples and one suggestion

Signed-off-by: Feynman Zhou <feynmanzhou@microsoft.com>
---
 docs/proposals/error-handling-guideline.md | 37 ++++++++++++++++++++--
 1 file changed, 35 insertions(+), 2 deletions(-)

diff --git a/docs/proposals/error-handling-guideline.md b/docs/proposals/error-handling-guideline.md
index 65cfcab63..c23683f6f 100644
--- a/docs/proposals/error-handling-guideline.md
+++ b/docs/proposals/error-handling-guideline.md
@@ -28,10 +28,11 @@ Last, error logs can also be useful for post-mortem debugging and can also be wr
 
 - Provide full description if the user input does not match what ORAS CLI expected. A full description should include the actual input received from the user and expected input
 - Use the capital letter ahead of each line of any error message
-- Print human readable error message. If the error message is mainly from the server and varies by different servers, tell users that the error response is from server. This implies that users may need to contact server side for troubleshooting.
+- Print human readable error message. If the error message is mainly from the server and varies by different servers, tell users that the error response is from server. This implies that users may need to contact server side for troubleshooting
 - Provide specific and actionable prompt message with argument suggestion or show the example usage for reference. (e.g, Instead of showing flag or argument options is missing, please provide available argument options and guide users to "--help" to view more examples)
-- If the actionable prompt message is too long to show in the CLI output, consider guide users to ORAS user guide or troubleshooting guide with the permanent link.
+- If the actionable prompt message is too long to show in the CLI output, consider guide users to ORAS user manual or troubleshooting guide with the versioned permanent link
 - If the error message is not enough for troubleshooting, guide users to use "--verbose" to print much more detailed logs
+- If the error message from the server side is too generic or has no value, especially in a few edge cases like example 12 and 13 below, consider providing customized and trimmed error logs to make it clearer. The original server logs can be displayed in debug mode. 
 
 ### Don'Ts
 
@@ -249,6 +250,38 @@ $ oras push localhost:5000/oras:v1 hello.txt
 Error: /home/user/hello.txt: no such file or directory
 ```
 
+#### Example 12: failed to authenticate with registry using an error credential from credential store
+
+```console
+$ oras pull localhost:7000/repo:tag --registry-config auth.config
+Error: failed to resolve tag: GET "http://localhost:7000/v2/repo/manifests/tag": credential required for basic auth
+```
+
+Suggested error message:
+
+```console
+$ oras pull localhost:7000/repo:tag --registry-config auth.config
+Error: pulling content from localhost:7000/repo:tag failed with status: 401 Unauthorized
+Please check whether the registry credential stored in the authentication file is correct
+```
+
+#### Example 13: failed to resolve the digest with incorrect username or password
+
+```console
+oras resolve localhost:7000/command/artifacts:foobar -u t -p 2
+WARNING! Using --password via the CLI is insecure. Use --password-stdin.
+Error response from registry: <nil>
+```
+
+Suggested error message:
+
+```console
+oras resolve localhost:7000/command/artifacts:foobar -u t -p 2
+WARNING! Using --password via the CLI is insecure. Use --password-stdin.
+Error: resolving the digest of artifact localhost:7000/command/artifacts:foobar failed with status: 401 Unauthorized
+Please use correct username or password
+```
+
 ## Reference
 
 Parts of the content are borrowed from these guidelines.

From c423335030d8c5129c3785e588d768dd3070d510 Mon Sep 17 00:00:00 2001
From: Feynman Zhou <feynmanzhou@microsoft.com>
Date: Tue, 2 Jan 2024 18:02:41 +0800
Subject: [PATCH 32/37] add two examples and one suggestion

Signed-off-by: Feynman Zhou <feynmanzhou@microsoft.com>
---
 docs/proposals/error-handling-guideline.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/docs/proposals/error-handling-guideline.md b/docs/proposals/error-handling-guideline.md
index c23683f6f..3f2fd8704 100644
--- a/docs/proposals/error-handling-guideline.md
+++ b/docs/proposals/error-handling-guideline.md
@@ -252,6 +252,8 @@ Error: /home/user/hello.txt: no such file or directory
 
 #### Example 12: failed to authenticate with registry using an error credential from credential store
 
+Current behavior and output:
+
 ```console
 $ oras pull localhost:7000/repo:tag --registry-config auth.config
 Error: failed to resolve tag: GET "http://localhost:7000/v2/repo/manifests/tag": credential required for basic auth
@@ -267,6 +269,8 @@ Please check whether the registry credential stored in the authentication file i
 
 #### Example 13: failed to resolve the digest with incorrect username or password
 
+Current behavior and output:
+
 ```console
 oras resolve localhost:7000/command/artifacts:foobar -u t -p 2
 WARNING! Using --password via the CLI is insecure. Use --password-stdin.

From 0f75e08b4a812a407e8d6e254855cfcd0866b76d Mon Sep 17 00:00:00 2001
From: Feynman Zhou <feynmanzhou@microsoft.com>
Date: Tue, 2 Jan 2024 18:12:13 +0800
Subject: [PATCH 33/37] resolve comments and refine spec

Signed-off-by: Feynman Zhou <feynmanzhou@microsoft.com>
---
 docs/proposals/error-handling-guideline.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/proposals/error-handling-guideline.md b/docs/proposals/error-handling-guideline.md
index 3f2fd8704..6d7e4389e 100644
--- a/docs/proposals/error-handling-guideline.md
+++ b/docs/proposals/error-handling-guideline.md
@@ -32,7 +32,7 @@ Last, error logs can also be useful for post-mortem debugging and can also be wr
 - Provide specific and actionable prompt message with argument suggestion or show the example usage for reference. (e.g, Instead of showing flag or argument options is missing, please provide available argument options and guide users to "--help" to view more examples)
 - If the actionable prompt message is too long to show in the CLI output, consider guide users to ORAS user manual or troubleshooting guide with the versioned permanent link
 - If the error message is not enough for troubleshooting, guide users to use "--verbose" to print much more detailed logs
-- If the error message from the server side is too generic or has no value, especially in a few edge cases like example 12 and 13 below, consider providing customized and trimmed error logs to make it clearer. The original server logs can be displayed in debug mode. 
+- If the error message from the server side is too generic or has no value, especially in a few edge cases like example 12 and 13 below, consider providing customized and trimmed error logs to make it clearer. The original server logs can be displayed in debug mode
 
 ### Don'Ts
 

From 0de8d595fa3dec0e29d6209f2ee0d5770f134334 Mon Sep 17 00:00:00 2001
From: Feynman Zhou <feynmanzhou@microsoft.com>
Date: Thu, 4 Jan 2024 19:07:52 +0800
Subject: [PATCH 34/37] resolve comments

Signed-off-by: Feynman Zhou <feynmanzhou@microsoft.com>
---
 docs/proposals/error-handling-guideline.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/proposals/error-handling-guideline.md b/docs/proposals/error-handling-guideline.md
index 6d7e4389e..c12090a9a 100644
--- a/docs/proposals/error-handling-guideline.md
+++ b/docs/proposals/error-handling-guideline.md
@@ -8,7 +8,7 @@ A clear and actionable error message is very important when raising an error, so
 
 First and foremost, make the error messages descriptive and informative. Error messages are expected to be helpful to troubleshoot where the user has done something wrong and the program is guiding them in the right direction. A great error message is recommended to contain the following elements:
 
-- Status code: optional, when the logs are generated from the server side, it's recommended to print the status code in the error description
+- HTTP status code: optional, when the logs are generated from the server side, it's recommended to print the HTTP status code in the error description
 - Error description: describe what the error is
 - Suggestion: for those errors that have potential solution, print out the recommended solution. Versioned troubleshooting document link is nice to have
 
@@ -47,12 +47,12 @@ Last, error logs can also be useful for post-mortem debugging and can also be wr
 Here is a sample structure of an error message:
 
 ```text
-{Error|Error response from registry}: {Error description (status code can be printed out if any)}
+{Error|Error response from registry}: {Error description (HTTP status code can be printed out if any)}
 [Usage: {Command usage}]
 [{Recommended solution}]
 ```
 
-- Status code is an optional information. Printed out the status code if the error message is generated from the server side. 
+- HTTP status code is an optional information. Printed out the HTTP status code if the error message is generated from the server side. 
 - Command usage is also an optional information but it's recommended to be printed out when user input doesn't follow the standard usage or examples.
 - Recommended solution (if any) should follow the general guiding principles described above.
 
@@ -283,7 +283,7 @@ Suggested error message:
 oras resolve localhost:7000/command/artifacts:foobar -u t -p 2
 WARNING! Using --password via the CLI is insecure. Use --password-stdin.
 Error: resolving the digest of artifact localhost:7000/command/artifacts:foobar failed with status: 401 Unauthorized
-Please use correct username or password
+Authentication failed. Please verify your login credentials and try again.
 ```
 
 ## Reference

From aaeb6bb5546556f76a8c5f8b9edc8c819834579b Mon Sep 17 00:00:00 2001
From: Feynman Zhou <feynmanzhou@microsoft.com>
Date: Tue, 9 Jan 2024 12:20:11 +0800
Subject: [PATCH 35/37] resolve comments

Signed-off-by: Feynman Zhou <feynmanzhou@microsoft.com>
---
 docs/proposals/error-handling-guideline.md | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/docs/proposals/error-handling-guideline.md b/docs/proposals/error-handling-guideline.md
index c12090a9a..5934e6d00 100644
--- a/docs/proposals/error-handling-guideline.md
+++ b/docs/proposals/error-handling-guideline.md
@@ -32,7 +32,7 @@ Last, error logs can also be useful for post-mortem debugging and can also be wr
 - Provide specific and actionable prompt message with argument suggestion or show the example usage for reference. (e.g, Instead of showing flag or argument options is missing, please provide available argument options and guide users to "--help" to view more examples)
 - If the actionable prompt message is too long to show in the CLI output, consider guide users to ORAS user manual or troubleshooting guide with the versioned permanent link
 - If the error message is not enough for troubleshooting, guide users to use "--verbose" to print much more detailed logs
-- If the error message from the server side is too generic or has no value, especially in a few edge cases like example 12 and 13 below, consider providing customized and trimmed error logs to make it clearer. The original server logs can be displayed in debug mode
+- If server returns an error without any [message or detail](https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc.3/spec.md#error-codes), such as the example 13 below, consider providing customized and trimmed error logs to make it clearer. The original server logs can be displayed in debug mode
 
 ### Don'Ts
 
@@ -114,20 +114,20 @@ Usage: oras manifest fetch [flags] <name>{:<tag>|@<digest>}
 You need to specify an artifact reference in the form of "<name>:<tag>" or "<name>@<digest>". Run "oras manifest fetch -h" for more options and examples 
 ```
 
-#### Example 4: Push a manifest if no media type flag provided
+#### Example 4: Push a manifest if no media type provided
 
 Current behavior and output:
 
 ```console
-$ oras manifest push --oci-layout /sample/images:foobar:mediatype
+$ oras manifest push --oci-layout /sample/images:foobar:mediatype manifest.json
 Error: media type is not recognized. 
 ```
 
 Suggested error message:
 
 ```console
-$ oras manifest push --oci-layout /sample/images:foobar:mediatype
-Error: media type is not recognized. 
+$ oras manifest push --oci-layout /sample/images:foobar:mediatype manifest.json
+Error: media type is not specified via the flag "--media-type" nor in the manifest.json 
 Usage: oras manifest push [flags] <name>[:<tag>[,<tag>][...]|@<digest>] <file>
 You need to specify a valid media type in the manifest JSON or via the "--media-type" flag
 ```
@@ -212,7 +212,7 @@ Suggested error message:
 
 ```console
 $ oras pull docker.io/nginx:latest
-Error response from registry: pull access denied for docker.io/nginx:latest : response status code 401: unauthorized: requested access to the resource is denied
+Error response from registry: pull access denied for docker.io/nginx:latest : unauthorized: requested access to the resource is denied
 Namespace is missing, do you mean `oras pull docker.io/library/nginx:latest`? 
 ```
 
@@ -263,11 +263,11 @@ Suggested error message:
 
 ```console
 $ oras pull localhost:7000/repo:tag --registry-config auth.config
-Error: pulling content from localhost:7000/repo:tag failed with status: 401 Unauthorized
+Error: failed to authenticate when attempting to pull: no valid credential found in auth.config
 Please check whether the registry credential stored in the authentication file is correct
 ```
 
-#### Example 13: failed to resolve the digest with incorrect username or password
+#### Example 13: failed to resolve the digest with empty error response from registry
 
 Current behavior and output:
 
@@ -282,7 +282,7 @@ Suggested error message:
 ```console
 oras resolve localhost:7000/command/artifacts:foobar -u t -p 2
 WARNING! Using --password via the CLI is insecure. Use --password-stdin.
-Error: resolving the digest of artifact localhost:7000/command/artifacts:foobar failed with status: 401 Unauthorized
+Error response from registry: empty response body: failed to resolve digest: HEAD "http://localhost:7000/v2/test/manifests/bar": response status code 401: Unauthorized
 Authentication failed. Please verify your login credentials and try again.
 ```
 

From d8f921b1bfbdce77a9743fec54eeb3cb32d8a696 Mon Sep 17 00:00:00 2001
From: Feynman Zhou <feynmanzhou@microsoft.com>
Date: Tue, 9 Jan 2024 12:24:50 +0800
Subject: [PATCH 36/37] resolve comments

Signed-off-by: Feynman Zhou <feynmanzhou@microsoft.com>
---
 docs/proposals/error-handling-guideline.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/proposals/error-handling-guideline.md b/docs/proposals/error-handling-guideline.md
index 5934e6d00..7d217eaa6 100644
--- a/docs/proposals/error-handling-guideline.md
+++ b/docs/proposals/error-handling-guideline.md
@@ -250,7 +250,7 @@ $ oras push localhost:5000/oras:v1 hello.txt
 Error: /home/user/hello.txt: no such file or directory
 ```
 
-#### Example 12: failed to authenticate with registry using an error credential from credential store
+#### Example 12: Failed to authenticate with registry using an error credential from credential store
 
 Current behavior and output:
 
@@ -267,7 +267,7 @@ Error: failed to authenticate when attempting to pull: no valid credential found
 Please check whether the registry credential stored in the authentication file is correct
 ```
 
-#### Example 13: failed to resolve the digest with empty error response from registry
+#### Example 13: Failed to resolve the digest with empty error response from registry
 
 Current behavior and output:
 

From 5568f2c6ee6451a8f7dc93e003d08c8373540b12 Mon Sep 17 00:00:00 2001
From: Feynman Zhou <feynmanzhou@microsoft.com>
Date: Tue, 16 Jan 2024 13:38:46 +0800
Subject: [PATCH 37/37] Update docs/proposals/error-handling-guideline.md

Co-authored-by: Billy Zha <qweeah@gmail.com>
Signed-off-by: Feynman Zhou <feynmanzhou@microsoft.com>
---
 docs/proposals/error-handling-guideline.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/proposals/error-handling-guideline.md b/docs/proposals/error-handling-guideline.md
index 7d217eaa6..5792671ab 100644
--- a/docs/proposals/error-handling-guideline.md
+++ b/docs/proposals/error-handling-guideline.md
@@ -282,7 +282,7 @@ Suggested error message:
 ```console
 oras resolve localhost:7000/command/artifacts:foobar -u t -p 2
 WARNING! Using --password via the CLI is insecure. Use --password-stdin.
-Error response from registry: empty response body: failed to resolve digest: HEAD "http://localhost:7000/v2/test/manifests/bar": response status code 401: Unauthorized
+Error response from registry: recognizable error message not found: failed to resolve digest: HEAD "http://localhost:7000/v2/test/manifests/bar": response status code 401: Unauthorized
 Authentication failed. Please verify your login credentials and try again.
 ```