Problem
VS Code detects the dev container JSON file and auto-suggests users to activate the dev container. For users already familiar with dev containers, this is a tempting approach to setting up the dev environment on their local machines because of the benefits and ease that dev containers usually come with. However, there are bugs in the macOS implementation of Docker's filesystem support that cause significant issues. The underlying problem is that because the maintainers never intended and do not use the devcontainer configuration locally, we are not actively testing this use case in order to find and address the pitfalls.
Description
The clearest solution is to document in the getting started guide that the dev containers are only intended for use with and tested on GitHub Codespaces and, in particular, only for frontend and documentation contributions. We need to document that we do not support its use on local machines.
This is my preferred suggested approach rather than trying to add caveats for local usage because it's easier to specify where we do intend it to work and advise against the other potential use cases. We cannot spend time to work around the issues with the macOS Docker Desktop implementation bugs, for example, when there are other, more wide-spread development experience bugs we should solve, and when that wasn't the intended use case for the devcontainer configuration in the first place.
Essentially, we should say something like: The supplied dev container configuration is only intended for frontend and documentation contributions within GitHub Codespaces. All other use cases (e.g., VS Code, local use, etc) are not supported.
Additionally, if it is possible to detect the codespaces environment in the post_create.sh script, it could be helpful to add a log message and exit 1 if outside that environment. That way unintended use cases do not even appear to work, only to break later on in the development experience.
Additional context
Surfaced in a discussion with @rwidom, @AetherUnbound, and @stacimc.
Problem
VS Code detects the dev container JSON file and auto-suggests users to activate the dev container. For users already familiar with dev containers, this is a tempting approach to setting up the dev environment on their local machines because of the benefits and ease that dev containers usually come with. However, there are bugs in the macOS implementation of Docker's filesystem support that cause significant issues. The underlying problem is that because the maintainers never intended and do not use the devcontainer configuration locally, we are not actively testing this use case in order to find and address the pitfalls.
Description
The clearest solution is to document in the getting started guide that the dev containers are only intended for use with and tested on GitHub Codespaces and, in particular, only for frontend and documentation contributions. We need to document that we do not support its use on local machines.
This is my preferred suggested approach rather than trying to add caveats for local usage because it's easier to specify where we do intend it to work and advise against the other potential use cases. We cannot spend time to work around the issues with the macOS Docker Desktop implementation bugs, for example, when there are other, more wide-spread development experience bugs we should solve, and when that wasn't the intended use case for the devcontainer configuration in the first place.
Essentially, we should say something like: The supplied dev container configuration is only intended for frontend and documentation contributions within GitHub Codespaces. All other use cases (e.g., VS Code, local use, etc) are not supported.
Additionally, if it is possible to detect the codespaces environment in the
post_create.shscript, it could be helpful to add a log message andexit 1if outside that environment. That way unintended use cases do not even appear to work, only to break later on in the development experience.Additional context
Surfaced in a discussion with @rwidom, @AetherUnbound, and @stacimc.