v2 Conformance Criteria

Zowe Explorer Conformance Evaluation Criteria (Version 2)

The Zowe Conformance Evaluation Criteria is a set of self-certifying and self-service tests to help the development community integrate and extend specific technology into the Zowe framework.

This document describes the requirements of the three available conformance programs. Items marked (required) are required for an application to be conformant. Items marked (best practice) are considered best practices for conformant applications.

For more details, technical guidance, and code samples for achieving these criteria see the README-Extending.md.

Throughout this document you will find the following terminology being used:

• Extender: The organization or developer producing an extension for Zowe Explorer.
• Zowe Explorer Extension: An installable piece of software that provides new functionality to Zowe Explorer or uses/calls services provided by Zowe Explorer. Also simply referred to here as an "extension", this can be a VS 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 Zowe Explorer extensions, but it is possible that more kinds of extensions can be created. If such new extension kinds surface, then Zowe Explorer APIs and this document can be expanded to support them in the future.
• Zowe Explorer VS Code extension: Refers to a Zowe Explorer extension that is a VS Code extension that is installed in addition to Zowe Explorer and that has a VS Code extension dependency to Zowe Explorer.
• Zowe SDKs are SDKs published by the Zowe project that provides various APIs for writing Zowe-based capabilities in general.

These Zowe Conformance criteria are applicable to the latest Zowe v2 LTS Release.

• Zowe Explorer - Zowe v2
  • General Extension
  • Extension Accessing Profiles
  • Data Provider Extension
  • Extension Adding Menus

Zowe Explorer - Zowe v2

General Extension

General conformance criteria for all extensions that add new capabilities to Zowe Explorer.

Item	Ver	Required	Best Practice	Conformant	Criteria
1	v2	x			Naming: If the extension uses the word "Zowe" in its name, it abides by The Linux Foundation Trademark Usage Guidelines and Branding Guidelines to ensure the word Zowe is used in a way intended by the Zowe community.
2	v2		x		No Zowe CLI plugin installation requirement: If the extender makes use of a Zowe CLI profile other than the Zowe Explorer default `zosmf` then the extension must not make any assumptions that a matching Zowe CLI plugin has been installed in the Zowe Explorer user's environment.
3	v2	x			Publication tag: If the extension is published in a public catalog or marketplace such as Npmjs, Open-VSX, or VS 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.
4	v2	x			Support: Extension has documentation with instructions on how to report problems that are related to the extension and not Zowe Explorer. It needs to explain how users can determine if a problem is related to the extension or Zowe Explorer.
5	v2		x		User settings consistency: Extender provides a consistent user settings experience. For VS Code extensions, extender follows the recommended naming convention for configuration settings as described in VS Code's configuration contribution documentation
6	v2	x			Using .zowe in user settings: Extender avoids starting setting names with the prefix `zowe.`, which is reserved for Zowe Explorer and and other extensions maintained by the Zowe Project .
7	v2		x		Error message consistency: Extension follows the recommended error message format indicated in the Zowe Explorer extensibility documentation to provide a consistent user experience with Zowe Explorer.
8	v2		x		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.
9	v2	x			Sharing of profiles with Zowe CLI: Extensions that utilize Zowe CLI profiles must keep the shared profile instances compatible between Zowe CLI and the Zowe Explorer extension that utilize them.
10		Mark all that apply,(a) (b) (c)			Extension uses the extensibility APIs provided by Zowe Explorer. Supported methods include: (Please select all that apply)
					a. Extension Accessing Profiles
					b. Data Provider Extension
					c. Extension Adding Menus

Extension Accessing Profiles

Criteria for VS Code extensions that want to access the same Zowe CLI profiles that Zowe Explorer uses.

Item	Ver	Required	Best Practice	Conformant	Criteria
11	v2	x			VS Code extension dependency: If the extension calls the Zowe Explorer API it must declare Zowe Explorer as a VS Code extension dependency by including an extensionDependencies entry for Zowe Explorer in its package.json file. This ensures Zowe Explorer and Zowe Explorer API are activated and initialized for proper use by its extenders
12	v2	x			Zowe Extender access: Extension accesses the shared Zowe Explorer profiles cache via `ZoweExplorerApi.IApiRegisterClient.getExplorerExtenderApi()` API as documented in the Zowe Explorer extensibility documentation.
13	v2	x			Added Profile Type initialization: If the extension has a dependency on a new Zowe CLI profile type other than the Zowe Explorer 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.
14	v2		x		Base Profile and Tokens: Extension supports base profiles and tokens
15	v2	x			Team Configuration File: Extension supports the Zowe CLI 7 team configuration file format.
16	v2		x		v1 Profile Support: Extension has a backwards compatibility and it is able to support v1 type of profiles.

Data Provider Extension

Criteria for VS Code extensions that extend the Zowe Explorer MVS, USS, or JES tree views to use alternative z/OS interaction protocols such as FTP or a REST API.

Item	Ver	Required	Best Practice	Conformant	Criteria
17	v2	x			VS Code extension dependency: If the extension calls the Zowe Explorer API it must declare Zowe Explorer as a VS Code extension dependency by including an extensionDependencies entry for Zowe Explorer in its package.json file. This ensures Zowe Explorer and Zowe Explorer API are activated and initialized for proper use by its extenders
18	v2	x			New Zowe CLI profile type: Extension registers its new API instances with a new profile type name for the different Zowe Explorer views via the `ZoweExplorerApi.IApiRegisterClient.register{Mvs|Uss|Jes}Api(profileTypeName)` call as indicated from the Zowe Explorer extensibility documentation
19	v2		x		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 extension using Zowe CLI commands.
20	v2	x			Data provider API implementation: Extension fully implements and registers to at least one of the three Zowe Explorer 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.
21	v2		x		API test suite implementation: If the extension implements a Zowe Explorer API data provider interface, it should implement a test suite that calls each of the implemented API methods.

Extension Adding Menus

Criteria for VS Code extensions adding menu and commands to VS Code that utilize Zowe Explorer data or extend Zowe Explorer capabilities.

Item	Ver	Required	Best Practice	Conformant	Criteria
22	v2		x		VS Code extension dependency: If the extension calls the Zowe Explorer API it should declare Zowe Explorer as a VS Code extension dependency by including an extensionDependencies entry for Zowe Explorer in its package.json file. This ensures Zowe Explorer and Zowe Explorer API are activated and initialized for proper use by its extenders
23	v2	x			Command operations: If the extension is adding new commands to Zowe Explorer's tree views, the commands must not replace any existing Zowe Explorer commands.
24	v2		x		Command categories 1: If the extension adds to contributes.commands in package.json, the value assigned to the category property contains the extension name.
25	v2	x			Command categories 2: If the extension assigns values to the category property in contributes.commands in package.json, the value cannot be "Zowe Explorer".
26	v2	x			Context menu groups: If contributing commands to Zowe Explorer's context menus, the extension follows the Zowe Explorer extensibility documentation and adds them in new context menu groups that are located below Zowe Explorer's existing context menu groups in the user interface.
27	v2		x		Adding New Menu Items: If the extension is adding new commands and context menu entries to the Zowe Explorer tree view nodes, the new command name is consistent with the terminology and naming conventions of the existing Zowe Explorer menu entries. More information is provided in the Zowe Explorer extensibility documentation.
28	v2	x			Existing Menu Items: Extension does not overwrite any existing Zowe Explorer command and context menu entries
29	v2	x			Context menu items: If contributing commands to Zowe Explorer's views (such as Data Sets, USS, or Jobs), the extension should only add them to the view's right-click context menus.