doc (spec): add error message guideline

docs/proposals/error-handling-guideline.md

@@ -20,18 +20,19 @@ 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
 
 ### 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.
+- 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
 
@@ -128,7 +129,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 +198,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
@@ -249,6 +250,42 @@ $ 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
+
+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
+```
+
+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
+
+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.
+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.