From 27d5e71877fbf8d7a2bfb1ef4f43b4403d72abc2 Mon Sep 17 00:00:00 2001 From: Hossein Abbasi <16090309+hsnabszhdn@users.noreply.github.com> Date: Fri, 4 Jul 2025 13:29:03 +1000 Subject: [PATCH] Signify 'devcontainer.json' through backticks --- docs/specs/devcontainer-features.md | 2 +- docs/specs/devcontainer-id-variable.md | 2 +- docs/specs/devcontainer-lockfile.md | 4 ++-- docs/specs/devcontainerjson-reference.md | 2 +- docs/specs/features-user-env-variables.md | 4 ++-- docs/specs/gpu-host-requirement.md | 2 +- docs/specs/image-metadata.md | 8 ++++---- docs/specs/supporting-tools.md | 4 ++-- 8 files changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/specs/devcontainer-features.md b/docs/specs/devcontainer-features.md index 844575a8..aac3ab81 100644 --- a/docs/specs/devcontainer-features.md +++ b/docs/specs/devcontainer-features.md @@ -108,7 +108,7 @@ Feature scripts run as the `root` user and sometimes need to know which user acc Additionally, the home folders of the two users are passed to the Feature scripts as `_REMOTE_USER_HOME` and `_CONTAINER_USER_HOME` environment variables. -The container user can be set with `containerUser` in the devcontainer.json and image metadata, `user` in the docker-compose.yml, `USER` in the Dockerfile, and can be passed down from the base image. +The container user can be set with `containerUser` in `devcontainer.json` and image metadata, `user` in the docker-compose.yml, `USER` in the Dockerfile, and can be passed down from the base image. ### Dev Container ID diff --git a/docs/specs/devcontainer-id-variable.md b/docs/specs/devcontainer-id-variable.md index 1f7ee612..ca9e8192 100644 --- a/docs/specs/devcontainer-id-variable.md +++ b/docs/specs/devcontainer-id-variable.md @@ -14,7 +14,7 @@ E.g., the `docker-in-docker` feature needs a way to mount a volume per dev conta ## Proposal -The identifier will be referred to as `${devcontainerId}` in the devcontainer.json and the feature metadata and that will be replaced with the dev container's id. It should only be used in parts of the configuration and metadata that is not used for building the image because that would otherwise prevent pre-building the image at a time when the dev container's id is not known yet. Excluding boolean, numbers and enum properties the properties supporting `${devcontainerId}` in the devcontainer.json are: `name`, `runArgs`, `initializeCommand`, `onCreateCommand`, `updateContentCommand`, `postCreateCommand`, `postStartCommand`, `postAttachCommand`, `workspaceFolder`, `workspaceMount`, `mounts`, `containerEnv`, `remoteEnv`, `containerUser`, `remoteUser`, `customizations`. Excluding boolean, numbers and enum properties the properties supporting `${devcontainerId}` in the feature metadata are: `entrypoint`, `mounts`, `customizations`. +The identifier will be referred to as `${devcontainerId}` in `devcontainer.json` and the feature metadata and that will be replaced with the dev container's id. It should only be used in parts of the configuration and metadata that is not used for building the image because that would otherwise prevent pre-building the image at a time when the dev container's id is not known yet. Excluding boolean, numbers and enum properties the properties supporting `${devcontainerId}` in `devcontainer.json` are: `name`, `runArgs`, `initializeCommand`, `onCreateCommand`, `updateContentCommand`, `postCreateCommand`, `postStartCommand`, `postAttachCommand`, `workspaceFolder`, `workspaceMount`, `mounts`, `containerEnv`, `remoteEnv`, `containerUser`, `remoteUser`, `customizations`. Excluding boolean, numbers and enum properties the properties supporting `${devcontainerId}` in the feature metadata are: `entrypoint`, `mounts`, `customizations`. Implementations can choose how to compute this identifier. They must ensure that it is unique among other dev containers on the same Docker host and that it is stable across rebuilds of dev containers. The identifier must only contain alphanumeric characters. We describe a way to do this below. diff --git a/docs/specs/devcontainer-lockfile.md b/docs/specs/devcontainer-lockfile.md index 72dcb1b6..1238404e 100644 --- a/docs/specs/devcontainer-lockfile.md +++ b/docs/specs/devcontainer-lockfile.md @@ -8,7 +8,7 @@ Below is the original proposal. ## Goal -Introduce a lockfile that records the exact version, download information and checksums for each feature listed in the devcontainer.json. +Introduce a lockfile that records the exact version, download information and checksums for each feature listed in `devcontainer.json`. This will allow for: - Improved reproducibility of image builds (installing "latest" of a tool will still have different outcomes as the tool publishes new releases). @@ -19,7 +19,7 @@ This will allow for: (The following is inspired by NPM's `package-lock.json` and Yarn's `yarn.lock`.) -Each feature is recorded with the identifier and version it is referred to in the devcontainer.json as its key and the following properties as its values: +Each feature is recorded with the identifier and version it is referred to in `devcontainer.json` as its key and the following properties as its values: - `resolved`: - OCI feature: A qualified feature id with the sha256 hash (not the version number). - tarball feature: The `https:` URL used to download the feature. diff --git a/docs/specs/devcontainerjson-reference.md b/docs/specs/devcontainerjson-reference.md index a479b5eb..149e1c86 100644 --- a/docs/specs/devcontainerjson-reference.md +++ b/docs/specs/devcontainerjson-reference.md @@ -158,7 +158,7 @@ Variables can be referenced in certain string values in `devcontainer.json` in t | `${containerWorkspaceFolder}` | Any | The path that the workspaces files can be found in the container. | | `${localWorkspaceFolderBasename}` | Any | Name of the local folder that was opened in the `devcontainer.json` supporting service / tool (that contains `.devcontainer/devcontainer.json`). | | `${containerWorkspaceFolderBasename}` | Any | Name of the folder where the workspace files can be found in the container. | -| `${devcontainerId}` | Any | Allow features to refer to an identifier that is unique to the dev container they are installed into and that is stable across rebuilds.
The properties supporting it in devcontainer.json are: `name`, `runArgs`, `initializeCommand`, `onCreateCommand`, `updateContentCommand`, `postCreateCommand`, `postStartCommand`, `postAttachCommand`, `workspaceFolder`, `workspaceMount`, `mounts`, `containerEnv`, `remoteEnv`, `containerUser`, `remoteUser`, and `customizations`. | +| `${devcontainerId}` | Any | Allow features to refer to an identifier that is unique to the dev container they are installed into and that is stable across rebuilds.
The properties supporting it in `devcontainer.json` are: `name`, `runArgs`, `initializeCommand`, `onCreateCommand`, `updateContentCommand`, `postCreateCommand`, `postStartCommand`, `postAttachCommand`, `workspaceFolder`, `workspaceMount`, `mounts`, `containerEnv`, `remoteEnv`, `containerUser`, `remoteUser`, and `customizations`. | ## Schema diff --git a/docs/specs/features-user-env-variables.md b/docs/specs/features-user-env-variables.md index 60eb4b7b..b42d07e3 100644 --- a/docs/specs/features-user-env-variables.md +++ b/docs/specs/features-user-env-variables.md @@ -10,7 +10,7 @@ Below is the original proposal. Feature scripts run as the `root` user and sometimes need to know which user account the dev container will be used with. -(The dev container user can be configured through the `remoteUser` property in the devcontainer.json. If that is not set, the container user will be used.) +(The dev container user can be configured through the `remoteUser` property in `devcontainer.json`. If that is not set, the container user will be used.) ## Proposal @@ -20,4 +20,4 @@ Additionally the home folders of the two users are passed to the feature scripts ## Notes -- The container user can be set with `containerUser` in the devcontainer.json and image metadata, `user` in the docker-compose.yml, `USER` in the Dockerfile and can be passed down from the base image. +- The container user can be set with `containerUser` in `devcontainer.json` and image metadata, `user` in the docker-compose.yml, `USER` in the Dockerfile and can be passed down from the base image. diff --git a/docs/specs/gpu-host-requirement.md b/docs/specs/gpu-host-requirement.md index 9249f92b..8f47ecba 100644 --- a/docs/specs/gpu-host-requirement.md +++ b/docs/specs/gpu-host-requirement.md @@ -14,7 +14,7 @@ This proposal adds GPU support to the existing host requirements properties. ## Proposal -We propose to add a new `gpu` property to the `hostRequirements` object in the devcontainer.json schema. The property can be a boolean value, the string `optional` or an object: +We propose to add a new `gpu` property to the `hostRequirements` object in the `devcontainer.json` schema. The property can be a boolean value, the string `optional` or an object: (Additional row for the existing table in the spec.) | Property | Type | Description | diff --git a/docs/specs/image-metadata.md b/docs/specs/image-metadata.md index c92d3500..8f4d6817 100644 --- a/docs/specs/image-metadata.md +++ b/docs/specs/image-metadata.md @@ -8,7 +8,7 @@ Below is the original proposal. ## Goal -Record dev container config and feature metadata in prebuilt images, such that, the image and the built-in features can be used with a devcontainer.json (image-, Dockerfile- or Docker Compose-based) that does not repeat the dev container config or feature metadata. Other tools should be able to record the same metadata without necessarily using features themselves. +Record dev container config and feature metadata in prebuilt images, such that, the image and the built-in features can be used with a `devcontainer.json` file (image-, Dockerfile- or Docker Compose-based) that does not repeat the dev container config or feature metadata. Other tools should be able to record the same metadata without necessarily using features themselves. Current dev container config that can be recorded in the image: `mounts`, `onCreateCommand`, `updateContentCommand`, `postCreateCommand`, `postStartCommand`, `postAttachCommand`, `customizations`, `remoteUser`, `userEnvProbe`, `remoteEnv`, `containerEnv`, `overrideCommand`, `portsAttributes`, `otherPortsAttributes`, `forwardPorts`, `shutdownAction`, `updateRemoteUserUID` and `hostRequirements`. @@ -18,7 +18,7 @@ We can add to these lists as we add more properties to the dev container configu ## Proposal -We propose to add metadata to the image with the following structure using one entry per feature and devcontainer.json (see table below for the full list): +We propose to add metadata to the image with the following structure using one entry per feature and `devcontainer.json` (see table below for the full list): ``` [ @@ -45,7 +45,7 @@ The metadata is added to the image as a `devcontainer.metadata` label with a JSO ## Merge Logic -To apply the metadata together with a user's devcontainer.json at runtime the following merge logic by property is used. The table also notes which properties are currently supported coming from the devcontainer.json and which from the feature metadata, this will change over time as we add more properties. +To apply the metadata together with user's `devcontainer.json` at runtime the following merge logic by property is used. The table also notes which properties are currently supported coming from `devcontainer.json` and which from the feature metadata, this will change over time as we add more properties. | Property | Type/Format | Merge Logic | devcontainer.json | Feature Metadata | | -------- | ----------- | ----------- | :---------------: | :--------------: | @@ -80,7 +80,7 @@ Variables in string values will be substituted at the time the value is applied. ## Additional devcontainer.json Properties -We are adding support for `mounts`, `containerEnv`, `containerUser`, `init`, `privileged`, `capAdd`, and `securityOpt` to the devcontainer.json (also with Docker Compose) the same way these properties are already supported in the feature metadata. +We are adding support for `mounts`, `containerEnv`, `containerUser`, `init`, `privileged`, `capAdd`, and `securityOpt` to `devcontainer.json` (also with Docker Compose) the same way these properties are already supported in the feature metadata. ## Notes diff --git a/docs/specs/supporting-tools.md b/docs/specs/supporting-tools.md index 40c40f2e..cba81043 100644 --- a/docs/specs/supporting-tools.md +++ b/docs/specs/supporting-tools.md @@ -144,5 +144,5 @@ Some properties may apply differently to codespaces. | `portsAttributes` | object | Codespaces does not yet support the `"host:port"` variation of this property.| | `shutdownAction` | enum | Does not apply to Codespaces. | | `${localEnv:VARIABLE_NAME}` | Any | For Codespaces, the host is in the cloud rather than your local machine.| -| `customizations.codespaces` | object | Codespaces reads this property from devcontainer.json, not image metadata. | -| `hostRequirements` | object | Codespaces reads this property from devcontainer.json, not image metadata. | +| `customizations.codespaces` | object | Codespaces reads this property from `devcontainer.json`, not image metadata. | +| `hostRequirements` | object | Codespaces reads this property from `devcontainer.json`, not image metadata. |