Zowe Explorer for Visual Studio Code Conformance (#222)

Signed-off-by: jp669844 <[email protected]>
Signed-off-by: John Mertic <[email protected]>

zowe_conformance/participation_form.md

@@ -94,6 +94,18 @@ Initial Version and Components of Zowe Conformance Program tests for Conformance
 >
 > \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_
 
+- [ ] **Zowe Explorer for Visual Studio Code - Zowe v1**
+
+> Please list any items where your offering does not meet the criteria set forth in the Test Evaluation Guide:
+>
+> \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_
+>
+> \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_
+>
+> \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_
+>
+> \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_
+
 - [ ] **Zowe Conformant Support Provider - API Mediation layer - Zowe v1**
 
 > Please list any items where you, as a Participant applying for Participant Conformance, do not meet the criteria set forth in the Test Evaluation Guide:
@@ -130,7 +142,7 @@ Initial Version and Components of Zowe Conformance Program tests for Conformance
 >
 > \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_
 
-- [ ] **Zowe Conformant Support Provider - Zowe Explorer for VS Code - Zowe v1**
+- [ ] **Zowe Conformant Support Provider - Zowe Explorer for Visual Studio Code - Zowe v1**
 
 > Please list any items where you, as a Participant applying for Participant Conformance, do not meet the criteria set forth in the Test Evaluation Guide:
 >

zowe_conformance/test_evaluation_guide.md

@@ -261,3 +261,81 @@ These Zowe Conformant criteria are applicable to the lastest Zowe v1 LTS Release
 14. **Support**
 
     The Submitter describes how Support is provided. Support details must be clearly documented.
+
+
+##  Zowe Explorer for Visual Studio Code - Zowe v1
+
+Throughout the this Zowe Explorer for Visual Studio Code section you will find the following terminology being used:
+
+- <a id="extender"></a> _Extender_: The organization or developer producing an extension for Zowe Explorer for Visual Studio Code.
+- <a id="extension"></a> _Extension of Zowe Explorer for Visual Studio Code_: An installable piece of software that provides new functionality to Zowe Explorer for Visual Studio Code or uses/calls services provided by Zowe Explorer for Visual Studio Code. Also simply referred to here as an "extension", this can be a Visual Studio Code extension as well as a Zowe CLI Plugin or an independent piece of software. The conformance criteria below call out conformance requirements for three common types of extensions of Zowe Explorer for Visual Studio Code, but it is possible that more kinds of extensions can be created. If such new extension kinds surface, then Zowe Explorer for Visual Studio Code APIs and this document can be expanded to support them in the future.
+- _Zowe Explorer for Visual Studio Code - Visual Studio Code extension_: Refers to a Zowe Explorer for Visual Studio Code extension that is a Visual Studio Code extension that is installed in addition to Zowe Explorer for Visual Studio Code ad that has a Visual Studio Code extension dependency to Zowe Explorer for Visual Studio Code.
+- <a id="zowe-sdk"></a> _Zowe SDKs_ are [SDKs published by the Zowe project](https://docs.zowe.org/stable/user-guide/sdks-using) that provides various APIs for writing Zowe-based capabilities in general.
+
+1. **General Extension**
+
+    General conformance criteria for all extensions that add new capabilities to Zowe Explorer for Visual Studio Code.
+
+    a. If the extension uses the word "Zowe" in its name, it abides by The Linux Foundation <a href="https://www.linuxfoundation.org/trademark-usage/">Trademark Usage Guidelines</a> and <a href="https://www.openmainframeproject.org/branding-guidelines">Branding Guidelines</a> to ensure the word Zowe is used in a way intended by the Zowe community. **(required)**
+
+    b. No Zowe CLI plugin installation requirement: </b> If the <a href="#extender">extender</a> makes use of a Zowe CLI profile other than the Zowe Explorer for Visual Studio Code default `zosmf` then the extension must not make any assumptions that a matching Zowe CLI plugin has been installed in the Zowe Explorer for Visual Studio Code user's environment. **(best practice)**
+
+    c. **Publication tag:** If the extension is published in a public catalog or marketplace such as Npmjs, Open-VSX, or Visual Studio Code Marketplace, it uses the tag or keyword "Zowe" so it can be found when searching for Zowe and be listed with other Zowe offerings. **(required)**
+
+    d. **Support:** Extension has documentation with instructions on how to report problems that are related to the extension and not Zowe Explorer for Visual Studio Code. It needs to explain how users can determine if a problem is related to the extension or Zowe Explorer for Visual Studio Code. **(required)**
+
+    e. **User settings consistency:** <a href="#extender">Extender</a> provides a consistent user settings experience. For Visual Studio Code extensions, <a href="#extender">extender</a> follows the recommended naming convention for configuration settings as described in Visual Studio Code's <a href="https://code.visualstudio.com/api/references/contribution-points#contributes.configuration">configuration contribution documentation</a>, and avoids starting setting names with the prefix `zowe.`, which is reserved for Zowe Explorer for Visual Studio Code. **(best practice)**
+
+    f. **Error message consistency:** Extension follows the recommended error message format indicated in the Zowe Explorer for Visual Studio Code extensibility documentation to provide a consistent user experience with Zowe Explorer for Visual Studio Code. **(best practice)**
+
+    g. **Zowe SDK usage:** Extension utilizes the available Zowe SDKs that standardize z/OS interactions as well as other common capabilities that are used by many other Zowe extensions and tools unless the extension's goal is to provide a new implementation with clearly stated goals. **(best practice)**
+
+    h. **Sharing of profiles with Zowe CLI:** Extensions that utilize Zowe CLI profiles must share the created profile instances between Zowe CLI and the Zowe Explorer for Visual Studio Code extension that utilize them. **(required)**
+
+    i. Extension uses the extensibility APIs provided by Zowe Explorer for Visual Studio Code. Supported methods include (Please select all that apply):
+    - Extension Accessing Profiles
+    - Data Provider Extension
+    - Extension Adding Menus
+
+2. **Extension Accessing Profiles**
+
+    Criteria for Visual Studio Code extensions that want to access the same Zowe CLI profiles that Zowe Explorer for Visual Studio Code uses.
+
+    a. **Visual Studio Code extension dependency:** Extension declares Zowe Explorer for Visual Studio Code as a Visual Studio Code extension dependency by including an `extensionDependencies` entry for Zowe Explorer for Visual Studio Code in its package.json file. **(required)**
+
+    b. **Zowe <a href="#extender">Extender</a> access:** Extension accesses the shared Zowe Explorer for Visual Studio Code profiles cache via `ZoweExplorerApi.IApiRegisterClient.getExplorerExtenderApi()` API as documented in the Zowe Explorer for Visual Studio Code extensibility documentation. **(required)**
+
+    c. **Added Profile Type initialization:** If the extension has a dependency on a new Zowe CLI profile type other than the Zowe Explorer for Visual Studio Code default `zosmf`, it is calling the `ZoweExplorerApi.IApiRegisterClient.getExplorerExtenderApi().initialize(profileTypeName)` to ensure that the profile type is supported and managed by the extension without a Zowe CLI plugin installed. **(required)**
+
+3. **Data Provider Extension**
+
+    Criteria for Visual Studio Code extensions that extend the Zowe Explorer for Visual Studio Code MVS, USS, or JES tree views to use alternative z/OS interaction protocols such as FTP or a REST API.
+
+    a. **New Zowe CLI profile type:** Extension registers its new API instances with a new profile type name for the different Zowe Explorer for Visual Studio Code views via the `ZoweExplorerApi.IApiRegisterClient.register{Mvs|Uss|Jes}Api(profileTypeName)` call as indicated from the Zowe Explorer for Visual Studio Code extensibility documentation. **(required)**
+
+    b. **Matching Zowe CLI Plugin:** Provide a Zowe CLI Plugin for the data provider's new profile type that implements the core capabilities required for the new protocol that users can then also use to interact with the protocol outside of the Zowe Explorer for Visual Studio Code extension using Zowe CLI commands. **(best practice)**
+
+    c. **Data provider API implementation:** Extension fully implements and registers to at least one of the three Zowe Explorer for Visual Studio Code interfaces or alternatively throw exceptions that provide meaningful error messages to the end-user in the 'Error.message' property that will be displayed in a dialog. **(required)**
+
+    d. **API test suite implementation:**  If the extension implements a Zowe Explorer for Visual Studio Code API data provider interface, it should implement a test suite that calls each of the implemented API methods. **(best practice)**
+
+    e. **Base Profile and Tokens:** Extension supports base profiles and tokens. **(best practice)**
+
+    f. **Team Configuration File:** Extension supports the Zowe CLI 7 team configuration file format as an alternative to the Zowe CLI 6 profiles file format. **(best practice)**
+
+    g. **Secure Credential Store:** If the extension supports Zowe CLI's Secure Credential store, it calls the Zowe Explorer for Visual Studio Code-provided method for initialization at startup. **(best practice)**
+
+4. **Extension Adding Menus**
+
+    Criteria for Visual Studio Code extensions adding menu and commands to Visual Studio Code that utilize Zowe Explorer for Visual Studio Code data or extend Zowe Explorer for Visual Studio Code capabilities.
+
+    a. **Command operations:** If the extension is adding new commands to Zowe Explorer for Visual Studio Code's tree views, the commands must not replace any existing Zowe Explorer for Visual Studio Code commands. **(required)**
+
+    b. **Command categories:** If the extension adds to `contributes.commands` in `package.json`, the value assigned to the `category` property contains the extension name and it cannot be "Zowe Explorer for Visual Studio Code". **(required)**
+
+    c. **Context menu groups:** If contributing commands to Zowe Explorer for Visual Studio Code's context menus, the extension follows the Zowe Explorer for Visual Studio Code extensibility documentation and adds them in new context menu groups that are located below Zowe Explorer for Visual Studio Code's existing context menu groups in the user interface. **(required)**
+
+    d. **Menu Names:** If the extension is adding new commands and context menu entries to the Zowe Explorer for Visual Studio Code tree view nodes, the new command name is consistent with the terminology and naming conventions of the existing Zowe Explorer for Visual Studio Code menu entries. **(best practice)**
+
+    e. **Context menu items:** If contributing commands to Zowe Explorer for Visual Studio Code's views (such as Data Sets, USS, or Jobs), the extension should only add them to the view's right-click context menus. **(best practice)**
+