Skip to content

Edit pass for consistency #307

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Oct 23, 2023
Merged

Edit pass for consistency #307

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
6986fda
Formatting
Oct 20, 2023
ddabab6
Update _implementors/features.md
bamurtaugh Oct 20, 2023
2837c98
Add Slack link
Oct 20, 2023
e8e27c9
Merge branch 'bamurtaugh/edit-pass' of https://github.com/devcontaine…
Oct 20, 2023
8cca3aa
Update _implementors/spec.md
bamurtaugh Oct 23, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion _implementors/contributing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ author: Microsoft
index: 9
---

We're excited for your contributions to the Dev Container Specification! This document outlines how you can get involved.
We're excited for your contributions to the Dev Container Specification! This document outlines how you can get involved. We also welcome you to join our [community Slack channel](https://aka.ms/dev-container-community).

## <a href="#contribution-approaches" name="contribution-approaches" class="anchor"> Contribution approaches </a>

Expand Down
6 changes: 3 additions & 3 deletions _implementors/features-distribution.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ index: 6

**TL;DR Check out the [quick start repository](https://github.com/devcontainers/feature-template) to get started on distributing your own Dev Container Features.**

This specification defines a pattern where community members and organizations can author and self-publish [Dev Container 'Features'](../features).
This specification defines a pattern where community members and organizations can author and self-publish [Dev Container Features](../features).

Goals include:

Expand Down Expand Up @@ -89,7 +89,7 @@ Each Features's `devcontainer-feature.json` metadata file is appended into the `

There are several supported ways to distribute Features. Distribution is handled by the implementing packaging tool such as the [Dev Container CLI](https://github.com/devcontainers/cli) or [Dev Container Publish GitHub Action](https://github.com/marketplace/actions/dev-container-publish). See the [quick start repository](https://github.com/devcontainers/feature-template) for a full working example.

A user references a distributed Feature in a `devcontainer.json` as defined in ['referencing a feature'](../features#referencing-a-feature).
A user references a distributed Feature in a `devcontainer.json` as defined in ['referencing a Feature'](../features#referencing-a-feature).

### <a href="#oci-registry" name="oci-registry" class="anchor"> OCI Registry </a>

Expand Down Expand Up @@ -151,7 +151,7 @@ Additional constraints exists when including local Features in a project:

* The project must have a `.devcontainer/` folder at the root of the [**project workspace folder**](/implementors/spec/#project-workspace-folder).

* A local Feature's source code **must** be contained within a sub-folder of the `.devcontainer/ folder`.
* A local Feature's source code **must** be contained within a sub-folder of the `.devcontainer/` folder.

* The sub-folder name **must** match the Feature's `id` field.

Expand Down
20 changes: 10 additions & 10 deletions _implementors/features.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,13 @@ author: Microsoft
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.
**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.

Feature metadata is captured by a `devcontainer-feature.json` file in the root folder of the feature.

> **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.
> This page 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>

Expand Down Expand Up @@ -72,15 +72,15 @@ The following lifecycle hooks may be declared as properties of `devcontainer-fea
| `postAttachCommand` | [string, array, object](/implementors/json_reference#formatting-string-vs-array-properties) |
{: .table .table-bordered .table-responsive}

#### Behavior
#### <a href="#behavior" name="behavior" class="anchor"> Behavior </a>

Each property mirrors the behavior of the matching property in [`devcontainer.json`](/implementors/json_reference#Lifecycle-scripts), including the behavior that commands are executed from the context of the [project workspace folder](/implementors/spec/#project-workspace-folder).

For each lifecycle hook (in [Feature installation order](/implementors/features/#installation-order)), each command contributed by a Feature is executed in sequence (blocking the next command from executing). Commands provided by Features are always executed _before_ any user-provided lifecycle commands (i.e: in the `devcontainer.json`).

If a Feature provides a given command with the [object syntax](/implementors/json_reference#formatting-string-vs-array-properties), all commands within that group are executed in parallel, but still blocking commands from subsequent Features and/or the `devcontainer.json`.

> NOTE: These properties are stored within [image metadata](/implementors/spec/#merge-logic).
> **Note**: These properties are stored within [image metadata](/implementors/spec/#merge-logic).

### <a href="#options-property" name="options-property" class="anchor"> The `options` property </a>

Expand Down Expand Up @@ -117,11 +117,11 @@ 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 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.

### <a href="#dev-container-id" name="dev-container-id" class="anchor"> Dev Container ID </a>

An 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 Feature metadata are: `entrypoint`, `mounts`, `customizations`.
An 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 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.

Expand Down Expand Up @@ -218,7 +218,7 @@ As a shorthand, the value of the `features` property can be provided as a single
}
```

### <a href="#referencing-a-feature" name="referencing-a-feature" class="anchor"> Referencing a feature </a>
### <a href="#referencing-a-feature" name="referencing-a-feature" class="anchor"> Referencing a Feature </a>

The `id` format specified dicates how a supporting tool will locate and download a given feature. `id` is one of the following:

Expand Down Expand Up @@ -251,7 +251,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 [Features distribution page](../features-distribution)._

## <a href="#execution" name="execution" class="anchor"> Execution </a>

Expand Down Expand Up @@ -313,11 +313,11 @@ After `overrideFeatureInstallOrder` is resolved, any remaining Features that dec

### <a href="#option-resolution" name="option-resolution" class="anchor"> Option Resolution </a>

A Feature's 'options' - specified as the value of a single Feature key/value pair in the user's `devcontainer.json` - are passed to the Feature as environment variables.
A Feature's `options` - specified as the value of a single Feature key/value pair in the user's `devcontainer.json` - are passed to the Feature as environment variables.

A supporting tool will parse the `options` object provided by the user. If a value is provided for a Feature, it will be emitted to a file named `devcontainer-features.env` following the format `<OPTION_NAME>=<value>`.

To ensure a option that is valid as an environment variable, the follow substitutions are performed.
To ensure a option that is valid as an environment variable, the follow substitutions are performed:

```javascript
(str: string) => str
Expand Down
20 changes: 11 additions & 9 deletions _implementors/reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,18 +6,18 @@ author: Microsoft
index: 2
---

The reference implementation for the specification is available through a [development container CLI](https://github.com/devcontainers/cli). This CLI can take a devcontainer.json and create and configure a dev container from it.
The reference implementation for the specification is available through a [development container CLI](https://github.com/devcontainers/cli). This CLI can take a `devcontainer.json` and create and configure a dev container from it.

## <a href="#what-is-CLI" name="what-is-CLI" class="anchor"> What is the dev container CLI? </a>
When tools like VS Code and Codespaces detect a devcontainer.json file in a user's project, they use a CLI to configure a dev container. We've now opened up this CLI as a reference implementation so that individual users and other tools can read in devcontainer.json metadata and create dev containers from it.
## <a href="#what-is-CLI" name="what-is-CLI" class="anchor"> What is the Dev Container CLI? </a>
When tools like VS Code and Codespaces detect a `devcontainer.json` file in a user's project, they use a CLI to configure a dev container. We've now opened up this CLI as a reference implementation so that individual users and other tools can read in `devcontainer.json` metadata and create dev containers from it.

This CLI can either be used directly or integrated into product experiences, similar to how it's integrated with Dev Containers and Codespaces today. It currently supports both a simple single container option and integrates with [Docker Compose](https://docs.docker.com/compose/) for multi-container scenarios.

The CLI is available for review in a new [devcontainers/cli](https://github.com/devcontainers/cli) repository, and you can read more about its development in [this issue](https://github.com/devcontainers/spec/issues/9) in the spec repo.
The CLI is available in the [devcontainers/cli](https://github.com/devcontainers/cli) repository.

## <a href="#try-it" name="try-it" class="anchor"> How can I try it? </a>

We'd love for you to try out the dev container CLI and let us know what you think. You can quickly try it out in just a few simple steps, either by installing its npm package or building the CLI repo from sources.
We'd love for you to try out the Dev Container CLI and let us know what you think. You can quickly try it out in just a few simple steps, either by installing its npm package or building the CLI repo from sources.

You may learn more about building from sources in the [CLI repo's README](https://github.com/devcontainers/cli#try-it-out). On this page, we'll focus on using the npm package.

Expand Down Expand Up @@ -97,7 +97,7 @@ Hello, VS Code Remote - Containers!
{"outcome":"success"}
```

Congrats, you've just run the dev container CLI and seen it in action!
Congrats, you've just run the Dev Container CLI and seen it in action!

These steps are also provided in the CLI repo's [README](https://github.com/devcontainers/cli/blob/main/README.md). You may also review frequently asked questions [here](https://github.com/devcontainers/spec/issues/31).

Expand All @@ -110,13 +110,15 @@ We recommend using the [Dev Container CLI](#npm-install) (or other spec supporti
devcontainer build --workspace-folder . --push true --image-name <my_image_name>:<optional_image_version>
```

You can also check out our [in-depth guide on prebuilds](/_posts/2023-08-22-prebuild.md).

#### <a href="#labels" name="labels" class="anchor"> Metadata in image labels</a>

You can include Dev Container configuration and Feature metadata in prebuilt images via [image labels](https://docs.docker.com/config/labels-custom-metadata/). This makes the image self-contained since these settings are automatically picked up when the image is referenced - whether directly, in a `FROM` in a referenced Dockerfile, or in a Docker Compose file. This helps prevent your Dev Container config and image contents from getting out of sync, and allows you to push updates of the same configuration to multiple repositories through a simple image reference.

This metadata label is **automatically added** when you pre-build using the [Dev Container CLI](#npm-install) (or other spec supporting utilities like the [GitHub Action](https://github.com/marketplace/actions/devcontainers-ci) or [Azure DevOps task](https://marketplace.visualstudio.com/items?itemName=devcontainers.ci)) and includes settings from devcontainer.json and any referenced Dev Container Features.
This metadata label is **automatically added** when you pre-build using the [Dev Container CLI](#npm-install) (or other spec supporting utilities like the [GitHub Action](https://github.com/marketplace/actions/devcontainers-ci) or [Azure DevOps task](https://marketplace.visualstudio.com/items?itemName=devcontainers.ci)) and includes settings from `devcontainer.json` and any referenced Dev Container Features.

This allows you to have a separate **more complex** devcontainer.json you use to pre-build your image, and then a dramatically **simplified one** in one or more repositories. The contents of the image will be merged with this simplified devcontainer.json content at the time you create the container (see the [the spec](/implementors/spec/#merge-logic) for info on merge logic). But at its simplest, you can just reference the image directly in devcontainer.json for the settings to take effect:
This allows you to have a separate **more complex** `devcontainer.json` you use to pre-build your image, and then a dramatically **simplified one** in one or more repositories. The contents of the image will be merged with this simplified devcontainer.json content at the time you create the container (see the [the spec](/implementors/spec/#merge-logic) for info on merge logic). But at its simplest, you can just reference the image directly in `devcontainer.json` for the settings to take effect:

```json
{
Expand All @@ -138,7 +140,7 @@ See the [Dev Container metadata reference](../json_reference) for information on

### <a href="#domainnames" name="domainnames" class="anchor"> Domain Names </a>

If you are behind a firewall that needs to allow specific domains used by the dev container CLI, here's the list of hostnames you should allow communication to go through:
If you are behind a firewall that needs to allow specific domains used by the Dev Container CLI, here's the list of hostnames you should allow communication to go through:

* `containers.dev` - The [homepage](https://containers.dev/) for everything about dev containers. It includes all official and community-supported [Features](https://containers.dev/features) and [Templates](https://containers.dev/templates).
* `ghcr.io`, `*.azurecr.io`, `mcr.microsoft.com` - [OCI registries](https://containers.dev/implementors/features-distribution/#oci-registry) like [GitHub Container Registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry), [Azure Container Registry](azure.microsoft.com/en-us/products/container-registry), and [Microsoft Container Registry](https://mcr.microsoft.com/en-us/catalog?search=dev%20container) serves as the primary distribution mechanism for dev container resources.
Loading