devcontainers / devcontainers/spec

Confusion in the spec about metadata and merge logic

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

Description

The [JSON reference](https://containers.dev/implementors/json_reference/#general-properties) page shows a table of properties in the `devcontainer.json` with a marker for fields that may be pulled from image metadata.

The [merge logic](https://containers.dev/implementors/spec/#merge-logic) page shows a table of properties, with additional columns indicating if it comes from `devcontainer.json` or "Feature metadata".

The [metadata in image labels](https://containers.dev/implementors/reference/#labels) section shows how to store metadata and where to store it.

I think that the confusion is around understanding the difference between metadata config that comes from a `devcontainer.json` vs from a feature. There's no affordances in the labels to delineate. My *hunch* is that if you're implementing merge logic you should (mostly) ignore the "feature metadata" column on the merge logic table, and if you're implementing labeling you should honor the markers in the JSON reference general properties table, whether the value came from a `devcontainer-feature.json` or a `devcontainer.json`.

For a more specific example, let's look at the `containerEnv` property:

- Is *not* part of `devcontainer-feature.json`
- Is part of `devcontainer.json`
- Is marked as being valid in metadata

If you're building and tagging a devcontainer, you *may* take your entire merged configuration, filter out properties not marked as valid for metadata, and then store it as a new entry in the `devcontainer.metadata` image label list. In our specific case, the `devcontainer.metadata` entry *would* contain `containerEnv`.

Later, if you are building another devcontainer that uses this built image as a base, you would:

- Read in `devcontainer.json`
- Read in all `devcontainer-feature.json`
- Merge these two together
- Read in all `devcontainer.metadata` entries
- Merge `devcontainer.metadata` entries, in order, based on a mix of the general properties markers and the merge logic

That last bullet is the tricky part: `containerEnv` is marked in the merge logic page as something that only comes from `devcontainer.json` and not from feature metadata. But it was stored as metadata according to the spec. So it would be *valid* for the "merged config" to include the `containerEnv` that was stored as metadata, which contradicts the merge logic table.

Am I misunderstanding something fundamental here?

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.