From 916ecf6d751748a777616998b94f99efcf7d0932 Mon Sep 17 00:00:00 2001 From: Thomas Watson Date: Tue, 17 Oct 2023 17:30:47 +0200 Subject: [PATCH] [docs] add info on how to generate custom Node.js builds (#168919) Co-authored-by: amyjtechwriter <61687663+amyjtechwriter@users.noreply.github.com> --- .../advanced/upgrading-nodejs.asciidoc | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/docs/developer/advanced/upgrading-nodejs.asciidoc b/docs/developer/advanced/upgrading-nodejs.asciidoc index 547ef0080cee8..1126a0631265e 100644 --- a/docs/developer/advanced/upgrading-nodejs.asciidoc +++ b/docs/developer/advanced/upgrading-nodejs.asciidoc @@ -4,6 +4,12 @@ {kib} requires a specific Node.js version to run. When running {kib} from source, you must have this version installed locally. +=== Step 1: Generate custom Node.js builds + +Before making a PR to upgrade Node.js, we must first <> matching the desired Node.js version. + +=== Step 2: Create PR to upgrade Node.js + The required version of Node.js is listed in several different files throughout the {kib} source code. These files must be updated when upgrading Node.js: @@ -16,8 +22,8 @@ These files must be updated when upgrading Node.js: - {kib-repo}blob/{branch}/package.json[`package.json`] - The version is specified in the `engines.node` field (if possible, also upgrade `@types/node` to match the new version, both under `devDependencies` and `resolutions`). - {kib-repo}blob/{branch}/WORKSPACE.bazel[`WORKSPACE.bazel`] - The version is specified in the `node_version` property. Besides this property, the list of files under `node_repositories` must be updated along with their respective SHA256 hashes. - These can be found on the https://nodejs.org[nodejs.org] website. - Example for Node.js v18.18.2: https://nodejs.org/dist/v18.18.2/SHASUMS256.txt.asc + These can be found in the `SHASUMS256.txt` file inside the public `kibana-custom-node-artifacts` GCP bucket. + Example for Node.js v18.18.2: https://storage.googleapis.com/kibana-custom-node-artifacts/node-glibc-217/dist/v18.18.2/SHASUMS256.txt[kibana-custom-node-artifacts/node-glibc-217/dist/v18.18.2/SHASUMS256.txt] See PR {kib-repo}pull/128123[#128123] for an example of how the Node.js version has been upgraded previously. @@ -37,6 +43,13 @@ Due to Node.js 16 coming to an https://nodejs.org/en/blog/announcements/nodejs16 To keep support for these older platforms, we're bundling the Linux distributable of {kib} with a https://github.com/elastic/kibana-custom-nodejs-builds[custom build of Node.js] with extended backwards compatibility. The only difference between the offical Node.js build and our custom build, is the version of `glibc` that it's compiled against. +[[start-new-nodejs-build]] +==== How to start a new build + +To generate a new custom Node.js build, https://buildkite.com/elastic/kibana-custom-node-dot-js-builds#new[start a new build] on our dedicated Buildkite pipeline (requires Elastic employee permissions). +Give it a clear name (e.g. `Node 18.18.2`) and remember so set the custom `OVERRIDE_TARGET_VERSION` environment variable to the desired Node.js version - e.g. `OVERRIDE_TARGET_VERSION=18.18.2`. +You find the "Environment Variables" field by expanding "Options >" in the "New Build" dialog. + === Backporting The following rules are not set in stone.