devcontainers
Addition of "extends" top level property to enable simple configuration inheritance
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.
// .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.
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.
Yeah I think this is a worthy thing to consider given https://github.com/microsoft/vscode-remote-release/issues/3279. That said, it might require the result of #7 first since this could affect how you'd make these kinds of references. Agree that a first implementation could be local references to start particularly with that in mind.
In terms of the example though, it shows .devcontainer/project.json which wouldn't be auto-detected currently. I assume that would be either .devcontainer/devcontainer.json or follow the folder structure from #6?
In terms of the example though, it shows .devcontainer/project.json which wouldn't be auto-detected currently. I assume that would be either .devcontainer/devcontainer.json or follow the folder structure from https://github.com/microsoft/dev-container-spec/issues/6?
That's right -- this is an oversight in the sample and wasn't mean to deviate from expecting that the file is named devcontainer.json. I'll update it.
toying around with a simple example repo: https://github.com/joshspicer/extends
