add document links to error messages consistently

[qweeah]

In #1026, the doc link of manifest annotation was added to the error output. The ad-hoc solution provides better UX on finding the solution of the error but raises a challenge for updating the link when the doc is changed.

We need to find and apply a good practice to manage the mapping between an error and its related doc, e.g. standardize error codes in ORAS CLI and provide a common guide for error handling.

[FeynmanZhou]

Adding multiple different doc links to the CLI output is not a sustainable way to maintain it since the doc links may change anytime. To resolve this challenge, I think we could design unique error IDs with detailed description for different response codes and provide a central troubleshooting doc. This is similar to the OCI Distribution Spec (error code).

The error messages always point to the same troubleshooting doc page, such as https://oras.land/docs/troubleshooting. We can guide users to different solutions/docs in the troubleshooting doc.

[1Shubham7]

I would want to work on this issue. PR #1026 was also done by me with with help of @qweeah. Consider me if possible.

[FeynmanZhou]

@qweeah Do you think we can close this PR now?

[qweeah]

@qweeah Do you think we can close this PR now?

No. The proposed unique error IDs and troubleshooting doc page (e.g. https://oras.land/docs/troubleshooting) is not implemented yet.