Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

ZE and ZE API readme updates #3365

Open
wants to merge 10 commits into
base: main
Choose a base branch
from
+7 −9
Open

ZE and ZE API readme updates #3365

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
2504185
Update ZE API README.md
adam-wolfe Dec 18, 2024
1231241
Remove "currently"
adam-wolfe Dec 18, 2024
379aa2a
Avoid overuse of "several"
adam-wolfe Dec 18, 2024
0d1e339
Remove V3 pre-release note and add tip for insert key
adam-wolfe Dec 18, 2024
a33977a
Fixed typo
adam-wolfe Dec 18, 2024
09bb653
modes
adam-wolfe Dec 18, 2024
1374f9e
adjust links for npmjs
adam-wolfe Dec 18, 2024
b90e67b
Full URL to FTP extension
adam-wolfe Dec 19, 2024
a4af768
Some addl wording changes
adam-wolfe Dec 19, 2024
9d2fe2c
Replace all relative paths with full URLs
adam-wolfe Dec 20, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 5 additions & 7 deletions packages/zowe-explorer-api/README.md
View file
Open in desktop
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good timing! I noticed this when reading this page earlier today, that this line the link to packages/zowe-explorer-ftp-extension/src/ZoweExplorerFtpApi.ts now goes to a 404.

Original file line number Diff line number Diff line change
Expand Up @@ -5,11 +5,9 @@

