Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
146 lines (99 loc) · 6.33 KB

CONTRIBUTING.md

File metadata and controls

146 lines (99 loc) · 6.33 KB

Contribution Guidelines

This document is intended to be a living summary of conventions & best practices for development within Zowe® Explorer for IBM® CICS® Transaction Server and Zowe CLI Plug-in for IBM CICS Transaction Server.

Developing this code base

Requirements

  • Install Node 20

Project structure

The repository is organized as a monorepo with multiple packages in the packages directory:

packages/cli

  • Name: @zowe/cics-for-zowe-cli
  • Description: Zowe CLI Plug-in for IBM CICS Transaction Server
  • Purpose: Provides command-line interface for interacting with CICS resources
  • Dependencies: Uses the SDK package for core functionality

packages/sdk

  • Name: @zowe/cics-for-zowe-sdk
  • Description: Zowe SDK for IBM CICS Transaction Server
  • Purpose: Core functionality for programmatic interaction with CICS through CMCI REST API

packages/vsce

  • Name: cics-extension-for-zowe
  • Description: Zowe Explorer for IBM CICS Transaction Server
  • Purpose: VS Code extension that adds IBM CICS support to Zowe Explorer
  • Dependencies: Uses both the SDK package and vsce-api package

packages/vsce-api

  • Name: @zowe/cics-for-zowe-explorer-api
  • Description: Zowe Explorer for IBM CICS Transaction Server API
  • Purpose: API layer for the VS Code extension
  • Dependencies: Uses the SDK package for core functionality

Build Locally

To build the project locally, follow these steps:

  1. Clone the repository:

    git clone https://github.com/zowe/cics-for-zowe-client.git
cd cics-for-zowe-client

  2. Install dependencies:

    npm install

  3. Build all packages:

    npm run build

  4. Run tests:

    npm run test:unit

  5. Run e2e tests (or check results in the CI build if you don't have a suitable Docker environment):

    npm run test:e2e

  6. If any e2e tests fail, see more details by using the playwright show-report tool. If the tests failed in CI, you can download the data and replay what happened. From the e2e-test job in GitHub Actions, find the "Archive E2E screenshots, Wiremock log, and Playwright test report" step. This step's logs contain a link to the artifact download URL. Download and unzip the artifact zip.

    Next run playwright's show-report. This opens a web browser that allows you to navigate through the e2e test results and examine any failures:

    npx playwright show-report <path_to_unzipped_artifact_zip>/packages/vsce/playwright-report/

  7. Create distributable packages (optional):

    npm run package

The built packages will be placed in the dist directory:

  • SDK, CLI package, and vsce-api packages: npm tarballs
  • VSCE package: .vsix file for VS Code extension installation

Testing if you don't have a CICS install

Our tests use wiremock to fake up a CICS region and test against. You can test against these using our set of test:e2e scripts (search in packages/vsce/package.json).

You need a docker setup locally - on the Mac, we use colima.

Start colima if necessary:

colima start

From within packages/vsce... Tear down any existing running e2e tests:

npm run test:e2e:teardown

Run the tests interactively - this will pop up a playwright window where you can play each e2e test:

npm run test:e2e:dev:interactive

You can also open a browser to http://localhost:1234/ - this will let you use VS Code against the wiremock CICSplex. It's a bit limited but is a useful way to test out the e2e test framework yourself.

How to Contribute

We encourage you to contribute!

Check the current open issues to choose where you can contribute. You can look for the help wanted-labeled issues to find issues that require additional input. If you are new to the project, you might want to check the issues with the good first issue label.

Changelog Update Guidelines

The changelog should be updated for any PR that updates code that will be distributed to the end user. Changes to certain files, such as the Jenkinsfile, do not require an update to the changelog.

The following code block should be inserted into the Changelog above the last released version:

## Recent Changes

- <Your changes should>
- <be documented here>

CLI Contribution Guidelines

The following information is critical to 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:

For more information about ... See:
General guidelines that apply to contributing to Zowe CLI and Plug-ins Contribution Guidelines
Conventions and best practices for creating packages and plug-ins for Zowe CLI Package and Plug-in Guidelines
Guidelines for running tests on Zowe CLI Testing Guidelines
Guidelines for running tests on the plug-ins that you build for Zowe CLI Plug-in Testing Guidelines
Documentation that describes the features of the Imperative CLI Framework About Imperative CLI Framework
Versioning conventions for Zowe CLI and Plug-ins Versioning Guidelines
⚡