Skip to content

migrateNode16.md

Latest commit

 

History

History
176 lines (123 loc) · 5.84 KB

migrateNode16.md

File metadata and controls

176 lines (123 loc) · 5.84 KB

⚠️ DEPRECATION WARNING: Node 16 is deprecated and on the end-of-life (EOL) path. This migration guide is provided for reference only. We strongly encourage migrating to Node 20 or Node 24 instead. Please refer to migrateNode24.md for the latest migration guide.

Table of content

Upgrading Tasks to Node 16

  1. Update @types packages in package.json dependencies.

      "dependencies": {
    "@types/node": "^16.11.39"
  }

    If the task does not use built-in nodejs modules (such as fs or path) directly, please remove @types/node from the task dependencies

  2. Upgrade azure-pipelines-task-lib to ^4.1.0 and azure-pipelines-tool-lib to ^2.0.0-preview in package.json dependencies, If a task has these packages.

  3. If you have common npm packages as the task dependency, make sure the azure-pipelines-task-lib and azure-pipelines-tool-lib common package dependencies have the same version as in the task. As a possible solution you also can remove these package versions through the make.json file, for example:

    {
    "rm": [
        {
            "items": [
                "node_modules/azure-pipelines-tasks-java-common/node_modules/azure-pipelines-task-lib",
            ],
            "options": "-Rf"
        }
    ]
}

  4. Add a new Node16 execution handler in task.json

    From To 
    "execution": {
  "Node10": {
    "target": "bash.js",
    "argumentFormat": ""
  }
}
    		 
    "execution": {
  "Node10": {
    "target": "bash.js",
    "argumentFormat": ""
  },
  "Node16": {
    "target": "bash.js",
    "argumentFormat": ""
  }
}

  5. Also in the task.json file, if the minimumAgentVersion isn't present or is less than 2.144.0, change it to 2.144.0.

    "minimumAgentVersion": "2.144.0"

    Agent version 2.144.0 is the first version to support Node10 handlers and the minimumAgentVersion will trigger an automatic upgrade of 2.x.y agents less than 2.144.0.

Common packages dependent on azure-pipeline-task-lib and azure-pipeline-tool-lib

The task-lib package uses some shared (e.g. global object) resources to operate so it may cause unexpected errors in cases when more than one version of the package is installed for a task. This happens if task-lib in child packages has a different version than a task's task-lib. Same for tool-lib.

Testing the changes

We need to test that the task works correctly on node 10 and node 16. How do we need to test the changes:

  • Run unit tests (they should pass on node 10 and node 16)
  • Run pipeline with the task using node 10 handler
  • Run pipeline with the task using node 16 handler

To start a task using node 10, we can set the pipeline variable AGENT_USE_NODE10 to true.

List of known dependency issues

Major commits between Node 10-16 related to fs/child_process/os modules (gathered from notable notes only):

Node 11

fs:

  • The fs.read() method now requires a callback.
  • The previously deprecated fs.SyncWriteStream utility has been removed.

child_process The default value of the windowsHide option has been changed to true.

Node 12

fs:

  • use proper .destroy() implementation for SyncWriteStream
  • improve mode validation
  • harden validation of start option in createWriteStream()
  • make writeFile consistent with readFile wrt fd
  • win, fs: detect if symlink target is a directory

child_process:

  • remove options.customFds
  • harden fork arguments validation
  • use non-infinite maxBuffer defaults

os:

  • implement os.type() using uv_os_uname()
  • remove os.getNetworkInterfaces()

Node 13

child_process:

  • ChildProcess._channel (DEP0129) is now a Runtime deprecation

fs:

  • The undocumented method FSWatcher.prototype.start() was removed
  • Calling the open() method on a ReadStream or WriteStream now emits a runtime deprecation warning. The methods are supposed to be internal and should not be called by user code
  • fs.read/write, fs.readSync/writeSync and fd.read/write now accept any safe integer as their offset parameter. The value of offset is also no longer coerced, so a valid type must be passed to the functions.

Node 14

os:

  • (SEMVER-MAJOR) os: move tmpDir() to EOL fs:
  • (SEMVER-MAJOR) fs: deprecate closing FileHandle on garbage collection
  • add fs/promises alias module (Gus Caplan)

Node 15

fs:

  • (SEMVER-MAJOR) fs: deprecation warning on recursive rmdir
  • (SEMVER-MAJOR) fs: reimplement read and write streams using stream.construct

Node 16:

fs:

  • (SEMVER-MAJOR) fs: remove permissive rmdir recursive
  • (SEMVER-MAJOR) fs: runtime deprecate rmdir recursive option

Feedback

If you run into some issues while migrating to Node 16, please create a ticket with the label "node-migration: Node16".