Repository: nodejs/node
Pull request: doc: update devcontainer.json and add documentation

The previous .devcontainer.json configuration was outdated and contained personal configurations that were not needed to run a dev container. This updates the structure so that it's put in .devcontainer/base/devcontainer.json based on the recommended setup in GitHub's documentation. The official image now publishes both arm64 and amd64 images, and devcontainer tools should be able to pick up the right one without extra arguments.

This also adds documentation on how to use the container.

I've also recorded a screencast on how to use the dev container to build a development branch in the Linux container from a macOS host without having to build V8 from scratch, and to test third party code installed from npm using the development branch build in the container: https://www.youtube.com/watch?v=3NwaA67jnB0

Refs: https://github.com/nodejs/devcontainer
Refs: https://hub.docker.com/r/nodejs/devcontainer
Refs: https://docs.github.com/en/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers#devcontainerjson

<!--
Before submitting a pull request, please read:

- the CONTRIBUTING guide at https://github.com/nodejs/node/blob/HEAD/CONTRIBUTING.md
- the commit message formatting guidelines at
  https://github.com/nodejs/node/blob/HEAD/doc/contributing/pull-requests.md#commit-message-guidelines

For code changes:
1. Include tests for any bug fixes or new features.
2. Update documentation if relevant.
3. Ensure that `make -j4 test` (UNIX), or `vcbuild test` (Windows) passes.

If you believe this PR should be highlighted in the Node.js CHANGELOG
please add the `notable-change` label.

Developer's Certificate of Origin 1.1

By making a contribution to this project, I certify that:

(a) The contribution was created in whole or in part by me and I
    have the right to submit it under the open source license
    indicated in the file; or

(b) The contribution is based upon previous work that, to the best
    of my knowledge, is covered under an appropriate open source
    license and I have the right under that license to submit that
    work with modifications, whether created in whole or in part
    by me, under the same open source license (unless I am
    permitted to submit under a different license), as indicated
    in the file; or

(c) The contribution was provided directly to me by some other
    person who certified (a), (b) or (c) and I have not modified
    it.

(d) I understand and agree that this project and the contribution
    are public and that a record of the contribution (including all
    personal information I submit with it, including my sign-off) is
    maintained indefinitely and may be redistributed consistent with
    this project or the open source license(s) involved.
-->


Changed files:
filename: .devcontainer.json
patch: @@ -1,25 +0,0 @@
-{
-  "name": "Node.js Core Developer Environment",
-  "runArgs": [
-    "--platform=linux/amd64"
-  ],
-  "customizations": {
-    "vscode": {
-      "extensions": [
-        "github.vscode-pull-request-github",
-        "ms-vsliveshare.vsliveshare",
-        "vscode-icons-team.vscode-icons",
-        "visualstudioexptteam.vscodeintellicode"
-      ],
-      "settings": {
-        "terminal.integrated.profiles.linux": {
-          "zsh (login)": {
-            "path": "zsh",
-            "args": ["-l"]
-          }
-        }
-      }
-    }
-  },
-  "image": "nodejs/devcontainer:nightly"
-}

filename: .devcontainer/base/devcontainer.json
patch: @@ -0,0 +1,11 @@
+{
+  "name": "Node.js Dev Container",
+  "image": "nodejs/devcontainer:nightly",
+  "workspaceMount": "source=${localWorkspaceFolder},target=/home/developer/nodejs/node,type=bind,consistency=cached",
+  "workspaceFolder": "/home/developer/nodejs/node",
+  "remoteUser": "developer",
+  "mounts": [
+    "source=node-devcontainer-cache,target=/home/developer/nodejs/node/out,type=volume"
+  ],
+  "postCreateCommand": "git restore-mtime"
+}

filename: .github/CODEOWNERS
patch: @@ -231,3 +231,7 @@
 
 # userland-migrations
 /doc/api/deprecations.md @nodejs/userland-migrations
+
+# dev container
+/.devcontainer/* @nodejs/devcontainer
+/doc/contributing/using-devcontainer.md @nodejs/devcontainer

filename: .gitignore
patch: @@ -7,7 +7,6 @@
 .*
 # Exclude specific dotfiles that we want to track.
 !deps/**/.*
-!.devcontainer.json
 !test/fixtures/**/.*
 !.clang-format
 !.cpplint
@@ -167,3 +166,10 @@ __pycache__
 
 # === Rules for C++ development ===
 compile_commands.json
