Merge pull request #2840 from github/robertbrignull/node-version

Add docs about the Node.js version

docs/node-version.md

@@ -0,0 +1,29 @@
+# Node version
+
+The CodeQL for VS Code extension defines the version of Node.js that it is intended to run with. This Node.js version is used when running most CI and unit tests.
+
+When running in production (i.e. as an extension for a VS Code application) it will use the Node.js version provided by VS Code. This can mean a different Node.js version is used by different users with different versions of VS Code.
+We should make sure the CodeQL for VS Code extension works with the Node.js version supplied by all versions of VS Code that we support.
+
+## Checking the version of Node.js supplied by VS Code
+
+You can find this info by seleting "About Visual Studio Code" from the top menu.
+
+![about-vscode](images/about-vscode.png)
+
+## Updating the Node.js version
+
+The following files will need to be updated:
+
+- `.github/workflows/cli-test.yml` - the "node-version: '[VERSION]'" setting
+- `.github/workflows/main.yml` - all the "node-version: '[VERSION]'" settings
+- `.github/workflows/release.yml` - the "node-version: '[VERSION]'" setting
+- `extensions/ql-vscode/.nvmrc` - this will enable nvm to automatically switch to the correct node version when you're in the project folder
+- `extensions/ql-vscode/package-lock.json` - the "engines.node: '[VERSION]'" setting
+- `extensions/ql-vscode/package.json` - the "engines.node: '[VERSION]'" setting
+
+## Node.js version used in tests
+
+Unit tests will use whatever version of Node.js is installed locally. In CI this will be the version specified in the workflow.
+
+Integration tests download a copy of VS Code and then will use whatever version of Node.js is provided by VS Code. Our integration tests are currently pinned to an older version of VS Code. See [VS Code version used in tests](./vscode-version.md#vs-code-version-used-in-tests) for more information.

docs/releasing.md

@@ -11,10 +11,7 @@
       * New telemetry events are added.
       * Deprecation or removal of commands.
       * Accumulation of many changes, none of which are individually big enough to warrant a minor bump, but which together are. This does not include changes which are purely internal to the extension, such as refactoring, or which are only available behind a feature flag.
-1. Double-check that the node version we're using matches the one used for VS Code. You can find this info by seleting "About Visual Studio Code" from the top menu. If it doesn't match, you will then need to update the node version in the following files:
-    * `.nvmrc` - this will enable `nvm` to automatically switch to the correct node version when you're in the project folder
-    * `.github/workflows/main.yml` - all the "node-version: '[VERSION]'" settings
-    * `.github/workflows/release.yml` - the "node-version: '[VERSION]'" setting
+1. Double-check that the node version we're using matches the one used for VS Code. See the [Node.js version instructions](./node-version.md) for more information.
 1. Double-check that the extension `package.json` and `package-lock.json` have the version you intend to release. If you are doing a patch release (as opposed to minor or major version) this should already be correct.
 1. Create a PR for this release:
     * This PR will contain any missing bits from steps 1, 2 and 3. Most of the time, this will just be updating `CHANGELOG.md` with today's date.

docs/vscode-version.md

@@ -0,0 +1,33 @@
+# VS Code version
+
+The CodeQL for VS Code extension specifies the versions of VS Code that it is compatible with. VS Code will only offer to install and upgrade the extension when this version range is satisfied.
+
+## Where is the VS Code version specified
+
+1. Hard limit in [`package.json`](https://github.com/github/vscode-codeql/blob/606bfd7f877d9fffe4ff83b78015ab15f8840b12/extensions/ql-vscode/package.json#L16)
+
+    This is the value that VS Code understands and respects. If a user does not meet this version requirement then VS Code will not offer to install the CodeQL for VS Code extension, and if the extension is already installed then it will silently refuse to upgrade the extension.
+
+1. Soft limit in [`extension.ts`](https://github.com/github/vscode-codeql/blob/606bfd7f877d9fffe4ff83b78015ab15f8840b12/extensions/ql-vscode/src/extension.ts#L307)
+
+    This value is used internally by the CodeQL for VS Code extension and is used to provide a warning to users without blocking them from installing or upgrading. If the extension detects that this version range is not met it will output a warning message to the user prompting them to upgrade their VS Code version to ge the latest features of CodeQL.
+
+## When to update the VS Code version
+
+Generally we should aim to support as wide a range of VS Code versions as we can, so unless there is a reason to do so we do not update the minimum VS Code version requirement.
+Reasons for updating the minimum VS Code version include:
+
+- A new feature is included in VS Code. We may want to ensure that it is available to use so we do not have to provide an alternative code path.
+- A breaking change has happened in VS Code, and it is not possible to support both new and old versions.
+
+Also consider what percentage of our users are using each VS Code version. This information is available in our telemetry.
+
+## How to update the VS Code version
+
+To provide a good experience to users, it is recommented to update the `MIN_VERSION` in `extension.ts` first and release, and then update the `vscode` version in `package.json` and release again. By stagging this update across two releases it gives users on older VS Code versions a chance to upgrade before it silently refuses to upgrade them.
+
+## VS Code version used in tests
+
+Our integration tests are currently pinned to use an older version of VS Code due to <https://github.com/github/vscode-codeql/issues/2402>.
+This version is specified in [`jest-runner-vscode.config.base.js`](https://github.com/github/vscode-codeql/blob/d93f2b67c84e79737b0ce4bb74e31558b5f5166e/extensions/ql-vscode/test/vscode-tests/jest-runner-vscode.config.base.js#L17).
+Until this is resolved this will limit us updating our minimum supported version of VS Code.