diff --git a/docs/specs/devcontainer-features.md b/docs/specs/devcontainer-features.md index 844575a..aac3ab8 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 1f7ee61..ca9e819 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 72dcb1b..1238404 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 a479b5e..149e1c8 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 60eb4b7..b42d07e 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 9249f92..8f47ecb 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 c92d350..8f4d681 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 40c40f2..cba8104 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. |