devcontainers / devcontainers/spec
Addition of "extends" top level property to enable simple configuration inheritance
- 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
Assessment
This issue has not been assessed yet.