Lock Files

[brooke-hamilton]

Dev container lock files (devcontainer-lock.json) were introduced as an experimental feature in 2023. What is the current status? The images repo uses the lock file feature, but I don't see documentation on it and I'm curious if this is still a planned feature or if something else is coming.

It exists in the spec, but it is implemented as an experimental feature in the cli as the --experimental-lockfile argument and as an experimental feature in VS Code: dev.containers.experimentalLockfile.

[shian15810]

Adding to this, currently there are 3 ways to opt in to create a new devcontainer-lock.json:

• Setting "dev.containers.experimentalLockfile": true in VSCode User (only, others won't work) Settings.
• Passing --experimental-lockfile to devcontainer build or devcontainer up.
• Running touch .devcontainer-lock.json before rebuilding according to Empty lockfiles will trigger lockfile to init/populate cli#637, introduced specifically as a workaround for Codespaces users who can't influence the flags passed to devcontainer CLI. No effect on existing populated devcontainer-lock.json.

At the same time, there are 3 ways to upgrade an existing devcontainer-lock.json:

• Setting "dev.containers.experimentalLockfile": true in VSCode User (only, others won't work) Settings.
• Passing --experimental-lockfile to devcontainer build or devcontainer up.
• Running devcontainer upgrade.

But there is only 1 way to enforce devcontainer-lock.json:

• Passing --experimental-frozen-lockfile to devcontainer build or devcontainer up.

---

I'm not sure how feasible it is at the moment to stabilize the naming of this feature by:

• Renaming --experimental-lockfile to --lockfile for devcontainer build/up.
• Renaming --experimental-frozen-lockfile to --frozen-lockfile for devcontainer build/up.
• Renaming "dev.containers.experimentalLockfile" to "dev.containers.lockfile" in VSCode User Settings.

Although they all have experimental in their names, I think renaming them is still worth some thoughts and plans since these changes are definitely not backward compatible, and will certainly break a lot of existing CI/CD pipelines.

---

Adding some thoughts to this after using Dev Containers myself since inception, maybe could help with the transitions mentioned above.

All the ways listed at the top to create/upgrade/enforce devcontainer-lock.json are operational and not declarative, which means it relies on everyone using the same devcontainer.json to synchronize the flags to be passed to devcontainer build/up, or everyone having "dev.containers.experimentalLockfile": true in their respective user-scoped settings.json (though this doesn't help with enforcing devcontainer-lock.json), which is very fragile and often leads to irreproducible builds even though everyone is using the same devcontainer.json.

One of the big reasons people love Docker is due to its property of reproducible builds, and I think this applies to us folks who use and love Dev Containers as well. Hence I think we need a declarative way that can be committed and shared, to tell devcontainer about --experimental-lockfile and --experimental-frozen-lockfile that we intend, so that it can ensure reproducible builds for everyone involved.

Hence I would suggest the addition of the following properties to devcontainer.json:

• The opt in to --experimental-lockfile should be a property (lockfile) that can be declared in devcontainer.json.
  • When unset or set to false and devcontainer-lock.json doesn't exist, this will be a no-op.
  • When set to true and devcontainer-lock.json doesn't exist, this will create new devcontainer-lock.json, unless locked is also set to true, in which case this will fail the build.
  • When set to false and blank devcontainer-lock.json exists, this will be a no-op, suppressing the blank-file trigger.
  • When unset or set to true and blank devcontainer-lock.json exists, this will populate the blank devcontainer-lock.json, unless locked is also set to true, in which case this will fail the build.
  • When set to false and populated devcontainer-lock.json exists, this will be a no-op.
  • When set to true and populated devcontainer-lock.json exists, this will upgrade devcontainer-lock.json, unless locked is also set to true, in which case locked takes precedence, enforcing devcontainer-lock.json instead of upgrading devcontainer-lock.json, and will fail the build if there is any version mismatch.
• The opt in to --experimental-frozen-lockfile should be a property (locked) that can be declared in devcontainer.json.
  • When unset or set to false, this will be a no-op.
  • When set to true, this will enforce devcontainer-lock.json and fail the build if devcontainer-lock.json is empty, missing, or has any version mismatch, regardless of the value of lockfile and whether lockfile is set or not.

Note that lockfile and locked are just placeholders.

The reason there are so many conditions above is to maintain the backward compatibility of:

• lockfile replacing --experimental-lockfile.
• locked replacing --experimental-frozen-lockfile.

On how the addition of lockfile and locked could help with migration and ease backward-incompatible changes:

• For users that don't set any of lockfile or locked in devcontainer.json, while providing none of the experimental flags or settings, proceed with building without any warning or error.
• For users that don't set any of lockfile or locked in devcontainer.json, while providing any of the experimental flags or settings, proceed with building and emit a warning to inform them about the sunsetting date and plan of experimental flags and settings.
• For users that set any of lockfile or locked in devcontainer.json, while providing any of the experimental flags or settings, refuse to build and emit an error to inform them that both sets of settings are mutually exclusive, essentially making this migration opt in.
• For users that set any of lockfile or locked in devcontainer.json, while providing none of the experimental flags or settings, proceed with building without any warning or error.

Just some thoughts and suggestions off my head.

---

Reference: https://mise.jdx.dev/dev-tools/mise-lock.html

Some of the ideas mentioned above are inspired by mise:

• The configuration file of mise has lockfile and locked properties under [settings].
• When lockfile = true, mise.lock will be read and updated, analogous to --experimental-lockfile.
• When locked = true, mise.lock will be respected and not updated, analogous to --experimental-frozen-lockfile.
• Also mise has a mechanism of writing to new mise.lock only if it was created as an empty file beforehand, analogous to Empty lockfiles will trigger lockfile to init/populate cli#637.

Although the lockfile mechanism of mise is not exactly the same as devcontainer, I think this is still very worth referencing since there are so much parallels here.