Preparing for a release

Before release

Before publishing a minor release, we must first follow these steps:

1. Create a branch based off of main to prepare the release. This branch should contain any final adjustments to the changelog, as well as last-minute necessary changes.
2. Remove the -SNAPSHOT suffix from the version number in lerna.json to prepare the automation for the release. Push this branch up to GitHub.
3. 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.
4. Create a PR for this branch to merge into main. Once reviewed and approved, the branch can be merged into main to kick off the release process. Once the workflows finish, the release will be published.
5. As soon as the PR has been merged, create a branch based off of main with the following format: release/X.Y
   • X represents the major version number
   • Y represents the minor version number

For patch releases, create a temporary branch based off of the release/X.Y branch (from the last minor release) instead - this temporary branch should not be named after a protected rule. The changes will be merged into that release branch. Depending on the changes made for each patch, you may have to introduce a separate, small PR into main that incorporates those patch notes into the latest versions of the changelogs.

Handling bug fixes

If a bug is spotted during code freeze, we should try to introduce the bug fix into the main branch, and then cherry-pick that fix into the release/X.Y branch.

If there is a reason we need to push a fix directly into the release branch, we can merge that branch back into main so that we keep those bug fixes in the codebase. However, we should avoid this approach and prefer merging bug fixes into main whenever possible.

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

Removing stale release branches

To keep release branches from piling up, we can choose keep a number of "previous release branches" to keep in the repository. The "last 2 minor versions" of a major release should be sufficient for our case. This could be considered a reference point for where a feature was working properly (or before a bug was introduced).

Once v3 becomes the active major version, we can create a v2-lts branch that would serve as a checkpoint for any v2 maintenance releases. We would follow this same release process for the v2-lts branch.

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 next, v1-lts, and all branches prefixed with release/.
• 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 15th, 2025. Please make sure that these are renewed before doing a release. Contact Fernando Rijo Cedeno or Mark Ackert for more info about renewing tokens.