devcontainers · bamurtaugh · Feb 17, 2023 · Feb 17, 2023 · Feb 17, 2023 · Feb 17, 2023
@@ -3,7 +3,7 @@ layout: implementors
 title:  "How to contribute to the Development Container Specification"
 shortTitle: "Contributing"
 author: Microsoft
-index: 8
+index: 9
 ---
 
 We're excited for your contributions to the Dev Container Specification! This document outlines how you can get involved. 

@@ -17,7 +17,7 @@ Goals include:
 - For users, provide the ability for a user to pin to a particular version (absolute, or semantic version) of a Feature to allow for consistent, repeatable environments.
 - Provide the ability to standardize publishing such that [supporting tools](../../supporting) may implement their own mechanism to aid Feature discoverability as they see fit.
 
-> **Tip:** This section covers details on the Features specification. If you are looking for summarized information on creating your own Features, see the [template](https://github.com/devcontainers/feature-template) and [core Features](https://github.com/devcontainers/features) repositories.
+> **Tip:** This section covers details on the Features specification. If you are looking for summarized information on creating your own Features, check out the [quick start](https://github.com/devcontainers/feature-starter) and [core Features](https://github.com/devcontainers/features) repositories.
 
 ## <a href="#source-code" name="source-code" class="anchor"> Source Code </a>
 
@@ -71,7 +71,7 @@ Features are distributed as tarballs. The tarball contains the entire contents o
 
 The tarball is named `devcontainer-feature-<id>.tgz`, where `<id>` is the Feature's `id` field.
 
-A reference implementation for packaging and distributing Features is provided as a GitHub Action (https://github.com/devcontainers/action).
+A reference implementation for packaging and distributing Features is provided as a [GitHub Action](https://github.com/devcontainers/action).
 
 ### <a href="#devcontainer-collection-json" name="devcontainer-collection-json" class="anchor"> devcontainer-collection.json </a>
 

@@ -8,13 +8,11 @@ index: 5
 
 Development container "Features" are self-contained, shareable units of installation code and development container configuration. The name comes from the idea that referencing one of them allows you to quickly and easily add more tooling, runtime, or library "Features" into your development container for you or your collaborators to use.
 
-> **Note:** While Features may be installed on top of any base image, the implementation of a Feature might restrict it to a subset of possible base images. 
-> 
-> For example, some Features may be authored to work with a certain linux distro (e.g. debian-based images that use the `apt` package manager).
-
 Feature metadata is captured by a `devcontainer-feature.json` file in the root folder of the feature.
 
-> **Tip:** This section covers details on the Features specification. If you are looking for summarized information on creating your own Features, see the [template](https://github.com/devcontainers/feature-template) and [core Features](https://github.com/devcontainers/features) repositories.
+> **Note:** While Features may be installed on top of any base image, the implementation of a Feature might restrict it to a subset of possible base images. For example, some Features may be authored to work with a certain Linux distro (e.g. debian-based images that use the `apt` package manager).
+> 
+> This section covers details on the Features specification. If you are looking for summarized information on creating your own Features, check out the [quick start](https://github.com/devcontainers/feature-starter) and [core Features](https://github.com/devcontainers/features) repositories.
 
 ## <a href="#folder-structure" name="folder-structure" class="anchor"> Folder Structure </a>
 
@@ -175,11 +173,11 @@ Below is a valid `features` object provided as an example.
 }
 ```
 
-> Note: The `:latest` version annotation is added implicitly if omitted. To pin to a specific package version ([example](https://github.com/devcontainers/features/pkgs/container/features/go/versions)), append it to the end of the Feature.
+> **Note:** The `:latest` version annotation is added implicitly if omitted. To pin to a specific package version ([example](https://github.com/devcontainers/features/pkgs/container/features/go/versions)), append it to the end of the Feature.
 
 An option's value can be provided as either a `string` or `boolean`, and should match what is expected by the feature in the `devcontainer-feature.json` file.
 
-As a shorthand, the value of a `feature` can be provided as a single string. This string is mapped to an option called `version`.  In the example below, both examples are equivalent. 
+As a shorthand, the value of the `features` property can be provided as a single string. This string is mapped to an option called `version`. In the example below, both examples are equivalent. 
 
 ```jsonc
 "features": {
@@ -217,7 +215,7 @@ Tooling that handles releasing Features will not republish Features if that exac
 
 ## <a href="#authoring" name="authoring" class="anchor"> Authoring </a>
 
-Features can be authored in a number of languages, the most straightforward being bash scripts. If a Feature is authored in a different language information about it should be included in the metadata so that users can make an informed choice about it.
+Features can be authored in a number of languages, the most straightforward being bash scripts. If a Feature is authored in a different language, information about it should be included in the metadata so that users can make an informed choice about it.
 
 Reference information about the application required to execute the Feature should be included in `devcontainer-feature.json` in the metadata section.
 
@@ -227,7 +225,7 @@ If the Feature is included in a folder as part of the repository that contains `
 
 ## <a href="#release" name="release" class="anchor"> Release </a>
 
-_For information on distributing Features, see [the dev container features distribution page](../features-distribution)._
+_For information on distributing Features, see [the dev container Features distribution page](../features-distribution)._
 
 ## <a href="#execution" name="execution" class="anchor"> Execution </a>
 

@@ -172,7 +172,7 @@ Variables can be referenced in certain string values in `devcontainer.json` in t
 | `${devcontainerId}` | Any | Identifier derived from a set of container labels that uniquely idenity the dev container on a Docker host. It allows Features to refer to an identifier that is unique to the dev container they are installed into and that is stable across rebuilds.<br> 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`. |
 {: .table .table-bordered .table-responsive}
 
-## Schema
+## <a href="#schema" name="schema" class="anchor"> Schema </a>
 
 You can see the VS Code implementation of the dev container schema [here](https://github.com/microsoft/vscode/blob/main/extensions/configuration-editing/schemas/devContainer.schema.src.json).
 

@@ -124,7 +124,7 @@ This allows you to have a separate **more complex** devcontainer.json you use to
 }
 ```
 
-Note that you can also opt to you can opt to manually add metadata to an image label instead. These properties will be picked up even if you didn't use the Dev Container CLI to build (and can be updated by the CLI even if you do). For example, consider this Dockerfile snippet:
+Note that you can also opt to manually add metadata to an image label instead. These properties will be picked up even if you didn't use the Dev Container CLI to build (and can be updated by the CLI even if you do). For example, consider this Dockerfile snippet:
 
 ```Dockerfile
 LABEL devcontainer.metadata='[{ \
@@ -134,4 +134,4 @@ LABEL devcontainer.metadata='[{ \
 }]'
 ```
 
-See [Dev Container metadata reference](../json_reference) for information on which properties are supported.
+See the [Dev Container metadata reference](../json_reference) for information on which properties are supported.
@@ -36,7 +36,6 @@ Certain dev container metadata properties can be stored in an image label as an
 
 Metadata should be representative of with the following structure, using one entry per [Dev Container Feature](../features) and devcontainer.json (see table below for the full list):
 
-
 ```json
 [
 	{
@@ -62,7 +61,7 @@ The metadata is added to the image as a `devcontainer.metadata` label with a JSO
 
 ### <a href="#merge-logic" name="merge-logic" class="anchor"> Merge Logic </a>
 
-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 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 from the Feature metadata- this will change over time as we add more properties.
 
 | Property | Type/Format | Merge Logic | devcontainer.json | Feature Metadata |
 | -------- | ----------- | ----------- | :---------------: | :--------------: |
@@ -181,7 +180,7 @@ Users control the permissions of applications executed in the containers, allowi
 * **Container User**: The user that will be used for all operations that run inside a container. This concept is native to containers. It may be set in the container image, using the `containerUser` property for  **image** and **dockerfile** scenarios, or using an orchestratric specific property like `user` property in Docker Compose files.
 * **Remote User**: Used to run the [lifecycle](#lifecycle) scripts inside the container. This is also the user tools and editors that connect to the container should use to run their processes. This concept is not native to containers. Set using the `remoteEnv` property in all cases and defaults to the container user.
 
-This separation allows the ENTRYPOINT for the image to execute with different permissions than the developer and allows for developers to switch users without recreating their containers.
+This separation allows the `ENTRYPOINT` for the image to execute with different permissions than the developer and allows for developers to switch users without recreating their containers.
 
 # <a href="#lifecycle" name="lifecycle" class="anchor"> Lifecycle </a>
 
@@ -203,7 +202,7 @@ The exact steps required to validate configuration can vary based on exactly whe
 
 ## <a href="#environment-creation" name="environment-creation" class="anchor"> Environment Creation </a>
 
-The creation process goes through the steps necesarry to go from the user configuration to a working **environment** that is ready to be used.
+The creation process goes through the steps necessary to go from the user configuration to a working **environment** that is ready to be used.
 
 ### <a href="#initialization" name="initialization" class="anchor"> Initialization </a> 
 
@@ -274,7 +273,7 @@ Like during the create process, remote [environment variables](#environment-vari
 
 Dev containers support a single command for each of its lifecycle scripts. While serial execution of multiple commands can be achieved with `;`, `&&`, etc., parallel execution deserves first-class support.
 
-All lifecycle scripts have been extended to support `object` types. The key of the `object` will be a unique name for the command and the value will be the `string` or `array` command. Each command must exit successfully for the stage to be considered successful.
+All lifecycle scripts have been extended to support `object` types. The key of the `object` will be a unique name for the command, and the value will be the `string` or `array` command. Each command must exit successfully for the stage to be considered successful.
 
 Each entry in the `object` will be run in parallel during that lifecycle step.
 

@@ -1,9 +1,9 @@
 ---
 layout: implementors
-title:  "Dev Container Templates distribution and discovery [proposal]"
+title:  "Dev Container Templates distribution and discovery"
 shortTitle: "Templates distribution"
 author: Microsoft
-index: 10
+index: 8
 ---
 
 **TL;DR Check out the [quick start repository](https://github.com/devcontainers/template-starter) to get started on distributing your own Dev Container Templates.**
@@ -78,6 +78,7 @@ The `devcontainer-collection.json` is an auto-generated metadata file.
 | :--- | :--- | :--- |
 | `sourceInformation` | object | Metadata from the implementing packaging tool. |
 | `templates` | array | The list of Templates that are contained in this collection.|
+{: .table .table-bordered .table-responsive}
 
 Each Template's `devcontainer-template.json` metadata file is appended into the `templates` top-level array.
 

@@ -1,14 +1,14 @@
 ---
 layout: implementors
-title:  "Dev Container Templates reference [proposal]"
+title:  "Dev Container Templates reference"
 shortTitle: "Templates"
 author: Microsoft
-index: 9
+index: 7
 ---
 
 Development container "Templates" are source files packaged together that encode configuration for a complete development environment. A Template can be used in a new or existing project, and a [supporting tool](/supporting) will use the configuration from the Template to build a development container.
 
-The configuration is placed in a [`.devcontainer.json`](/implementors/json_reference#devcontainerjson) which can also reference other files within the Template. Alternatively, `.devcontainer/devcontainer.json` can also be used if the container needs to reference other files, such as a `Dockerfile` or `docker-compose.yml`. A Template can also provide additional source files (eg: boilerplate code or a [lifecycle script](/implementors/json_reference/#lifecycle-scripts).
+The configuration is placed in a [`.devcontainer.json`](/implementors/json_reference#devcontainerjson) which can also reference other files within the Template. Alternatively, `.devcontainer/devcontainer.json` can also be used if the container needs to reference other files, such as a `Dockerfile` or `docker-compose.yml`. A Template can also provide additional source files (eg: boilerplate code or a [lifecycle script](/implementors/json_reference/#lifecycle-scripts)).
 
 Template metadata is captured by a `devcontainer-template.json` file in the root folder of the Template.
 
@@ -41,6 +41,7 @@ The properties of the file are as follows:
 | `platforms` | array | Languages and platforms supported by the Template. |
 | `publisher` | string | Name of the publisher/maintainer of the Template. |
 | `keywords` | array | List of strings relevant to a user that would search for this Template. |
+{: .table .table-bordered .table-responsive}
 
 ### <a href="#options" name="options" class="anchor">  The `options` property</a>
 The `options` property contains a map of option IDs and their related configuration settings. These `options` are used by the supporting tools to prompt the user to choose from different Template configuration options. The tools would replace the option ID with the selected value in all the files (within the sub-directory of the Template). This replacement would happen before dropping the `.devcontainer.json` (or `.devcontainer/devcontainer.json`) and other files (within the sub-directory of the Template) required to containerize your project. See [option resolution](#option-resolution) for more details. For example:
@@ -66,6 +67,7 @@ The `options` property contains a map of option IDs and their related configurat
 | `optionId.proposals` | array | A list of suggested string values. Free-form values **are** allowed. Omit when using `optionId.enum`. |
 | `optionId.enum` | array | A strict list of allowed string values. Free-form values are **not** allowed. Omit when using `optionId.proposals`. |
 | `optionId.default` | string | Default value for the option. |
+{: .table .table-bordered .table-responsive}
 
 > `Note`: The `options` must be unique for every `devcontainer-template.json`
 
@@ -87,7 +89,7 @@ Tooling that handles releasing Templates will not republish Templates if that ex
 
 ## <a href="#release" name="release" class="anchor"> Release </a>
 
-_For information on distributing Templates, see [templates-distribution](/implementors/templates-distribution)._
+_For information on distributing Templates, see the [Templates distribution doc](/implementors/templates-distribution)._
 
 ### <a href="#option-resolution" name="option-resolution" class="anchor"> Option Resolution </a>
 
@@ -119,7 +121,7 @@ Suppose the `java` Template has the following `options` parameters declared in t
           "17",
           "11"
         ],
-			  "default": "17-bullseye"
+    "default": "17-bullseye"
     },
     "nodeVersion": {
         "type": "string", 
@@ -145,14 +147,14 @@ and it has the following `.devcontainer.json` file:
 
 ```json
 {
-	"name": "Java",
-	"image": "mcr.microsoft.com/devcontainers/java:0-${templateOption:imageVariant}",
-	"features": {
-		"ghcr.io/devcontainers/features/node:1": {
-			"version": "${templateOption:nodeVersion}",
-      "installMaven": "${templateOption:installMaven}"
-		}
-	},
+     "name": "Java",
+     "image": "mcr.microsoft.com/devcontainers/java:0-${templateOption:imageVariant}",
+     "features": {
+          "ghcr.io/devcontainers/features/node:1": {
+               "version": "${templateOption:nodeVersion}",
+               "installMaven": "${templateOption:installMaven}"
+          }
+     },
 //	...
 }
 ```
@@ -161,7 +163,7 @@ A user tries to add the `java` Template to their project using the [supporting t
 
 The supporting tool could then use a string replacer for all the files within the sub-directory of the Template. In this example, `.devcontainer.json` needs to be modified and hence, the inputs can provided to it as follows:
 
-```
+```json
 {
   imageVariant:"17-bullseye",
   nodeVersion: "latest",
@@ -173,16 +175,16 @@ The modified `.devcontainer.json` will be as follows:
 
 ```json
 {
-	"name": "Go",
-	"image": "mcr.microsoft.com/devcontainers/go:0-17-bullseye",
-	"features": {
-		"ghcr.io/devcontainers/features/node:1": {
-			"version": "latest",
-      "installMaven": "false"
-		}
-	},
-	...
+     "name": "Go",
+     "image": "mcr.microsoft.com/devcontainers/go:0-17-bullseye",
+     "features": {
+          "ghcr.io/devcontainers/features/node:1": {
+               "version": "latest",
+               "installMaven": "false"
+	  }
+     },
+     ...
 }
 ```
 
-The modified `.devcontainer.json` would be dropped into any existing folder as a starting point for containerizing your project.
+The modified `.devcontainer.json` would be dropped into any existing folder as a starting point for containerizing your project.