v1 Conformance Criteria

Zowe Explorer Conformance Evaluation Criteria (Version 1)

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 ad 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 v1 LTS Release.

Zowe Explorer - Zowe v1

Zowe Explorer - Zowe v1

General Extension

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

Item	Ver	Required	Best Practice	Criteria
1	v1	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	v1		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	v1	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	v1	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	v1		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, and avoids starting setting names with the prefix `zowe.`, which is reserved for Zowe Explorer.
6	v1		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.
7	v1		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.
8	v1	x		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 extension that utilize them.
9		Mark (a) or (b) or (c)		Extension uses the extensibility APIs provided by Zowe Explorer. Supported methods include: (Please select all that apply _a_, _b_, or _c_)
				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	Criteria
10	v1	x	VS Code extension dependency: Extension declares Zowe Explorer as a VS Code extension dependency by including an `extensionDependencies` entry for Zowe Explorer in its package.json file.
11	v1	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.
12	v1	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.

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	Criteria
13	v1	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
14	v1		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.
15	v1	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.
16	v1		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.
17	v1		x	Base Profile and Tokens: Extension supports base profiles and tokens (For more information, click here)
18	v1		x	Team Configuration File: Extension supports the Zowe CLI 7 team configuration file format as an alternative to the Zowe CLI 6 profiles file format.
19	v1		x	Secure Credential Store: If the extension supports Zowe CLI's Secure Credential store, it calls the Zowe Explorer-provided method for initialization at startup.

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	Criteria
20	v1	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.
21	v1	x		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".
22	v1	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.
23	v1		x	Menu Names: 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.
24	v1		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.