devcontainers / devcontainers/spec

Addition of "extends" top level property to enable simple configuration inheritance

Open
#22 15 comments 145 reactions 0 assignees View on GitHub
finalization
Dominant language
No language data
Stars
5.7k
Forks
496
PR merge metrics
No merged PRs in 30d

Description

# Problem

Multiple teams collaborating on a common codebase may have different dependency or setup needs and currently this is done by sharing a single `devcontainer.json` configuration with all of their individual needs combined. https://github.com/microsoft/dev-container-spec/issues/6 describes support for multiple configuration files, but there isn't set a way to consolidate the shared configuration into a single file.

# Proposed Solution

Introduce a new top level key `"extends"` with a value that is a relative a file path within the same repository to a "parent" devcontainer configuration. The configurations will be merged using the [same rules applied by a Docker Compose overrides file](https://docs.docker.com/compose/extends/#adding-and-overriding-configuration).

```json5
// .devcontainer/defaults.json
{
"name": "example/project",
"forwardPorts": [80, 5432],
"hostRequirements": {
"storage": "64gb",
"memory": "16gb"
}
}

// .devcontainer/devcontainer.json
{
"extends": "./defaults.json",
"forwardPorts": [2222],
"hostRequirements": {
"memory": "32gb"
},
"onCreateCommand": ".devcontainer/on-create-command.sh",
}

// Results in
{
"name": "example/project",
"forwardPorts": [80, 5432, 2222], // <-- Array values are the UNION
"hostRequirements": {
"storage": "64gb",
"memory": "32gb" // <-- Basic types overwrite
},
"onCreateCommand": ".devcontainer/on-create-command.sh", // <-- New keys are added
}
```

where the value of "extends" is a relative path to a JSON or JSONC file in the same repository:

- Same Directory: `"./defaults.json"`
- Parent Director: `"../defaults.json"`
- Subdirectory: `"./dev/defaults.json"`

# Future

## Add support for referring to configuration outside the repository

Users may have a use-case for keeping some shared configuration in a separate repository. The described solution does not support this, but support for this could be added.

## Add support for JSON Schema/Open API 3.0 style "$ref" document imports

The described solution is opinionated about how to merge a document, which may not be a good fit for everyone's needs (see https://github.com/docker/compose/issues/3729). A more sophisticated document reference method could be introduced to give users more control to import documents within objects or arrays and to reference objects within imported documents. See https://github.com/microsoft/dev-container-spec/issues/23 for more details.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.