Document how Node.js should be upgraded (#87450)

* Document how Node.js should be upgraded

* Apply suggestions from code review

Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com>

* Don't show version numbers as code snippets

* Add information about .ci/Dockerfile edge-case

Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com>

docs/developer/advanced/index.asciidoc

@@ -4,9 +4,12 @@
 * <<running-elasticsearch>>
 * <<development-es-snapshots>>
 * <<development-basepath>>
+* <<upgrading-nodejs>>
 
 include::development-es-snapshots.asciidoc[leveloffset=+1]
 
 include::running-elasticsearch.asciidoc[leveloffset=+1]
 
-include::development-basepath.asciidoc[leveloffset=+1]
+include::development-basepath.asciidoc[leveloffset=+1]
+
+include::upgrading-nodejs.asciidoc[leveloffset=+1]

docs/developer/advanced/upgrading-nodejs.asciidoc

@@ -0,0 +1,76 @@
+[[upgrading-nodejs]]
+== Upgrading Node.js
+
+{kib} requires a specific Node.js version to run.
+When running {kib} from source, you must have this version installed locally.
+
+The required version of Node.js is listed in several different files throughout the {kib} source code.
+Theses files must be updated when upgrading Node.js:
+
+  - {kib-repo}blob/{branch}/.ci/Dockerfile[`.ci/Dockerfile`] - The version is specified in the `NODE_VERSION` constant.
+    This is used to pull the relevant image from https://hub.docker.com/_/node[Docker Hub].
+    Note that Docker Hub can take 24+ hours to be updated with the new images after a new release of Node.js, so if you're upgrading Node.js in Kibana _just_ after the official Node.js release, you have to check if the new images are present on Docker Hub.
+    If they are not, and the update is urgent, you can skip this file and update it later once Docker Hub has been updated.
+  - {kib-repo}blob/{branch}/.node-version[`.node-version`]
+  - {kib-repo}blob/{branch}/.nvmrc[`.nvmrc`]
+  - {kib-repo}blob/{branch}/package.json[`package.json`] - The version is specified in the `engines.node` field.
+
+See PR {kib-repo}pull/86593[#86593] for an example of how the Node.js version has been upgraded previously.
+
+In the 6.8 branch, the `.ci/Dockerfile` file does not exist, so when upgrading Node.js in that branch, just skip that file.
+
+=== Backporting
+
+The following rules are not set in stone.
+Use best judgement when backporting.
+
+Currently version 7.11 and newer run Node.js 14, while 7.10 and older run Node.js 10.
+Hence, upgrades to either Node.js 14 or Node.js 10 shold be done as separate PRs.
+
+==== Node.js patch upgrades
+
+Typically, you want to backport Node.js *patch* upgrades to all supported release branches that run the same _major_ Node.js version:
+
+  - If upgrading Node.js 14, and the current release is 7.11.1, the main PR should target `master` and be backported to `7.x` and `7.11`.
+  - If upgrading Node.js 10, the main PR should target `6.8` only.
+
+==== Node.js minor upgrades
+
+Typically, you want to backport Node.js *minor* upgrades to the next minor {kib} release branch that runs the same *major* Node.js version:
+
+  - If upgrading Node.js 14, and the current release is 7.11.1, the main PR should target `master` and be backported to `7.x`, while leaving the `7.11` branch as-is.
+  - If upgrading Node.js 10, the main PR should target `6.8` only.
+
+=== Upgrading installed Node.js version
+
+The following instructions expect that https://github.com/nvm-sh/nvm[nvm] is used to manage locally installed Node.js versions.
+
+Run the following to install the new Node.js version. Replace `<version>` with the desired Node.js version:
+
+[source,bash]
+----
+nvm install <version>
+----
+
+To get the same global npm modules installed with the new version of Node.js as is currently installed, use the `--reinstall-packages-from` command-line argument (optionally replace `14` with the desired source version):
+
+[source,bash]
+----
+nvm install <version> --reinstall-packages-from=14
+----
+
+If needed, uninstall the old version of Node.js by running the following. Replace `<old-version>` with the full version number of the version that should be uninstalled:
+
+[source,bash]
+----
+nvm uninstall <old-version>
+----
+
+Optionally, tell nvm to always use the "highest" installed Node.js 14 version. Replace `14` if a different major version is desired:
+
+[source,bash]
+----
+nvm alias default 14
+----
+
+Alternatively, include the full version number at the end to specify a specific default version.

docs/developer/getting-started/index.asciidoc

@@ -20,7 +20,7 @@ cd kibana
 
 Install the version of Node.js listed in the `.node-version` file. This
 can be automated with tools such as
-https://github.com/creationix/nvm[nvm],
+https://github.com/nvm-sh/nvm[nvm],
 https://github.com/coreybutler/nvm-windows[nvm-windows] or
 https://github.com/wbyoung/avn[avn]. As we also include a `.nvmrc` file
 you can switch to the correct version when using nvm by running: