Preparing for a release

Before release

Before the release is published, we need to prepare the following:

1. Create a new branch named after the version to publish. The name should be in this format: X.Y.Z-release (e.g. "2.1.0-release")
2. Edit the lerna.json file and change the version number:

   {
     "version": "2.1.0", <---
     ...
   }
   

3. Review the release notes in CHANGELOG.md for each package and make any updates needed.
4. Once the changes are done, push the branch to GitHub and open a pull request.
5. For v3 only: Upload l10n terms to POEditor to give contributors an opportunity to translate new terms before the release is published.
   1. In GitHub, download the file poeditor.json file from the release branch.
   2. In the POEditor project, select the "Import" tab and upload the JSON file.

Note: If you ever need to manually update the version number across all files in your branch, follow the steps in Manual versioning.

Release

The release is automatically published when a pull request is merged that meets the following conditions:

• The PR's base branch is a release branch defined in .github/release.config.js. Currently our release branches are main, maintenance, and v1-lts.
• The version number in lerna.json is not a snapshot version. If the version ends with "-SNAPSHOT" it will not be published.

The deployment workflow will perform the following steps:

• Push a commit that updates the version number across all CHANGELOG.md and package.json files (see example here).
• Build the npm packages (TGZ for zowe-explorer-api) and VS Code extensions (VSIX for zowe-explorer and zowe-explorer-ftp-extension).
• Publish the npm packages to the npm registry.
• Publish the VS Code extensions to the VS Code Marketplace and OVSX Registry.
• Create a draft GitHub release with these files uploaded as assets, and post a comment on the PR if the release succeeded (see example here).
• Push another commit that updates the version number, this time to the next snapshot version (see example here).

After release

After the release is published, one more step remains. Review the draft GitHub release, make any desired updates to the release notes, and publish it.

Manual versioning

Note: If you ever need to manually update the version number across all files in your branch, follow the steps below. Typically this is not necessary because the deployment workflow can now update the version number automatically.

Update new version branch with release versioning

1. Create a new branch following the steps in Before release.
2. Replace the "TBD Release" header in each package's changelog with the version number (e.g., ## `2.1.0`).
3. Edit the package.json file for each package and change the following:

• In the following example, we are ready to publish release 1.19.0, so the version number should be changed to "1.19.0" (without -SNAPSHOT).

  • the extension's version number:

    "name": "@zowe/zowe-explorer-api",
    "version": "1.19.0", <---
    "description": "Extensibility API for Zowe Explorer.",
    

  • devDependencies version number:

    "@types/yargs": "^11.0.0",
    "eslint-plugin-zowe-explorer": "1.19.0", <----
    "@typescript-eslint/eslint-plugin": "^2.31.0",
    

  • dependencies version number:

     "dependencies": {
     "@zowe/zowe-explorer-api": "1.19.0", <---
     "fs-extra": "8.0.1",
    

4. Once the changes are done, open a PR to the release branch to update the version.

Update release branch with snapshot versioning

1. Create a branch with the release branch as the base. For example, if release 1.18.1 was just published, the base branch would be v1.18.x.
2. Edit all the package.json and change the following to the next patch pre-release version with -SNAPSHOT:

• In the following example, release 1.18.1 was just published, so the next potential patch version number is 1.18.2. The version number should be changed to "1.18.2-SNAPSHOT".

  • the extension's version number:

    "name": "@zowe/zowe-explorer-api",
    "version": "1.18.2-SNAPSHOT", <---
    "description": "Extensibility API for Zowe Explorer.",
    

  • devDependencies version number:

    "@types/yargs": "^11.0.0",
    "eslint-plugin-zowe-explorer": "1.18.2-SNAPSHOT", <----
    "@typescript-eslint/eslint-plugin": "^2.31.0",
    

  • dependencies version number:

     "dependencies": {
     "@zowe/zowe-explorer-api": "1.18.2-SNAPSHOT", <---
     "fs-extra": "8.0.1",
    

3. Once the changes are done, open a PR to the base release branch (for example, v1.18.x) to update the pre-release version.

Notes:

• pre-release format for publishing follows as version (ie: 2.0.0) followed by -next.<year><month><day><militaryTime> for example 2.0.0-next.202204041200
• If you ever need to manually generate the vsix and tgz files, run the command yarn && yarn run package. They will be generated in dist folder.
• Open VSX and VSC Marketplace Tokens will expire on July 15 2022. Please make sure that these are renewed before doing a release. Contact Fernando Rijo Cedeno or Mark Ackert for more info about renewing tokens