Extensibility API for Zowe Explorer is a collection of APIs that can be used to extend the [Zowe Explorer](https://github.com/zowe/zowe-explorer-vscode) VS Code extension with alternative z/OS interaction protocols and new capabilities.

The current state of this API is experimental, but the goal is provide a stabilized version that can be used for Zowe Conformance certifications in the future. See this issue for more details: <https://github.com/zowe/zowe-explorer-vscode/issues/837>.
The API is used by extenders of the Zowe Explorer VS Code extension, including the [IBM z/OS FTP for Zowe Explorer](https://github.com/zowe/zowe-explorer-vscode/tree/main/packages/zowe-explorer-ftp-extension) and [IBM CICS for Zowe Explorer](https://github.com/zowe/cics-for-zowe-client/tree/main/packages/vsce) VS Code extensions, as well as several commercial extensions.

However, the current API is being used by other extensions already, such as for Zowe Explorer with the [Zowe Explorer FTP Extension](../zowe-explorer-ftp-extension) that you can find in this same Git repository, as well as for commercial extensions maintained by Zowe's contributors and available on their company websites.

Currently, the API is organized into two modules, which both are rolled up into the top-level `index.ts` file for convenient access.
The API is organized into modules that are exposed through the top-level `index.ts` file for convenient access.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Comment here isn't for the sentence itself but about the changed access to modules, removing the access directly to the /profiles module was a huge breaking change I saw for extenders that use our profile ZE APIs in a CLI plugin. Bringing attention here for discussion.


- `/profiles`: Provides access to common Zowe CLI profile management APIs, as well as abstractions for providing alternative z/OS interactions that use protocols other than z/OSMF, based on alternative Zowe CLI profile types.
- `/tree`: Provides abstractions for accessing and extending the Zowe Explorer VS Code tree views.
Expand All @@ -23,9 +21,9 @@ The `/profiles` module has no dependency to VS Code and could be used in Zowe CL
import { ZoweExplorerApi } from "@zowe/zowe-explorer-api/lib/profiles";
```

The main API provided by the `/profiles` module is called `ZoweExplorerApi`. It defines a namespace for interfaces for implementing access to z/OS MVS, USS, and JES. You can see that the Zowe Explorer FTP Extension provides such an alternative implementation for USS using the FTP protocol in [packages/zowe-explorer-ftp-extension/src/ZoweExplorerFtpApi.ts](../zowe-explorer-ftp-extension/src/ZoweExplorerFtpApi.ts). The `/profiles` module itself contains Zowe Explorer's default implementation using z/OSMF in [packages/zowe-explorer-api/src/profiles/ZoweExplorerZosmfApi.ts](./src/profiles/ZoweExplorerZosmfApi.ts)
The main API provided by the `/profiles` module is called `ZoweExplorerApi`. It defines a namespace for interfaces for implementing access to z/OS MVS, USS, and JES. You can see that the Zowe Explorer FTP Extension provides such an alternative implementation for USS using the FTP protocol in [packages/zowe-explorer-ftp-extension/src/ZoweExplorerFtpMvsApi.ts](https://github.com/zowe/zowe-explorer-vscode/tree/main/packages/zowe-explorer-ftp-extension/src/ZoweExplorerFtpMvsApi.ts). The `/profiles` module itself contains Zowe Explorer's default implementation using z/OSMF in [packages/zowe-explorer-api/src/profiles/ZoweExplorerZosmfApi.ts](https://github.com/zowe/zowe-explorer-vscode/tree/main/packages/zowe-explorer-api/src/profiles/ZoweExplorerZosmfApi.ts)

Zowe Explorer itself exports a `IApiRegisterClient` object that can be used for an alternative implementation to be registered with Zowe Explorer. You can find an example for doing this in [packages/zowe-explorer-ftp-extension/src/extension.ts](../zowe-explorer-ftp-extension/src/extension.ts). To be able to do this, your VS Code extension must define a dependency to Zowe Explorer to ensure that VS Code extension activation is performed in the correct order. Therefore, your VS Code extension's `package.json` must contain
Zowe Explorer itself exports a `IApiRegisterClient` object that can be used for an alternative implementation to be registered with Zowe Explorer. You can find an example for doing this in [packages/zowe-explorer-ftp-extension/src/extension.ts](https://github.com/zowe/zowe-explorer-vscode/tree/main/packages/zowe-explorer-ftp-extension/src/extension.ts). To be able to do this, your VS Code extension must define a dependency to Zowe Explorer to ensure that VS Code extension activation is performed in the correct order. Therefore, your VS Code extension's `package.json` must contain

```json
"extensionDependencies": [
Expand Down Expand Up @@ -53,4 +51,4 @@ See this [special extension document](https://github.com/zowe/zowe-explorer-vsco

Extensibility API for Zowe Explorer is part of the [Zowe Explorer monorepo on Github](https://github.com/zowe/zowe-explorer-vscode). You find the sources there in the `/packages/zowe-explorer-api` sub-folder.

To file issues, use the [Zowe Explorer issue list](https://github.com/zowe/zowe-explorer-vscode/issues) after reviewing the [API Roadmap item](https://github.com/zowe/zowe-explorer-vscode/issues/837).
To submit a bug report or enhancement request, open an issue in the [Zowe Explorer repository](https://github.com/zowe/zowe-explorer-vscode/issues).
4 changes: 2 additions & 2 deletions packages/zowe-explorer/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,6 @@
[![codecov](https://codecov.io/gh/zowe/zowe-explorer-vscode/branch/main/graph/badge.svg)](https://codecov.io/gh/zowe/zowe-explorer-vscode)
[![slack](https://img.shields.io/badge/chat-on%20Slack-blue)](https://slack.openmainframeproject.org/)

> ## v3 Pre-release is now available in our [Github Releases](https://github.com/zowe/zowe-explorer-vscode/releases) with the removal of v1 profile support. Keep an eye on [changes affecting users and extenders](https://github.com/zowe/zowe-explorer-vscode/wiki/v3-Changes-for-Users-and-Extenders) for the full list of changes

## Introduction

[Zowe Explorer](https://github.com/zowe/community#zowe-explorer) is a sub-project of Zowe, focusing on modernizing the mainframe experience. [Zowe](https://www.zowe.org/) is a project hosted by the [Open Mainframe Project](https://www.openmainframeproject.org/), a [Linux Foundation](https://www.linuxfoundation.org/) project.
Expand Down Expand Up @@ -156,6 +154,8 @@ Your token has been successfully invalidated.

- **Open recent members**: Zowe Explorer lets you open a list of members you worked on earlier. You can access the list by pressing `Ctrl`+`Alt`+`R` (Windows) or `Command`+`Option`+`R` (Mac).

- **Insert/overtype modes**: Visual Studio Code v1.96 introduced the ability to toggle between insert and overtype modes by pressing the `Insert` key. Overtype mode can be helpful when working with data sets and members with fixed record lengths.

For the comprehensive Zowe Explorer documentation that also includes information about USS and Jobs interactions, see [the Zowe Explorer documentation](https://docs.zowe.org/stable/user-guide/ze-install.html) in Zowe Docs.

## Keyboard Shortcuts
Expand Down
Loading