oras-project
add document links to error messages consistently
In https://github.com/oras-project/oras/pull/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.
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.
I would want to work on this issue. PR #1026 was also done by me with with help of @qweeah. Consider me if possible.
@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.