+
+# === Dev Container rules ===
+# Only track the shared base devcontainer.json; ignore everything else under .devcontainer
+!.devcontainer/
+.devcontainer/**
+!.devcontainer/base/
+!.devcontainer/base/devcontainer.json

filename: doc/contributing/using-devcontainer.md
patch: @@ -0,0 +1,131 @@
+# Developing Node.js using Dev Containers
+
+Node.js publishes a [nightly image on DockerHub](https://hub.docker.com/r/nodejs/devcontainer) for
+[Dev Containers](https://containers.dev/) that can be used to spin up a
+development container that comes with pre-installed build dependencies and pre-genreated build cache.
+
+When you need to test a few changes in the main branch and do not need
+to change the V8 headers (which is rare), using the nightly image will allow you to compile your
+changes from a fresh checkout quickly without having to compile the entire codebase, especially V8,
+from scratch.
+
+The Dev Container also allows you to test your changes in a different operating system, and to test
+third-party code from bug reports safely with your work-in-progress Node.js branches in an isolated environment.
+
+There are many command line tools, IDEs and services that [support Dev Containers](https://containers.dev/supporting).
+Among them, [Visual Studio Code (VS Code)](https://code.visualstudio.com/) is a very popuplar option.
+This guide will walk you through the steps to set up a Dev Container for Node.js development using VS Code.
+You should be able to use the same [`nodejs/devcontainer:nightly` image](https://hub.docker.com/r/nodejs/devcontainer)
+in other tools and services using generally similar steps.
+
+## Prerequisites
+
+Before you begin, ensure you have the following installed on your machine:
+
+* [Docker](https://www.docker.com/get-started)
+* [Visual Studio Code](https://code.visualstudio.com/)
+* [Dev Containers extension for VS Code](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
+
+## Setting Up the Dev Container
+
+### 1. Clone the Node.js Repository
+
+If you haven't already, clone the Node.js repository to your local machine.
+
+```bash
+git clone https://github.com/nodejs/node.git
+```
+
+Or follow [this guide](./pull-requests.md#setting-up-your-local-environment) if you are
+setting up the git repository to contribute changes as pull requests.
+
+### 2. Open the Repository in VS Code
+
+Launch VS Code and open the cloned Node.js repository.
+
+### 3. Start the Dev Container
+
+* Press `Ctrl+Shift+P` or `Cmd+Shift+P` to open the command palette.
+* Type `Dev Containers: Reopen in Container` and select it.
+* Select the appropriate Dev Container configuration from the drop down. The base configuration in this
+  repository is `Node.js Dev Container` located in
+  [`.devcontainer/base/devcontainer.json`](../../.devcontainer/base/devcontainer.json), which should be
+  automatically detected by VS Code.
+
+### 4. Wait for the Container to Build
+
+VS Code will build the Dev Container based on the configuration file. This may take some time depending
+on your internet connection and system performance.
+
+After the Dev Container is built, it will start automatically. By default it will run `git restore-mtime` to
+restore the modification times of the files in the working directory, in order to keep the build cache valid,
+and you will see something like this in the terminal.
+
+```text
+Running the postCreateCommand from devcontainer.json...
+
+[10136 ms] Start: Run in container: /bin/sh -c git restore-mtime
+```
+
+This may take a few seconds. Wait until it finishes before you open a new terminal.
+
+### 5. Build your changes
+
+Once the Dev Container is running, you can open a terminal in VS Code and run the build commands. By default,
+your local repository is mounted inside a checkout in the Dev Container, so any changes you make will be reflected
+in the container environment.
+
+In the Dev Container, the necessary dependencies are already installed and Node.js has already been
+compiled, so a usable cache will exist. For better developer experience, the
+build tool used in the Dev Container is `ninja`, instead of `make`. See
+[Building Node.js with Ninja](./building-node-with-ninja.md) for more details on using `ninja` to build Node.js.
+
+```bash
+./configure --ninja
+ninja -C out/Release
+```
+
+As long as your local checkout is not too different from the main branch in the nightly image, the build
+should be incremental and fast.
+
+### 6. Leaving the Container
+
+When you're done working in the Dev Container, open the command palette again and select
+`Dev Containers: Reopen Folder locally` to go back to your local development environment.
+
+## Customizing the Dev Container
+
+The default configuration is located in
+[`.devcontainer/base/devcontainer.json`](../../.devcontainer/base/devcontainer.json) which pairs with the
+official [Node.js Nightly Dev Container image](https://github.com/nodejs/devcontainer).
+This is tracked in version control. You can create a personal configuration by creating a new
+directory in `.devcontainer/` and adding a `devcontainer.json` file there (for example,
+`.devcontainer/local/devcontainer.json`), and configure VS Code to use it.
+
+## Rebuilding the Dev Container
+
+Docker will cache the already downloaded Dev Container images. If you wish to pull a new nightly image, you can do
+so by running the following command in the terminal on your host machine:
+
+```bash
+docker pull nodejs/devcontainer:nightly
+```
+
+The default configuration creates a volume to cache the build outputs between Dev Container restarts. If you wish to
+clear the build cache, you can do so by deleting the volume named `node-devcontainer-cache`.
+
+```bash
+docker volume rm node-devcontainer-cache
+```
+
+To rebuild the Dev Container in VS Code, open the command palette and select
+`Dev Containers: Rebuild and Reopen in Container`.
+
+## Further Reading
+
+* If you want to propose changes to the official Node.js Nightly Dev Container image, feedback is welcome at
+  [nodejs/devcontainer](https://github.com/nodejs/devcontainer). There, you can find the Dockerfile and
+  automated nightly workflows.
+* [Visual Studio Code Dev Containers Documentation](https://code.visualstudio.com/docs/remote/containers)
+* [GitHub's Introduction to Dev Containers](https://docs.github.com/en/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers)
+* [The Dev Containers Specification](https://containers.dev/implementors/spec/)