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

[greggroth]

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. #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 docker/compose#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 #23 for more details.

[Chuxel]

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 microsoft/vscode-remote-release#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?

[greggroth]

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?

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.

[joshspicer]

toying around with a simple example repo: https://github.com/joshspicer/extends

[phorcys420]

sorry to be that guy but, is there any news on this topic ?

[acdha]

The main use I have for this is similar to #305: I have a project using a dev container which has a base image from our common registry. If I want to override that base image currently (for example to use an ARM image instead of x86-64), I have to edit devcontainer.json and remember not to commit the changes. It would be useful if I could have an override file which would change a Docker build argument but otherwise keep behaviour inline with everything else.