Developer Setup

Developer Setup

Use this page for development environment setup and common contributor workflow tasks across v2 and v3.

For contributor expectations (DCO, testing baseline, refactoring guidance), see Contributor Guidance.

Contents

• Choose your target stream (v2 or v3)
• Prerequisites
• Clone, install dependencies, and build
• Install in VS Code from source
• Testing your changes during development
• Packaging
• Review and merge guidance
• Building with local changes to Zowe CLI
• Related docs

Choose your target stream (v2 or v3)

• v2 development base branch: v2-lts (Yarn-based workflow)
• v3 development base branch: main (pnpm-based workflow)

Pick the branch first, then use the matching package manager commands in the sections below.

Prerequisites

• Install requirements based on the target stream:
  • v2 (v2-lts): Install Node.js v14.0 or later and Yarn Classic.
  • v3 (main): Install Node.js v20.0 or later and pnpm v10.
• Clone the repository if you have write access. Otherwise, fork and clone your fork.
• Create a feature/fix branch from the target base branch.

Clone, install dependencies, and build

Use commands for your target stream:

v2 (v2-lts)

yarn
yarn build

v3 (main)

pnpm install
pnpm run build

Install in VS Code from source

Build Zowe Explorer as a VSIX file and install it in VS Code.

Build a VSIX

v2 (v2-lts)

yarn install
yarn workspace vscode-extension-for-zowe package

v3 (main)

pnpm install
pnpm --filter vscode-extension-for-zowe package

After packaging, a .vsix file is created in ./dist.

Install the VSIX in VS Code

1. Open the Extensions view in VS Code.
2. Select the ... menu and choose Install from VSIX.
3. Select the generated .vsix file.
4. Restart VS Code.

Testing your changes during development

Use the VS Code debugger for quick validation while iterating:

• Run Zowe Explorer VS Code Extension for zowe-explorer changes.
• Run Zowe Explorer FTP VS Code Extension for zowe-explorer-ftp-extension changes.

Additional notes:

• If the debugger is already running, restart it after new changes are built.
• If zowe-explorer-api changes are introduced, rebuild and restart dependent extension debug sessions.

For full testing setup and execution details (v3 E2E, v3 integration, v2 Theia regression), see Testing Setup and Execution.

Packaging

Use packaging commands based on your target stream to package all in the repository:

v2 (v2-lts)

yarn package

v3 (main)

pnpm run package

These commands create extension artifacts in ./dist.

For API/dependency packages like zowe-explorer-api (used by Zowe Explorer and extenders), a TGZ is produced for dependency distribution via npm.

For VS Code extensions, a VSIX is produced that can be installed in VS Code or published to the VS Code Marketplace or Open VSX Registry.

Note: The list of files included in the VSIX bundle is defined by an allowlist in .vscodeignore.

The CI workflows for Zowe Explorer and Zowe Explorer FTP run packaging commands and archive VSIXs as artifacts that can be downloaded for testing. If you have the GitHub CLI installed, you can define a Bash alias like this to download a VSIX for a given branch or pull request (zeVsix main or zeVsix 123):

zeVsix() {
  repo="zowe/vscode-extension-for-zowe"
  case $1 in
    '') echo "Error: You must specify a branch name or PR number" >&2 && return 1 ;;
    *[!0-9]*) branch=$1 ;;
    *) branch=$(gh pr view $1 -R $repo --json headRefName --jq ".headRefName") ;;
  esac
  runId=$(gh run list -R $repo -b $branch --limit 1 --status success --workflow "Zowe Explorer CI" --json databaseId --jq ".[0].databaseId")
  GH_DEBUG=1 gh run download $runId -R $repo -n zowe-explorer-vsix
}

Review and merge guidance

When creating a pull request

Follow the guidelines below when opening a draft pull request. Once checks pass and feedback is addressed, mark the PR ready for review.

• Use a descriptive title (for example, Issue # + short description).
• Link related issue(s) in the PR.
• Add the milestone from the source issue when applicable.
• Add labels to support triage and prioritization.
• Ensure required checks pass (including DCO and CI checks).
• Keep PR scope focused to a single fix/feature when possible.
• Avoid repeated force pushes/new commit churn during active review unless needed.

Reviewer guidance

• Aim for at least 2 approvals.
• Prioritize based on complexity and milestone target.
• Prefer merging by reviewer consensus.
• When filtering open PRs, start with is:pr is:open status:success.

Building with local changes to Zowe CLI

When you are working on upstream changes in Zowe CLI package and want to start consuming it in Zowe Explorer before the feature is merged and version bumped in Zowe Explorer package, it is difficult to get a working solution to override using public package version from node_modules with your local changes.

First, you need to make sure that your local changes in Zowe CLI are sitting on the same minor version as the one that Zowe Explorer is currently using. You may find that this sentence is irrelevant based on whatever changes are being made in the minor versions, however sometimes there are changes between minor versions that are not in sync with what is in Zowe Explorer and the ZE build will fail.

Let's say in this scenario you have changed a method in zowe-cli/packages/zosfiles.

To pull in those changes, first run npm build in that location, then npm pack. This will create a temporary .tgz npm package file.

Now in the Zowe Explorer package.json, in the dependencies, navigate to @zowe/zos-files-for-zowe-sdk and set it to "file:<relative path to zowe-cli repo from zowe explorer repo>/packages/zosfiles/zowe-zos-files-for-zowe-sdk-<version>.tgz". For example, if zowe-explorer-vscode and zowe-cli repos are next to each other, and version is 8.15.3, it would be "file:../../../zowe-cli/packages/zosfiles/zowe-zos-files-for-zowe-sdk-8.31.5.tgz".

Remember that if your changes includes any other changes to other SDK packages, you also need to repeat the above steps for those packages.

If your changes are being used in zowe-explorer-api, you also need to do the same in that area's package.json file.

Finally, if you are facing issues with circular dependencies for no apparent reason, temporarily remove && pnpm madge command from the build step in the package.json scripts section.

Now run pnpm install && pnpm build in the Zowe Explorer repository root to pull in the local packages and build with them. Now you can develop on top of your local changes.

Note: there is also the ability to use link: syntax in the package.json files with just the path to the npm package root rather than building the npm package, however this is found to be a lot more fragile in that sometimes npm will still try to pull in dependencies from node_modules which will cause the build to fail. Sometimes it works, sometimes it doesn't but this whole process is already annoying so just see what works for you.

Related docs

• Contributor Guidance
• Testing Setup and Execution
• Developer Reference