From fc4f8702e415153cf41f31455af7e3d75d4f5198 Mon Sep 17 00:00:00 2001 From: Amber Torrise Date: Thu, 14 Mar 2024 11:23:22 -0400 Subject: [PATCH] updating spellings and documentation Signed-off-by: Amber Torrise --- CHANGELOG.md | 6 ++- README.md | 38 ++++++++++--------- __tests__/pluginDef.test.ts | 2 +- docs/tutorials/Setup.md | 2 +- docs/tutorials/files-util/FilesUtilPlugin.md | 6 +-- .../ListDirectoryContentsPlugin.md | 2 +- .../ListTypicodeTodoPlugin.md | 4 +- .../profile-example/ProfilePlugin.md | 2 +- package.json | 2 +- src/LifeCycleForSample.ts | 38 +++++++++---------- 10 files changed, 55 insertions(+), 47 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index abe81dc..d12aa22 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,7 +4,11 @@ All notable changes to the Sample Plug-in for Zowe CLI will be documented in thi ## Recent Changes -- Enhancement: Added plugin lifecycle example. +- Enhancement: + - Removed detailed Jenkins information and switched to GHA + - Updated imports and resolved errors when making plug-in v3 compatible + +- Enhancement: Added plug-in lifecycle example. - Enhancement: Removed deprecated pluginHealthCheck. - BugFix: Updated dependencies for technical currency. diff --git a/README.md b/README.md index bbb4efa..b29ce42 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Zowe CLI Sample Plug-in -This repository contains a sample Zowe CLI plug-in that adheres to the contribution guidelines for the project. Use this project and the associated tutorials as a starting point for creating Zowe CLI plug-ins. +This repository contains a sample Zowe CLI Plug-in that adheres to the contribution guidelines for the project. Use this project and the associated tutorials as a starting point for creating Zowe CLI Plug-ins. - [Zowe CLI Sample Plug-in](#zowe-cli-sample-plug-in) - [Plug-in Sample Overview](#plug-in-sample-overview) @@ -18,18 +18,18 @@ This repository contains a sample Zowe CLI plug-in that adheres to the contribut ## Plug-in Sample Overview -This sample plug-in includes: -- Source code for a command that lists contents in a remote directory. +This plug-in sample includes: +- Source code for extending the Zowe CLI with a command that lists the contents of a remote directory. - Tutorials on: - - Building the plug-in and using its `zowe zowe-cli-sample list directory-contents` command. - - Enhancing the code with a third-party package by creating a command for file-diff highlighting. - - Augmenting the code to connect with Typicode's external API, showcasing the retrieval and display simulated backend data. -- Examples of lifecycle hooks and GitHub workflows for CI/CD. + - [Building the plug-in](docs/tutorials/list-directory-contents/ListDirectoryContentsPlugin.md) to use its `zowe zowe-cli-sample list directory-contents` command. + - [Enhancing the sample](docs/tutorials/files-util/FilesUtilPlugin.md) with a third-party package and creating a new command for file-diff highlighting. + - [Augmenting the code](docs/tutorials/list-typicode-todo/ListTypicodeTodoPlugin.md) to connect with Typicode's external API, a simulator of backend data, to walk through the cli's interaction with RESTful services. +- Examples of lifecycle hooks and GitHub Actions workflows for CICD. - Templates for model testing suites. ## Why Create a Zowe CLI Plug-in? -You might want to create a Zowe CLI plug-in to accomplish the following: +You might want to create a Zowe CLI Plug-in to accomplish the following: * Provide new script-able functionality for yourself, your organization, or to a broader community. * Make use of Zowe CLI infrastructure (profiles and programmatic APIs). @@ -42,27 +42,28 @@ We provide the following tutorials, guidelines, and documentation to assist you ### Tutorials -To learn about how to work with this sample plug-in, build new commands, or build a new Zowe CLI plug-in, see [Extend Zowe CLI](https://docs.zowe.org/stable/extend/extend-zowe-overview/#extend-zowe-cli). +This sample plug-in comes with [tutorial information](docs/tutorials), but more in-depth documentation can be found online. See [Extend Zowe CLI](https://docs.zowe.org/stable/extend/extend-zowe-overview/#extend-zowe-cli) to learn more about how to work with this sample plug-in, build new commands, or build a new Zowe CLI Plug-in. + **Note:** For an advanced example on how to create a plug-in that serves as a Credential Manager, see [Zowe CLI secrets for Kubernetes](https://github.com/zowe/zowe-cli-secrets-for-kubernetes/) ### Contribution Guidelines -The Zowe CLI [contribution guidelines](CONTRIBUTING.md) contain standards and conventions for developing Zowe CLI plug-ins. +The Zowe CLI [contribution guidelines](CONTRIBUTING.md) contain standards and conventions for developing Zowe CLI Plug-ins. The guidelines contain critical information about working with the code, running/writing/maintaining automated tests, developing consistent syntax in your plug-in, and ensuring that your plug-in integrates with Zowe CLI properly. ### Imperative CLI Framework Documentation -[Imperative CLI Framework](https://github.com/zowe/imperative/wiki) documentation is a key source of information to learn about the features of Imperative CLI Framework (the code framework that you use to build plug-ins for Zowe CLI). Refer to these documents during development. +The Zowe CLI once required the [Imperative CLI Framework](https://github.com/zowe/imperative/wiki) as a dependency. As of V3 of the CLI, Imperative has become a built-in package of the CLI. Many of the CLI's capabilities stem from Imperative's provided structural foundation. The following archived information about the Imperative CLI Framework is still relevant and will provide you with a good understanding about the underpinnings and features of the Zowe CLI. Refer to these documents during the development of your plug-in. ### CICD Guidelines -Reference our [included Github workflows](.github/workflows/) for guidance about setting up and maintaining automated testing/deployment for your plug-in with Github Actions. +Reference our [included GitHub Actions workflows](.github/workflows/) for guidance about setting up and maintaining automated testing and deployment for your plug-in with GitHub Actions. ## Prerequisites -Before you work with the Zowe CLI sample plug-in, [install Zowe CLI globally.](https://docs.zowe.org/active-development/user-guide/cli-installcli.html) +Before you work with the Zowe CLI sample plug-in, [install Zowe CLI](https://docs.zowe.org/stable/user-guide/cli-installcli) and its dependencies globally. ## Create a Local Development Space @@ -85,11 +86,14 @@ See [setup](docs/tutorials/Setup.md). **Note:** If you don't have access to a z/OSMF instance at your site, run `npm run server:start` to launch a mock server at http://localhost:3000. +#### If you have a z/OSMF system you are connecting to: 1. `cd __tests__/__resources__/properties` -2. Copy `example_properties.yaml` to `custom_properties.yaml`. -3. Edit the properties within `custom_properties.yaml` to contain valid system information for your site. -4. `cd` to your `zowe-cli-sample-plugin` folder -5. `npm run test` +2. a) Copy `example_properties.yaml` to `custom_properties.yaml`.\ +b) Edit the properties within `custom_properties.yaml` to contain valid system information for your site. + +#### Run your tests: +3. `cd` to your `zowe-cli-sample-plugin` folder +4. `npm run test` ### Install the zowe-cli-sample-plugin to Zowe CLI diff --git a/__tests__/pluginDef.test.ts b/__tests__/pluginDef.test.ts index b353b6f..ff59a2d 100644 --- a/__tests__/pluginDef.test.ts +++ b/__tests__/pluginDef.test.ts @@ -8,7 +8,7 @@ * Copyright Contributors to the Zowe Project. */ -describe("plugin definition", () => { +describe("plug-in definition", () => { // Will fail if imperative config object is changed. This is a sanity/protection check to ensure that any // changes to the configuration document are intended. diff --git a/docs/tutorials/Setup.md b/docs/tutorials/Setup.md index 05854cf..c7a7127 100644 --- a/docs/tutorials/Setup.md +++ b/docs/tutorials/Setup.md @@ -1,6 +1,6 @@ # Setting up your development environment -Before you follow the development tutorials for installing, extending, and creating a Zowe CLI plug-in, follow these steps to set up your environment. +Before you follow the development tutorials for installing, extending, and creating a Zowe CLI Plug-in, follow these steps to set up your environment. ## Prequisites diff --git a/docs/tutorials/files-util/FilesUtilPlugin.md b/docs/tutorials/files-util/FilesUtilPlugin.md index 5603299..563eeb9 100644 --- a/docs/tutorials/files-util/FilesUtilPlugin.md +++ b/docs/tutorials/files-util/FilesUtilPlugin.md @@ -2,7 +2,7 @@ Before you begin this tutorial, make sure that you completed the [Extending an existing plug-in]() tutorial. ## Overview -This tutorial demonstrates creating a brand new Zowe CLI plug-in that uses Zowe CLI Node.js programmatic APIs. +This tutorial demonstrates creating a brand new Zowe CLI Plug-in that uses Zowe CLI Node.js programmatic APIs. At the end of this tutorial, you will have created a data set diff utility plug-in for Zowe CLI, from which you can pipe your plugin's output to another utility for a side-by-side diff of data set member contents. @@ -37,7 +37,7 @@ import { IImperativeConfig } from "@zowe/imperative"; const config: IImperativeConfig = { commandModuleGlobs: ["**/cli/*/*.definition!(.d).*s"], - rootCommandDescription: "Files utilty plugin for Zowe CLI", + rootCommandDescription: "Files utilty plug-in for Zowe CLI", envVariablePrefix: "FILES_UTIL_PLUGIN", defaultHome: "~/.files_util_plugin", productDisplayName: "Files Util Plugin", @@ -189,7 +189,7 @@ export default class DataSetsDiffHandler implements ICommandHandler { ``` ## Trying your command -Be sure to build your plugin via `npm run build`. +Be sure to build your plug-in via `npm run build`. Install your plug-in into Zowe CLI via `'zowe plugins install .`' diff --git a/docs/tutorials/list-directory-contents/ListDirectoryContentsPlugin.md b/docs/tutorials/list-directory-contents/ListDirectoryContentsPlugin.md index 92290aa..6e0b94f 100644 --- a/docs/tutorials/list-directory-contents/ListDirectoryContentsPlugin.md +++ b/docs/tutorials/list-directory-contents/ListDirectoryContentsPlugin.md @@ -4,7 +4,7 @@ Before you begin, [setup](../Setup.md) your environment to install a plug-in. ## Overview -This tutorial covers installing and running this bundled Zowe CLI plugin as-is (without modification), which will display your current directory contents. +This tutorial covers installing and running this bundled Zowe CLI Plug-in as-is (without modification), which will display your current directory contents. The plug-in adds a command to the CLI that lists the contents of a directory on your PC. diff --git a/docs/tutorials/list-typicode-todo/ListTypicodeTodoPlugin.md b/docs/tutorials/list-typicode-todo/ListTypicodeTodoPlugin.md index 2243465..f5ecc8c 100644 --- a/docs/tutorials/list-typicode-todo/ListTypicodeTodoPlugin.md +++ b/docs/tutorials/list-typicode-todo/ListTypicodeTodoPlugin.md @@ -7,7 +7,7 @@ This tutorial demonstrates how to extend the plug-in that is bundled with this s 2. Creating a new command definition 3. Creating a new handler -We'll do this by using `@zowe/imperative` infrastructure to surface REST API data on our Zowe CLI plug-in. +We'll do this by using `@zowe/imperative` infrastructure to surface REST API data on our Zowe CLI Plug-in. Specifically, we're going to show data from [this URI](https://jsonplaceholder.typicode.com/todos) by [Typicode](https://jsonplaceholder.typicode.com/). Typicode serves sample REST JSON data for testing purposes. @@ -161,7 +161,7 @@ is presented. You can also see how to use your optional `--id` flag: ![output](images/completedSample.png) # Summary -You extended an existing Zowe CLI plug-in by introducing a Node.js programmatic API, and you created a command definition with a handler. +You extended an existing Zowe CLI Plug-in by introducing a Node.js programmatic API, and you created a command definition with a handler. For an official plugin, you would also add [JSDoc](http://usejsdoc.org/) to your code and create tests. Completed source can be found on the `typicode-todos` branch of this repo. diff --git a/docs/tutorials/profile-example/ProfilePlugin.md b/docs/tutorials/profile-example/ProfilePlugin.md index e1b941d..7d40bfb 100644 --- a/docs/tutorials/profile-example/ProfilePlugin.md +++ b/docs/tutorials/profile-example/ProfilePlugin.md @@ -1,4 +1,4 @@ -# Implementing profiles in a Zowe CLI plug-in +# Implementing profiles in a Zowe CLI Plug-in You can use this profile template to create a profile for your product. The profile definition is placed in the 'pluginDef.ts' file. diff --git a/package.json b/package.json index 39fa2e3..b6ae3ae 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "@zowe/sample-plugin-for-zowe-cli", "version": "3.0.0", - "description": "A sample plugin for Zowe CLI :)", + "description": "A sample plug-in for Zowe CLI :)", "homepage": "https://github.com/zowe/zowe-cli-sample-plugin#readme", "bugs": { "url": "https://github.com/zowe/zowe-cli-sample-plugin/issues" diff --git a/src/LifeCycleForSample.ts b/src/LifeCycleForSample.ts index 861aa6a..82f052d 100644 --- a/src/LifeCycleForSample.ts +++ b/src/LifeCycleForSample.ts @@ -11,20 +11,20 @@ import {AbstractPluginLifeCycle, ImperativeError, Logger} from "@zowe/imperative"; /** - * This class performs lifecycle functions for your plugin. You are free to - * change the name of this class to reflect your plugin and its actions. + * This class performs lifecycle functions for your plug-in. You are free to + * change the name of this class to reflect your plug-in and its actions. * * You only have to supply such a class if you specify the 'pluginLifeCycle' - * property in your IImperativeConfig definition for your plugin. In this sample, + * property in your IImperativeConfig definition for your plug-in. In this sample, * that definition is supplied in src/pluginDef.ts. */ export class LifeCycleForSample extends AbstractPluginLifeCycle { /** - * This function will be called after a plugin is installed. - * A plugin can use this opportunity to perform a sanity test or to - * perform some additional setup which is specific to your plugin. + * This function will be called after a plug-in is installed. + * A plug-in can use this opportunity to perform a sanity test or to + * perform some additional setup which is specific to your plug-in. * - * If your plugin's postInstall function performs an asynchronous operation, + * If your plug-in's postInstall function performs an asynchronous operation, * its postInstall function should return a promise, allowing the CLI * to await the postInstall function. Such a signature would be like this: * @@ -39,7 +39,7 @@ export class LifeCycleForSample extends AbstractPluginLifeCycle { */ public postInstall(): void { /* It is up to you to decide what actions are meaningful for you - * to perform immediately after your plugin is installed. + * to perform immediately after your plug-in is installed. * * When all goes well, you probably should display nothing to the user. */ @@ -58,7 +58,7 @@ export class LifeCycleForSample extends AbstractPluginLifeCycle { * default log level is WARN. So by default, only messages displayed at * the WARN, ERROR, and FATAL levels will be displayed (or logged). */ - const warnMsg = "Something weird happened in the sample plugin's " + + const warnMsg = "Something weird happened in the sample plug-in's " + "postInstall function. However, things should still work ok."; Logger.getConsoleLogger().warn(warnMsg); Logger.getImperativeLogger().warn(warnMsg); @@ -68,30 +68,30 @@ export class LifeCycleForSample extends AbstractPluginLifeCycle { * an imperative error. The "zowe plugins install" command will catch * that error, display it, and add some additional information. * - * Your plugin has already been installed. However, when you throw an + * Your plug-in has already been installed. However, when you throw an * error during your postInstall function, the 'zowe plugins install' * command will exit with a non-zero exit code. */ const someBigProblemOccurred = false; if ( someBigProblemOccurred ) { throw new ImperativeError({ - msg: "Something awful happened in the sample plugin's " + - "postInstall function. Thus, the plugin could not be properly setup." + msg: "Something awful happened in the sample plug-in's " + + "postInstall function. Thus, the plug-in could not be properly setup." }); } } /** - * This function will be called before a plugin is uninstalled. + * This function will be called before a plug-in is uninstalled. * This lifecycle hook is intended to replace the capability that used to * be performed by the NPM pre-uninstall action before NPM removed that * capability in NPM version 7. * See https://docs.npmjs.com/cli/v9/using-npm/scripts#a-note-on-a-lack-of-npm-uninstall-scripts * - * A plugin can use this opportunity to revert any specialized setup that was - * established during the lifetime of your plugin. + * A plug-in can use this opportunity to revert any specialized setup that was + * established during the lifetime of your plug-in. * - * If your plugin's preUninstall function performs an asynchronous operation, + * If your plug-in's preUninstall function performs an asynchronous operation, * its preUninstall function should return a promise, allowing the CLI * framework to await the preUninstall function. Such a signature would be like this: * @@ -110,7 +110,7 @@ export class LifeCycleForSample extends AbstractPluginLifeCycle { */ const somethingWeirdOccurred = true; if ( somethingWeirdOccurred ) { - const warnMsg = "Something weird happened in the sample plugin's " + + const warnMsg = "Something weird happened in the sample plug-in's " + "preUninstall function that we thought you should know about."; Logger.getConsoleLogger().warn(warnMsg); Logger.getImperativeLogger().warn(warnMsg); @@ -125,9 +125,9 @@ export class LifeCycleForSample extends AbstractPluginLifeCycle { const someBigProblemOccurred = false; if ( someBigProblemOccurred ) { throw new ImperativeError({ - msg: "Something awful happened during the sample plugin's " + + msg: "Something awful happened during the sample plug-in's " + "preUninstall function. Maybe you have to manually release " + - "some resource that was used by this plugin." + "some resource that was used by this plug-in." }); } }