V1 Conformance - Create a best practice documentation for error handling

As part of the conformance criteria, we would like Zowe Explorer to have a Best Practice Documenation on how to implement error handling.

V1 Conformance requirement is a documentation. In this document, we would like to advise extenders on how they are going to display their error message.

My proposal is

1. to use this format: Extension Name - Error Message
2. To throw a not implemented error for Zowe Explorer APIs that are not implemented in their extension

V2 requirement is an API: We would like to have an API that will allow users to call and pass their error message. It may still use the proposed format above. Additionally, we could implement error codes for better debugging (e.g. APIML Error Codes)

[jellypuno]

@katelynienaber Similar to what FTP ext is doing here

[katelynienaber]

More thoughts after talking with @lauren-li …

Test branch is here. Logger is here. Example of use is here.

I tagged people I think can answer the questions. But ofc anyone can add to this as they like 😃

Questions for @JillieBeanSim:

• How would this API setup for the logger work with the cics extension? Specifically, the current WIP setup has a dependency on VSCode…

Questions for @VitGottwald & @nickImbirev:

• We have a problem with this function. It has a dependency on VSCode AND our profiles API. To solve this, can we create the basic logging functions as a base class & profiles prompting function as an extension of this base class? similar to ZosmfCommonApi & ZosmfUssApi. Then people could skip the import of the extended class if they don’t want the profiles dependency…
• Error codes? How to tell which error we have, without doing something like if (string.includes("I am an error")) { ... ?

Research needed:

• Can we get name of extension from package.json with VSCode’s API? (In error messages, we must add identifying info about the extension name that caused the error)

Conclusions

• The new logging API functions should not be in the zowe-explorer-api/src/profiles API folder, because they depend on VSCode. Maybe we can make some new file in the tree folder…
• Localization: Extenders should pass our logger localized strings. They would run localization themselves.