From a37a9c7bfc6a2b1c37430ce3fc31ac01cdf897ad Mon Sep 17 00:00:00 2001 From: jp669844 Date: Fri, 3 Jun 2022 15:29:31 +0200 Subject: [PATCH] Testing criteria tables update from v1 to v2 Signed-off-by: jp669844 --- ...support_provider_evaluation_guide_table.md | 271 +- .../test_evaluation_guide_table.md | 3250 +++++++++-------- 2 files changed, 1959 insertions(+), 1562 deletions(-) diff --git a/zowe_conformance/support_provider_evaluation_guide_table.md b/zowe_conformance/support_provider_evaluation_guide_table.md index b98e7f9..b8b3335 100644 --- a/zowe_conformance/support_provider_evaluation_guide_table.md +++ b/zowe_conformance/support_provider_evaluation_guide_table.md @@ -10,10 +10,10 @@ This guide describes the requirements of the support conformance program. All Ap - [Zowe Security](#zowe-security) - [Zowe Fix Strategy](#zowe-fix-strategy) - [Zowe Support Components Section](#zowe-support-components-section) - - [Zowe Component Requirements: API Mediation Layer](#zowe-component-requirements--api-mediation-layer) - - [Zowe Component Requirements: App Framework](#zowe-component-requirements--app-framework) - - [Zowe Component Requirements: Command Line Interface](#zowe-component-requirements--command-line-interface) - - [Zowe Component Requirements: Explorer](#zowe-component-requirements--explorer) + - [Zowe Component Requirements: API Mediation Layer](#zowe-component-requirements-api-mediation-layer) + - [Zowe Component Requirements: App Framework](#zowe-component-requirements-app-framework) + - [Zowe Component Requirements: Command Line Interface](#zowe-component-requirements-command-line-interface) + - [Zowe Component Requirements: Explorer](#zowe-component-requirements-explorer) ## Zowe Support Core Section @@ -21,95 +21,87 @@ This guide describes the requirements of the support conformance program. All Ap - - - - - - + + + + + + - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + +
Item NumberProgram VersionRequiredBest PracticeConformant (Yes/No)CriteriaItemVersionRequiredBest PracticeConformantCriteria
1V1x Support Provider agrees: to provide capable support for the given authenticated binary(s) of the Zowe core component(s) being attested to for the version(s) of Zowe defined in this version of the Zowe Support Provider Conformance program.
- Capable Support is defined as having necessary hardware, software, and persons to diagnose issues, code solutions, test solutions, and provide fixes for issues in a reasonable timeframe.
- Zowe core component(s) are defined at this site.
- Authenticated binaries are defined as those applicable to a given Zowe Core component and that passes the verification process (see here). -
2V1x Support Provider agrees: to abide by the applicable license associated with the Zowe source code which produced the authenticated binaries. -
1v2
x
Support Provider agrees: to provide capable support for the given authenticated binary(s) of the Zowe core component(s) being attested to for the version(s) of Zowe defined in this version of the Zowe Support Provider Conformance program.
+Capable Support is defined as having necessary hardware, software, and persons to diagnose issues, code solutions, test solutions, and provide fixes for issues in a reasonable timeframe.
Zowe core component(s) are defined here.
+Authenticated binaries are defined as those applicable to a given Zowe Core component and that passes the verification process (see here).
2v2
x
Support Provider agrees: to abide by the applicable license associated with the Zowe source code which produced the authenticated binaries.
### Zowe Security - - - - - - + + + + + + - - - - - - - - - - + + + + + + + + + +
Item NumberProgram VersionRequiredBest PracticeConformant (Yes/No)CriteriaItemVersionRequiredBest PracticeConformantCriteria
3V1x Support Provider agrees: to follow the Security Reporting Process outlined in the Zowe Docs Report Security Issues section when reporting security vulnerabilities (see here). -
3v2
x
Support Provider agrees: to follow the Security Reporting Process outlined in the Zowe Docs Report Security Issues section when reporting security vulnerabilities (see here)
### Zowe Fix Strategy - - - - - - + + + + + + - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + +
Item NumberProgram VersionRequiredBest PracticeConformant (Yes/No)CriteriaItemVersionRequiredBest PracticeConformantCriteria
4V1x Support Provider agrees: to the extent that code is contributed upstream to the Zowe project by the Support Provider, the Support Provider would make such contributions adhere to the Zowe project contribution guidelines (see here). -
5V1x Support Provider agrees: that it is able to both create and apply emergency fixes to the authenicated binary, including emergency fixes that may come from a third-party. Further, the Support Provider agrees to adhere to any requirements of the applicable license for the emergency fix. An emergency fix is defined as a change made to the components in the authenicated binary to resolve an issue which is deemed urgent or critical for use of the authenicated binary. -
4v2
x
Support Provider agrees: to the extent that code is contributed upstream to the Zowe project by the Support Provider, the Support Provider would make such contributions adhere to the Zowe project contribution guidelines (see here).
5v2
x
Support Provider agrees: that it is able to both create and apply emergency fixes to the authenicated binary, including emergency fixes that may come from a third-party. Further, the Support Provider agrees to adhere to any requirements of the applicable license for the emergency fix. An emergency fix is defined as a change made to the components in the authenicated binary to resolve an issue which is deemed urgent or critical for use of the authenicated binary.
## Zowe Support Components Section @@ -123,94 +115,95 @@ This guide describes the requirements of the support conformance program. All Ap For each of the applicable COMPONENT SECTIONS selected, **Support Provider Applicant confirms Capable Support as defined in item (1)** (mark each applicable section as conformant in "Conformant" column). -### Zowe Component Requirements: API Mediation Layer +### Zowe Component Requirements: API Mediation Layer - - - - - - + + + + + + - - - - - - - - - + + + + + + + + + +
Item NumberProgram VersionRequiredBest PracticeConformantCriteriaItemVersionRequiredBest PracticeConformantCriteria
6V1x Support Provider confirms: Capable Support as defined in item (1) -
6v2
x
 Support Provider confirms: Capable Support as defined in item (1)
-### Zowe Component Requirements: App Framework +### Zowe Component Requirements: App Framework - - - - - - + + + + + + - + - - - - - - + + + + + + +
Item NumberProgram VersionRequiredBest PracticeConformantCriteriaItemVersionRequiredBest PracticeConformantCriteria
7V1x Support Provider confirms: Capable Support as defined in item (1) - 7v2
x
Support Provider confirms: Capable Support as defined in item (1)
-### Zowe Component Requirements: Command Line Interface +### Zowe Component Requirements: Command Line Interface - - - - - - + + + + + + - + - - - - - - + + + + + + +
Item NumberProgram VersionRequiredBest PracticeConformantCriteriaItemVersionRequiredBest PracticeConformantCriteria
8V1x Support Provider confirms: Capable Support as defined in item (1) - 8v2
x
 Support Provider confirms: Capable Support as defined in item (1)
-### Zowe Component Requirements: Explorer +### Zowe Component Requirements: Explorer - - - - - - + + + + + + - + - - - - - + + + + + -
Item NumberProgram VersionRequiredBest PracticeConformantCriteriaItemVersionRequiredBest PracticeConformantCriteria
9V1x9v2
x
 Support Provider confirms: Capable Support as defined in item (1)
+ + \ No newline at end of file diff --git a/zowe_conformance/test_evaluation_guide_table.md b/zowe_conformance/test_evaluation_guide_table.md index 1ac441f..e8d71d3 100644 --- a/zowe_conformance/test_evaluation_guide_table.md +++ b/zowe_conformance/test_evaluation_guide_table.md @@ -2,12 +2,12 @@ The Zowe Conformance Test Evaluation Guide 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 guide 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. +This guide describes the requirements of the four 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. -These Zowe Conformance criteria are applicable to the lastest Zowe v1 LTS Release. +These Zowe Conformance criteria are applicable to the lastest Zowe LTS Release. - [Zowe Conformance Test Evaluation Guide](#zowe-conformance-test-evaluation-guide) - - [Zowe API Mediation Layer - Zowe v1](#zowe-api-mediation-layer---zowe-v1) + - [Zowe API Mediation Layer](#zowe-api-mediation-layer) - [Application Service](#application-service) - [REST API Documentation](#rest-api-documentation) - [REST API Naming and Addressing](#rest-api-naming-and-addressing) @@ -16,1534 +16,1938 @@ These Zowe Conformance criteria are applicable to the lastest Zowe v1 LTS Releas - [Versioning and Support](#versioning-and-support) - [WebSocket Services](#websocket-services) - [Directory and File Ownership Permissions](#directory-and-file-ownership-permissions) - - [Lifecycling as a Zowe address space](#lifecycling-as-a-zowe-address-space) + - [Packaging](#packaging) - [Support](#support) - - [Zowe CLI - Zowe v1](#zowe-cli---zowe-v1) + - [Zowe CLI](#zowe-cli) - [Infrastructure](#infrastructure) - [Installation](#installation) - [Naming](#naming) - [Profiles](#profiles) - [Support](#support-1) - - [Zowe App Framework - Zowe v1](#zowe-app-framework---zowe-v1) - - [Packaging](#packaging) + - [Documentation](#documentation) + - [Zowe Application Framework](#zowe-application-framework) + - [Packaging](#packaging-1) + - [Packaging Format and Manifest](#packaging-format-and-manifest) - [Web UIs All](#web-uis-all) - - [Web UI iframe](#web-ui-iframe) - - [Web UI Non iframe](#web-ui-non-iframe) + - [Web UI IFrame](#web-ui-iframe) + - [Web UI Non-IFrame](#web-ui-non-iframe) - [UI Design](#ui-design) - - [Localization and Internationalization l10n and l18n](#localization-and-internationalization-l10n-and-l18n) + - [Localization and Internationalization (l10n and l18n)](#localization-and-internationalization-l10n-and-l18n) - [App Server](#app-server) - - [Documentation](#documentation) + - [Documentation](#documentation-1) - [Logging](#logging) - [Encoding](#encoding) - [Storage](#storage) - [Directory and File Ownership Permissions](#directory-and-file-ownership-permissions-1) - - [Lifecycling as a Zowe address space](#lifecycling-as-a-zowe-address-space-1) + - [Lifecycling as a Zowe address space](#lifecycling-as-a-zowe-address-space) - [Support](#support-2) - - [Zowe Explorer for Visual Studio Code - Zowe v1](#zowe-explorer-for-visual-studio-code---zowe-v1) + - [Zowe Explorer for Visual Studio Code](#zowe-explorer-for-visual-studio-code) - [General Extension](#general-extension) - - [Extension Accessing Profiles](#extension-accessing-profiles) - - [Data Provider Extension](#data-provider-extension) - - [Extension Adding Menus](#extension-adding-menus) + - [[a] Extension Interacts with mainframe assets delivered by Zowe Explorer](#a-extension-interacts-with-mainframe-assets-delivered-by-zowe-explorer) + - [[b] Extension Accessing Profiles](#b-extension-accessing-profiles) + - [[c] Extension Serves as a Data Provider](#c-extension-serves-as-a-data-provider) + - [[d] Extension Adding Menus](#d-extension-adding-menus) -## Zowe API Mediation Layer - Zowe v1 +## Zowe API Mediation Layer -### Application Service +### Application Service - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Item Ver Required Best Practice Conformant Criteria
1v1xThe product or applications that extends Zowe API ML must provide at least one API service registered with the Zowe API ML Discovery Service
2Mark (a) or (b)A service must be registered using one of the following methods:

(Mark which one applies _a_ or _b_).

v1xa. Dynamic Registration
v1xb. Static Definition
3v1xThe service must provide a default service ID that is prefixed by the organization/provider name. -

Examples of compliant service IDs:

zowemonitoring, cajclcheck, ibmims, rocketterasam

Examples of non-compliant service IDs:

jclcheck, myims, mydb2

Note: The API ID is not part of the URL.

4v1xThe service ID must be configurable externally after deployment
5v1xThe service ID must be lower case, contain no symbols, and have a maximum of 64 characters
6v1xThe API ID must follow the same rules for Java packages.

Example of the API ID: zowe.apiml.apicatalog

7v1xThe published service URL must follow the gateway URL conventions
8VersionedFor versioned APIs, the service URL must contain a service version before the service ID in the following formats:

(Mark only one section - Versioned or Non-Versioned)

v1x - api/v1/{serviceId} reserved for REST APIs
v1x - ui/v1/{serviceId} reserved for UIs
v1x - ws/v1/{serviceId} reserved for WebSockets
Non-VersionedFor non-versioned APIs or APIs versioned differently (e.g. z/OSMF), use the following formats:
v1x - api/{serviceId} reserved for REST APIs
v1x - ui/{serviceId} reserved for UIs
v1x - ws/{serviceId} reserved for WebSockets
v1x - graphql/{serviceId} reserved for GraphQL APIs
9Mark (a) or (b) or (c)Registration of the service must not be performed by modifying the Zowe runtime directory api-defs folder. Supported methods include:

(Mark which one applies _a_, _b_, _c_, or _d_)

v1xa. Adding the static API definition YAML file path to instance.env file for the Zowe workspace
v1xb. Copying the static API definition YAML file to the instance directory workspace api-definitions directory
v1xc. Adding the path of a launch component to the instance.env file for the Zowe workspace
v1xd. Dynamic registration of an application that is NOT lifecycled as a Zowe address space /td> -
ItemVersionRequiredBest PracticeConformantCriteria
1v2
x
The product or applications that extends Zowe API ML must provide at least one API service registered with the Zowe API ML Discovery Service
2 Mark (a) or (b)A service must be registered using one of the following methods
  [please mark which one applies (a) or (b)]:
v2
x
a.  Dynamic Registration
v2
x
b . Static Definition 
3v2
x
The service must provide a default service ID that is prefixed by the organization/provider name.
Examples of compliant service IDs:
zowemonitoring, bcmjclcheck, ibmims, rocketterasam
Examples of non-compliant service IDs:
jclcheck, myims, mydb2
Note: The service ID is part of the URL
4v2
x
The service ID must be configurable externally after deployment
5v2
x
The service ID must be written in lower case, contain no symbols, and is limited to 64 characters
6v2
x
Services must provide API ID to provide grouping of APIs provided by multiple services. The API ID is for example used for Automated CLI Client Configuration. The API ID must be prefixed by the organization/provider name. Example of the API ID: zowe.apiml.apicatalog
Note: API ID isn't part of the URL
7v2
x
The published service URL must follow the gateway URL conventions
8VersionedFor versioned APIs, service URLs must contain a service ID in the first place in the path, before the service version (all formats). Example formats: (Mark only one section - Versioned or Non-Versioned)
v2
x
- {serviceId}/api/v1 reserved for REST APIs
v2
x
- {serviceId}/ui/v1 reserved for UIs
v2
x
- {serviceId}/ws/v1 reserved for WebSockets
 Non-VersionedFor non-versioned APIs or APIs versioned differently (e.g. z/OSMF), use the following formats: 
v2
x
- {serviceId}/api reserved for REST APIs
v2
x
- {serviceId}/ui reserved for UIs
v2
x
- {serviceId}/ws reserved for WebSockets
v2
x
- {serviceId}/graphql reserved for GraphQL APIs
9 Mark
 (a), (b) or (c)		Registration of the service must be performed via one of the supported methods: (Mark which one applies _a_, _b_, _c_)
v2
x
a. Adding the static API definition YAML file path to zowe.yaml
v2
x
b. Copying the static API definition YAML file to the workspace api-definitions directory
v2
x
c. Dynamic registration of an application
### REST API Documentation - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Item Ver Required Best Practice Conformant Criteria
10v1xDocumentation is Swagger/Open API 2.0/Open API 3.0 compliant
11v1xEvery public resource is documented with a description of each resource
12v1xEvery method of each public REST endpoint is documented
13v1xEvery method of each public REST endpoint is demonstrated with an example
14v1xEvery parameter (headers, query parameters, payloads, cookies, etc.) is documented with definitions of all possible values and their associated meanings
15v1xEvery HTTP error code must be documented. If the endpoint has additional, more granular error codes, only provide the documentation reference.
+ +Item +Version +Required +Best Practice +Conformant +Criteria + + + +10 +v2 +
x
+ + +Documentation is Swagger/Open API 2.0/Open API 3.0 compliant + + +11 +v2 +
x
+ + +Every public resource is documented with a description of each end-point + + +12 +v2 +
x
+ + +Every method of each public REST endpoint is documented + + +13 +v2 +
x
+ + +Every method of each public REST endpoint is demonstrated by example. The examples are part of the documentation. + + +14 +v2 +
x
+ + +Every parameter (headers, query parameters, payload, cookies, status codes etc.) is documented with definitions of all possible values and their associated meanings + + +15 +v2 +
x
+ + +Every HTTP error code must be documented. If the endpoint has additional and more granular error codes only provide the documentation reference. + + + ### REST API Naming and Addressing - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Item Ver Required Best Practice Conformant Criteria
16v1xEncoded slash is not used
17v1xThe service interprets values independent of their URL encoding
18v1xlowerCamelCase is used for names of resources, parameters, and JSON properties
+ +Item +Version +Required +Best Practice +Conformant +Criteria + + + +16 +v2 + +
x
+ +Encoded slash is not used + + +17 +v2 +
x
+ + +The service interprets values independent of their URL encoding + + +18 +v2 + +
x
+ +lowerCamelCase is used for names of resources, parameters, and JSON properties + + + ### Service Requests and Responses - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Item Ver Required Best Practice Conformant Criteria
19v1xREST API - Request and response payloads are in JSON or binary data format
20v1xREST API - in JSON format, use relative links, and must not contain schema, hostname, and port. Alternatively, an absolute link can be used, in which case the service must translate the link to the form that goes through the Gateway that is based on the X-Forwarded-* Headers
21v1xWebSocket (if applicable) - Service URIs contained in WebSocket messages payload are addressed through the API ML Gateway
22v1xUI (if applicable) - The UI uses relative links and does not contain the schema, hostname, and port. Alternatively an absolute link can be used, in which case the service must translate the link to the form that goes through the Gateway that is based on the X-Forwarded-* Headers
+ +Item +Version +Required +Best Practice +Conformant +Criteria + + + +19 +v2 + +
x
+ +REST API - Request and response payloads are in JSON or binary data format + + +20 +v2 +
x
+ + +REST API - - Since in JSON format, links are relative, links in responses payloads should not contain the schema, hostname, and port. Alternatively, an absolute link can be used, in which case the service must translate the link to the form that goes through the Gateway that is based on the X-Forwarded-* Headers. + + +21 +v2 +
x
+ + +WebSocket (if applicable) - Service URIs contained in WebSocket messages payload are addressed through the API ML Gateway + + +22 +v2 +
x
+ + +UI (if applicable) - The UI uses relative links and does not contain the schema, hostname, and port. Alternatively an absolute link can be used, in which case the service must translate the link to the form that goes through the Gateway that is based on the X-Forwarded-* Headers + + + ### Authentication and Authorization - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Item Ver Required Best Practice Conformant Criteria
23v1xResources are protected by mainframe credentials
24v1xServices accept basic authentication or Single-Sign-On Support as explained in the point 25 (minimum requirement)
25v1xSingle-Sign-On Support: Services accept EITHER Zowe JWT token in the cookie OR support of PassTickets
- - ### Versioning and Support + +Item +Version +Required +Best Practice +Conformant +Criteria + + + +23 +v2 +
x
+ + +Resources are protected by SAF authorization. All Single-Sign-On methods under item 23 are based on SAF authentication. + + +24 +Please mark which apply (a), (b) or (c) + +Services support Single-Sign-On using at least one of the following methods
[please mark which apply (a), (b) or (c)]: + + + +

v2

+ +
x
+ + +(a) Services accept PassTickets in the Authorization header of the HTTP requests using the basic authentication scheme (httpBasicPassTicket). + + +v2 +
x
+ + +(b) Services accept Zowe JWT token in the cookie (zoweJwt) + + +v2 +
x
+ + +(c) Services accept SAF Identity Token in the cookie (safIdt) + + + - - - - - - - - - - - - - - - - - - - - - - - - - - -
Item Ver Required Best Practice Conformant Criteria
26v1xService implementation follows the semantic versioning model
27v1xThe last two major versions are supported by API services
- - ### WebSocket Services +### Versioning and Support - - - - - - - - - - - - - - - - - - - - - - - - - -
Item Ver Required Best Practice Conformant Criteria
28v1xWebSocket connection creation, all subsequent communication between WebSocket client, and server is routed through the API ML Gateway
29v1xWebSocket connections are closed by the initiator through API ML Gateway
- - ### Directory and File Ownership Permissions + +Item +Version +Required +Best Practice +Conformant +Criteria + + + +25 +v2 + +
x
+ +Service implementation follows the semantic versioning model + + +26 +v2 +
x
+ + +Last two major versions are supported by API services + + + - - - - - - - - - - - - - - - - - - - - - - - - - - -
Item Ver Required Best Practice Conformant Criteria
30v1xA conformant application must not modify the contents of the Zowe runtime USS directory and must not change any directory or file permissions or ownership within the Zowe runtime
31v1xA conformant application must not modify the permissions or ownership of a Zowe instance directory workspace
+### WebSocket Services -### Lifecycling as a Zowe address space + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ItemVersionRequiredBest PracticeConformantCriteria
27v2
x
WebSocket connection creation, all subsequent communication between WebSocket client, and server is routed through the API ML Gateway
28v2
x
WebSocket connections are closed by the initiator through API ML Gateway
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Item Ver Required Best Practice Conformant Criteria
32Applicable if LIFECYCLEDSatisfy the following criteria to lifecycle a service with Zowe:
v1xContains a fully qualified path in the instance.env file for the Zowe workspace which points to the location of a directory containing a start.sh script
v1xContains a validate.sh script
v1xContains a configure.sh script
33v1xIf the service introduces new variables to the instance.env file, these variables should be prefixed by the provider ID to avoid collisions
- - - ### Support +### Directory and File Ownership Permissions - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + +
Item Ver Required Best Practice Conformant Criteria
ItemVersionRequiredBest PracticeConformantCriteria
29v2
x
A conformant application must not modify the contents of the Zowe runtime USS directory and it must not change any directory or file permissions or ownership within the Zowe runtime
30v2
x
A conformant application must not modify the permissions or ownership of a Zowe instance directory workspace.  
- - 34 - v1 - x - - - The Submitter describes how support is provided. Support details must be clearly documented. - +### Packaging + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ItemVersionRequiredBest PracticeConformantCriteria
Applicable if LIFECYCLEDSatisfy the following criteria to lifecycle a service with Zowe. By lifecycling we mean that Zowe Launcher will start, configure, validate and stop the service:
31v2
x
If the extension is standalone (not bundled with other products), the extension convenience build (non-SMPE) MUST package itself into zip, tar, or pax format.
32v2
x
The extension MUST package a manifest.yaml (or manifest.yml, or manifest.json) into final package.
33v2
x
If the extension is standalone (not bundled with other products), the manifest file MUST be placed in the root directory after it’s extracted or installed.
34v2
x
The extension manifest MUST contain "name" definition.
35v2
x
It's recommended to define "version" in the extension manifest.
36v2
x
It's recommended to define "license" in the extension manifest .
37v2
x
It's recommended to define "title" and "description" in the extension manifest.
38v2
x
It's recommended to define "build" in the extension manifest to describe the source code information from version control systems.
39v2
x
The extension is suggested to define “commands.install”, “commands.configure”, and/or “commands.start” to instruct Zowe how to install, configure or start in Zowe context.
40v2
x
If the extension contains services that will be registered under API-ML, those services MUST be defined as entries of "apimlServices" in the extension manifest.
- +### Support -# + + + + + + + + + + + + + + + + + + + +
ItemVersionRequiredBest PracticeConformantCriteria
41v2
x
Submitter describes how Support is provided and Support details are clearly documented
-## Zowe CLI - Zowe v1 +## Zowe CLI -### Infrastructure +### Infrastructure - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Item Ver Required Best Practice Conformant Criteria
1v1xThe plug-in is constructed on the Imperative CLI Framework
2v1xThe plug-in does not run as a standalone CLI (e.g. does not specify a bin field in package.json or other similar techniques to run standalone)
3v1xThe plug-in commands write to stdout or stderr via Imperative Framework response.console APIs
+ +Item +Version +Required +Best Practice +Conformant +Criteria + + + +1 +v2 +
x
+ + +Plug-in is constructed on the Imperative CLI Framework + + +2 +v2 +
x
+ + +Plug-in is NOT run as a standalone CLI + + +3 +v2 +
x
+ + +Plug-in commands write to stdout or stderr via Imperative Framework response.console APIs + + +4 +v2 +
x
+ + +If plug-in requires gzip decompression support, leverage the Core CLI built-in support -- do NOT opt-out of the built-in gzip decompression support (specifically, the `mDecode` property of the Imperative RestClient must NOT be overridden). + + +5 +v2 +
x
+ + +Plug-ins must not have an @zowe/cli peer dependency for improved npm@7 compatibility. The only peer dependencies that should be included are packages which are imported in the plug-in's source code (e.g., @zowe/imperative). + + +6 +v2 + +
x
+ +In their Imperative config file (defined in the imperative.configurationModule property of package.json), plug-ins should make their imports as few and specific as possible. This can significantly decrease their load time (example). + + +7 +v2 + +
x
+ +HTTP or HTTPS requests to REST APIs should use the @zowe/imperative RestClient instead of a direct dependency on a 3rd-party package like request or axios. + + + + ### Installation - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Item Ver Required Best Practice Conformant Criteria
4v1xThe plug-in is installable with the zowe plugins install command
5v1xThe plug-in is installable into the @zowe-v1-lts version of the core Zowe CLI and follows semantic versioning
6v1xThe plug-in is uninstallable via the zowe plugins uninstall command
- - ### Naming + +Item +Version +Required +Best Practice +Conformant +Criteria + + + +8 +v2 +
x
+ + +Plug-in is installable with the zowe plugins install command + + +9 +v2 +
x
+ + +Plug-in is installable into the @zowe-vN-lts version of the core Zowe CLI and follows semantic versioning (where "N" = the latest "active" LTS release number) + + +10 +v2 +
x
+ + +Plug-in is uninstallable via the zowe plugins uninstall command + + +11 +v2 +
x
+ + +`@latest` should point to the same version as the most recent zowe lts tag (Note: for V2 it will be `@zowe-v2-lts`) + + + + +### Naming - - - - - - - - - - - - - - - - - -
Item Ver Required Best Practice Conformant Criteria
7v1xIf the plug-in introduces a command group name, it must not conflict with existing conformant plug-in group names
+ +Item +Version +Required +Best Practice +Conformant +Criteria + + + +12 +v2 +
x
+ + +If the plug-in introduces a command group name, it does not conflict with existing conformant plug-in group names + + +13 +v2 + +
x
+ +Names of CLI commands/groups/options must be in kebab case (lower case & hyphens). Names of properties in zowe.config.json should be camel case. Only alphanumeric characters should be used - `[a-zA-Z0-9-]+`. + + +14 +v2 +
x
+ + +The following option names/aliases are reserved and must not be used: --response-format-json, --rfj, --help, -h, --help-examples, --help-web, --hw + + + ### Profiles - - - - - - - - - - - - - - - - - - - - - - - - - -
Item Ver Required Best Practice Conformant Criteria
8v1xIf the plug-in has unique connection details, it introduces a profile that lets users store these details for repeated use
9v1xPlug-in users are able to override all profile settings via the command line and/or environment variables
- - ### Support + +Item +Version +Required +Best Practice +Conformant +Criteria + + + +15 +v2 +
x
+ + +If the plug-in has unique connection details, it introduces a profile that lets users store these details for repeated use + + +16 +v2 + +
x
+ +Plug-in users are able to override all profile settings via the command line and/or environment variables + + +17 +v2 +
x
+ + +If the plug-in uses a Zowe API-ML integrated API, it (the plug-in) has an option named `base-path` in the profile to used to house the path of the associated service in the API ML. + + +18 +v2 +
x
+ + +If the plug-in connects to a service, it must include the following profile properties AND they MUST be these exact properties (e.g. host, NOT hostname): 'host', 'port', 'user', 'password' + + +19 +v2 +
x
+ + +If the plug-in connects to a service, and the service supports logging in with a token, it must include the following profile properties AND they MUST be these exact properties: 'tokenType', 'tokenValue' + + +20 +v2 +
x
+ + +If the plug-in connects to a service, and the service supports logging in with PEM certificates, it must include the following profile properties AND they MUST be these exact properties: 'certFile', 'certKeyFile' + + +21 +v2 +
x
+ + +If the plug-in connects to a service, and the service supports logging in with PFX/P12 certificates, it must include the following profile properties AND they MUST be these exact properties: 'certFile', 'certFilePassphrase' + + +22 +v2 +
x
+ + +If the plug-in provides an option to reject untrusted certificates, the property must be named “rejectUnauthorized”. CLI option should be reject-unauthorized. + + +23 +v2 + +
x
+ +The plug-in specifies options to be pre-filled by default in zowe.config.json once `zowe config init` has executed + + +24 +v2 +
x
+ + +Plug-in supports team-profile config + + +25 +v2 +
x
+ + +Plug-in supports base profiles + + +26 +v2 + +
x
+ +When host, port, user, or password is missing for a particular command and no default value is set, the user is prompted for the argument. Host, user, and password should NOT have default values. + + +27 +v2 +
x
+ + +To take advantage of the new 'zowe config auto-init' command, a plugin that works with a single-sign-on, APIML-compliant REST service MUST supply a new object within its plugin definition to identify that REST service. The new IImperative.apimlConnLookup object must be in the plugin's definition. That object includes the apiId and gatewayUrl of the corresponding REST service. The related REST service must also supply its apiId and gatewayUrl in the apiml section of its application.yml definition. Zowe-CLI automatically handles the apimlConnLookup object for the 'zosmf' service. Thus an apimlConnLookup object for 'zosmf' does not have to be specified within a plugin. + + + + +### Support - - - - - - - - - - - - - - - - - -
Item Ver Required Best Practice Conformant Criteria
10v1xThe Submitter describes how support is provided. Support details must be clearly documented.
- -# - -## Zowe App Framework - Zowe v1 + +Item +Version +Required +Best Practice +Conformant +Criteria + + + +28 +v2 +
x
+ + +Submitter describes how Support is provided and Support details are clearly documented + + + + +### Documentation + + + + + + + + + + + + + + + + + + + + +
ItemVersionRequiredBest PracticeConformantCriteria
29v2
x
Plug-in command help is contributed to this repo for the purpose of hosting the ecosystem web-help on Zowe Docs - https://github.com/zowe/zowe-cli-web-help-generator
+ +## Zowe Application Framework ### Packaging - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Item Ver Required Best Practice Conformant Criteria
1v1xEvery plugin must have a unique ID. The ID format follows java package naming conventions. The Zowe project reserves org.zowe
2v1xEvery plugin and each of its services must have a version
3v1xThe directory layout adheres to the App filesystem structure
4v1xSource code is recommended, but not required to adhere to the App filesystem structure for tooling consistency
- - ### Web UIs All - - - - - - - - - - - - - - - - - - - -
Item Ver Required Best Practice Conformant Criteria
5v1xAll Apps must contain an icon image file to represent it, located at code>web/assets/icon.png within the App's package
- -### Web UI iframe - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Item Ver Required Best Practice Conformant Criteria
6v1xIframe Apps (apps with framework type "iframe") which embed a top-level iframe within them must use the ID "zluxIframe" for that element.

Example: https://github.com/zowe/api-layer/blob/master/zlux-api-catalog/web/index.html

This is required for the app to be a recipient of app to app communication.
7v1xZowe resources must be accessed via the iframe-adapter located within zlux-app-manager/bootstrap/web. The use of window.parent or window.top to access the ZoweZLUX object is non-permissible.
8v1xDocumentation or automated addition of the "iframe" plugin to the Zowe desktop must be performed by executing the zowe-install-app.sh script in the Zowe instance directory
- - -### Web UI Non iframe - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Item Ver Required Best Practice Conformant Criteria
9v1xDOM elements originating from your App are children of the Zowe viewport DOM element, com-rs-mvd-viewport
10v1xNetwork requests to the Zowe App Server must never be done without the use of the URI Broker. This ensures compatibility with future versions of Zowe if URLs change.
11v1xAccess to resources outside the App Server should be made through the URI Broker whenever possible
12v1xApps must not pollute the global namespace with regards Javascript, HTML, and CSS
13v1xWhen using a library present in the Zowe App Framework core, you must depend on the same version
14v1xWeb apps should extend the framework's default build scripts for webpack and typescript.
+ +Item +Version +Required +Best Practice +Conformant +Criteria + + + +1 +v2 +
x
+ + +Every plugin must have a unique ID. The ID format follows java package naming conventions. The Zowe project reserves org.zowe + + +2 +v2 +
x
+ + +Every plugin and each of its services must have a version + + +3 +v2 +
x
+ + +Directory layout adheres to the App filesystem structure + + +4 +v2 + +
x
+ +Source code is also recommended, but not required to adhere to the App filesystem structure for tooling consistency + + +5 +v2 +
x
+ + +Plugins must be packaged as part of a Component, so that Component install & managment tooling can be used + + +6 +v2 +
x
+ + +Plugins must not be installed by calling install-app.sh directly, as Component tooling calls it instead. More information is available in "Packaging" conformance section + + + + +### Packaging Format and Manifest + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ItemVersionRequiredBest PracticeConformantCriteria
7v2
x
If the extension is standalone (not bundled with other products), the extension convenience build (non-SMPE) MUST package itself into zip, tar, or pax format.
8v2
x
The extension MUST package a manifest.yaml (or manifest.yml, or manifest.json) into final package.
9v2
x
If the extension is standalone (not bundled with other products), the manifest file MUST be placed in the root directory after it’s extracted or installed.
10v2
x
The extension manifest MUST contain "name" definition.
11v2
x
If the extension manifest contains definition of "appfwPlugins", it MUST also define "id" definition.
12v2
x
It's recommended to define "version" in the extension manifest.
13v2
x
It's recommended to define "license" in the extension manifest .
14v2
x
It's recommended to define "title" and "description" in the extension manifest.
15v2
x
It's recommended to define "build" in the extension manifest to describe the source code information from version control systems.
16v2
x
The extension is suggested to define “commands.install”, “commands.configure”, and/or “commands.start” to instruct Zowe how to install, configure or start in Zowe context.
17v2
x
If the extension contains services that will be registered under API-ML, those services MUST be defined as entries of "apimlServices" in the extension manifest.
18v2
x
If the extension contains Zowe App Framework plugin(s), these plugins MUST to defined as entries of "appfwPlugins" in the extension manifest.
19v2
x
If the extension contains Zowe ZIS plugin(s), these plugins MUST to defined as entries of "zisPlugins" in the extension manifest.
+ +### Web UIs All + + + + + + + + + + + + + + + + + + + + +
ItemVersionRequiredBest PracticeConformantCriteria
20v2
x
All Apps must contain an icon image file located somewhere within the /web folder of the plugin and the plugin definition must specify the location relative to the /web folder as the webContent.launchDefinition.imageSrc property
+ +### Web UI IFrame + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ItemVersionRequiredBest PracticeConformantCriteria
21v2
x
IFrame Apps (apps with framework type "iframe") which embed a top-level iframe within (example) must use the ID "zluxIframe" for that element. This is required for the app to be a recipient of app to app communication.
22v2
x
Zowe resources must be accessed via the iframe-adapter located within zlux-app-manager/bootstrap/web. Use of window.parent or window.top to access the ZoweZLUX object is non-permissible.
+ +### Web UI Non-IFrame + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ItemVersionRequiredBest PracticeConformantCriteria
23v2
x
DOM elements originating from your App should always be a child of the Zowe viewport DOM element, "com-rs-mvd-viewport"
24v2
x
Network requests to the Zowe App Server must never be done without the use of the URI Broker
25v2
x
Access to resources outside the App Server should also be made through the URI Broker whenever possible
26v2
x
Apps must not pollute the global namespace with regards to Javascript, HTML, and CSS however it is permitted to have 1 Javascript global who's name is equal to the plugin identifier
27v2
x
When using a library present in the Zowe App Framework core, you must depend on the same version, as seen in here
28v2
x
Web apps should extend the framework's default build scripts for webpack and typescript.
### UI Design - - - - - - - - - - - - - - - - - - -
Item Ver Required Best Practice Conformant Criteria
15v1xApps should follow the UI Design guidelines at https://github.com/zowe/zlc/blob/master/process/UI_GUIDELINES.md
- - ### Localization and Internationalization l10n and l18n - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Item Ver Required Best Practice Conformant Criteria
16v1xIf your software supports multiple languages, the active language to be used for string selection must be retrieved using ZoweZLUX.globalization.getLanguage(), which determines language by multiple factors
17v1xNo strings visible in a UI should be hard-coded. Resource strings must be used in accordance with one of the existing internationalization support mechanisms.
+ + + + + + + + + + + + + + + + + + + +
ItemVersionRequiredBest PracticeConformantCriteria
29v2
x
Apps should follow the UI Design guidelines at this page
+ +### Localization and Internationalization (l10n and l18n) + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ItemVersionRequiredBest PracticeConformantCriteria
30v2
x
If supporting more than one language, the active language to be used for string selection must be retrieved using the get methods in ZoweZLUX.globalization, which determine language by multiple factors
31v2
x
If supporting more than one language, no strings visible in a UI should be hard-coded, rather resource strings must be used in accordance with one of the existing internationalization support mechanisms
### App Server - - - - - - - - - - - - - - - - - - +
Item Ver Required Best Practice Conformant Criteria
18v1xData services should be written such that all synchronous and asynchronous errors are caught. Utilize try-catch and check the existence of error objects from asynchronous calls. Uncaught exceptions affect server responsiveness and disrupts clients.
+ + + + + + + + + + + + + + + + + +
ItemVersionRequiredBest PracticeConformantCriteria
32v2
x
Data services should be written such that all synchronous and asynchronous errors are caught. Utilize try-catch and check the existence of error objects from asynchronous calls. Uncaught exceptions effect server responsiveness and disrupt clients
### Documentation - - - - - - - - - - - - - - - - - - - - - - - - - - +
Item Ver Required Best Practice Conformant Criteria
19v1xEvery HTTP API must be documented in swagger 2.0. The swagger document must be stored in doc/swagger.
20v1xIn addition, we recommend documentation about the format of any Websocket APIs, to be included in the doc
+ + + + + + + + + + + + + + + + + + + + + + + + + +
ItemVersionRequiredBest PracticeConformantCriteria
33v2
x
Every HTTP API which is intended for 3rd party use must be documented in swagger 2.0. The swagger document must be stored in doc/swagger
34v2
x
In addition, it is recommended to have documentation about the format of any Websocket APIs, to be placed within doc
- ### Logging - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +
Item Ver Required Best Practice Conformant Criteria
21v1xAn Apps non-Iframe web components, or App Framework dataservices (eg Javascript and Typescript) must log only through the "zlux" logger
22v1xZSS services log only through the Zowe ZSS Logger
23v1xPasswords must never be logged
24v1xError reporting should follow the standard tooling
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ItemVersionRequiredBest PracticeConformantCriteria
35v2
x
An Apps non-IFrame web components, or App Framework dataservices (eg Javascript and Typescript) must log only through the "zlux" logger
36v2
x
ZSS services log only through the Zowe ZSS Logger
37v2
x
Passwords must never be logged
38v2
x
Error reporting should follow the standard tooling
### Encoding - - - - - - - - - - - - - - - - - - - - - - - - - - -
Item Ver Required Best Practice Conformant Criteria
25v1xApplication Framework plugins serving web content through App Server or doing file I/O through an App Server dataservice should tag these files on z/OS according to their content type
26v1xTesting Apps via the install-app script is advisable to enable end users to utilize Zowe plugin management tooling
- - ### Storage - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Item Ver Required Best Practice Conformant Criteria
27v1xUser preferences, if applicable to a plug-in, must be stored through the configuration data service, unless the software needs pre-existing storage structures such as DB2
28v1xFor other plugin storage needs, storing data outside of the configuration dataservice is permitted only within $INSTANCE_DIR/workspace/app-server or $INSTANCE_DIR/workspace/app-server/pluginStatic with a top-level folder equal to their plugin ID. Plugins must not store information anywhere else in any Zowe directories such as $INSTANCE_DIR or $ROOT_DIR in order to prevent conflict with future Zowe versions and other plugins
29v1xIt is advisable for the storage of user preferences to use environment variables for locating directories. The use of the instance directory environment variable is not required, however we recommend the use of this variable to subvert the use of hard-coded paths
- - ### Directory and File Ownership Permissions - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Item Ver Required Best Practice Conformant Criteria
30v1xA conformant application must not modify the contents of the Zowe root directory $ROOT_DIR and must not change any directory or file permissions or ownership
31v1xA conformant application must not modify the permissions or ownership of a Zowe instance directory workspace
- - ### Lifecycling as a Zowe address space - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Item Ver Required Best Practice Conformant Criteria
32Applicable if LIFECYCLEDIf the app framework plugin requires services that do not originate from Zowe, but require the same lifecycle as Zowe, satisfy the following criteria to lifecycle them with Zowe:
v1xThe service should provide a fully qualified path in the instance.env file for the Zowe workspace which points to the location of a directory containing a start.sh script
v1xContain a validate.sh script
v1xContain a configure.sh script
33v1xIf the service introduces new variables to the instance.env file, these variablesshould be prefixed by the provider ID to avoid collisions
- - - ### Support - - - - - - - - - - - - - - - - - - +
Item Ver Required Best Practice Conformant Criteria
34v1xThe Submitter describes how support is provided. Support details must be clearly documented
+ + + + + + + + + + + + + + + + + +
ItemVersionRequiredBest PracticeConformantCriteria
39v2
x
If you want your Apps to work with z/OS Node.js version 12 or greater, all application files must be tagged according to their content type
-# +### Storage + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ItemVersionRequiredBest PracticeConformantCriteria
40v2
x
For persistent storage, user preferences (if applicable to a plugin) must be stored through the configuration data service
41v2
x
Regarding persistent storage for other plugin storage needs, storing data outside of the configuration dataservice is permitted only within /workspaceDirectory/app-server or /workspaceDirectory/app-server/pluginStatic with a top-level folder equal to their plugin ID. Plugins must not store information anywhere else in any Zowe directories such as /workspaceDirectory or $ROOT_DIR in order to prevent conflict with future Zowe versions and other plugins
42v2
x
It is advisable for the storage of user preferences to use environment variables for locating directories. Use of the workspace directory environment variable is not required, but should be considered to subvert the use of hard-coded paths
43v2
x
To be HA compatible, you should use some or all of the storage APIs of Zowe which include but are not limited to the caching service of the API ML, storage API of the App server, and storage API of ZSS
-## Zowe Explorer for Visual Studio Code - Zowe v1 +### Directory and File Ownership Permissions -Throughout the this Zowe Explorer for Visual Studio Code section you will find the following terminology being used: + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ItemVersionRequiredBest PracticeConformantCriteria
44v2
x
A conformant application must not modify the contents of the Zowe runtime USS directory and it must not change any directory or file permissions or ownership
45v2
x
A conformant application must not modify the permissions or ownership of a Zowe workspace directory
-- _Extender_: The organization or developer producing an extension for Zowe Explorer for Visual Studio Code. -- _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. -- _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. +### Lifecycling as a Zowe address space -### General Extension + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ItemVersionRequiredBest PracticeConformantCriteria
If the service should be lifecycled by Zowe, then:
46v2
x
it should provide and specify in its Component manifest a start.sh script
47v2
x
a validate.sh script
48v2
x
a configure.sh script
49v2
x
If the service introduces new environment variables to the zowe.yaml file, these should be prefixed by the provider ID to avoid collisions
-General conformance criteria for all extensions that add new capabilities to Zowe Explorer for Visual Studio Code. +### Support - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + +
Item Ver Required Best Practice Conformant Criteria
1v1xNaming: 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.
2v1xNo Zowe CLI plugin installation requirement: If the extender 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.
3v1xPublication 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.
4v1xSupport: 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.
5v1xUser settings consistency: Extender provides a consistent user settings experience. For Visual Studio Code extensions, extender follows the recommended naming convention for configuration settings as described in Visual Studio Code's configuration contribution documentation, and avoids starting setting names with the prefix `zowe.`, which is reserved for Zowe Explorer for Visual Studio Code.
6v1xError 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.
7v1xZowe 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.
8v1xSharing 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.
9Mark (a) or (b) or (c)Extension uses the extensibility APIs provided by Zowe Explorer for Visual Studio Code. Supported methods include:

(Please select all that apply _a_, _b_, or _c_)

a. Extension Accessing Profiles
b. Data Provider Extension
c. Extension Adding Menus
ItemVersionRequiredBest PracticeConformantCriteria
50v2
x
Submitter describes how Support is provided and Support details are clearly documented
-### Extension Accessing Profiles +## Zowe Explorer for Visual Studio Code -Criteria for Visual Studio Code extensions that want to access the same Zowe CLI profiles that Zowe Explorer for Visual Studio Code uses. +### General Extension - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Item Ver Required Best Practice Conformant Criteria
10v1xVisual 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.
11v1xZowe Extender 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.
12v1xAdded 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.
ItemVersionRequiredBest PracticeConformantCriteria
1v2
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.
2v2
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.
3v2
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.
4v2
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.
5v2
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
6v2
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 .
7v2
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.
8v2
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.
9v2
x
Sharing Zowe profiles: If the Extension accesses the same mainframe service as a Zowe CLI plug-in, the connection information should be shared via Zowe Team Config (zowe.config.json)
10Mark (a) (b) (c) (d)Extension enhances the mainframe user experience [a]
+OR
+Extension utilizes the extensibility APIs provided by Zowe Explorer + [b, c, d]
x
a. Extension interacts with mainframe content retrieved via Data Set, USS or Jobs view
x
b. Extension Accessing Profiles
x
c. Data Provider Extension
x
d. Extension Adding Menus
-### 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] Extension Interacts with mainframe assets delivered by Zowe Explorer +

Criteria for VS Code extensions that access or interact with Zowe Explorer assets (i.e. data sets, USS, jobs)

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + +
Item Ver Required Best Practice Conformant Criteria
13v1xNew 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
14v1xMatching 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.
15v1xData 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.
16v1xAPI 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.
17v1xBase Profile and Tokens: Extension supports base profiles and tokens.
18v1xTeam Configuration File: Extension supports the Zowe CLI 7 team configuration file format as an alternative to the Zowe CLI 6 profiles file format.
19v1xSecure 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.
ItemVersionRequiredBest PracticeConformantCriteria
11v2
x
README.MD File: Extension documents the following in its associated README.MD file (displayed at the appropriate Marketplace)
+(1) recommends use of Zowe Explorer
+(2) describes the relationship to Zowe Explorer
+(3) describes the scenario that leverages Zowe Explorer
+(4) uses the "zowe" TAG
+Sample verbiage: Recommended for use with Zowe Explorer. [Extension-name] extension uses the Zowe Explorer to access mainframe files and then ....[complete-your-use-case-here] +
-### Extension Adding Menus +### [b] Extension Accessing Profiles +

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

-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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ItemVersionRequiredBest PracticeConformantCriteria
12v2
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. +
13v2
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.
14v2
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.
15v2
x
Base Profile and Tokens: Extension supports base profiles and tokens
16v2
x
Team Configuration File: Extension supports the Zowe CLI team configuration file format.
17v2
x
v1 Profile Support: Extension has a backwards compatibility and it is able to support v1 type of profiles.
+### [c] Extension Serves as a Data Provider + +

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
20v1xCommand 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.
21v1xCommand 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".
22v1xContext 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.
23v1xMenu 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.
24v1xContext 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.
ItemVersionRequiredBest PracticeConformantCriteria
18v2
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. +
19v2
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
20v2
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.
21v2
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.
22v2
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.
+### [d] 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.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ItemVersionRequiredBest PracticeConformantCriteria
23v2
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. +
24v2
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.
25v2
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.
26v2
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".
27v2
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.
28v2
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.
29v2
x
Existing Menu Items: Extension does not overwrite any existing Zowe Explorer command and context menu entries
30v2
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.
\ No newline at end of file