Fixes and additions to the spec.

docs/specs/devcontainer-reference.md

@@ -24,9 +24,9 @@ The `devcontainer.json` specification contains different configuration options r
 
 While this metadata may be provided in different ways, when searching for a devcontainer.json file, products should expect to find a devcontainer.json file in one or more of the following locations (in order of precedence):
 
-.devcontainer/devcontainer.json
-.devcontainer.json
-.devcontainer/**/devcontainer.json (where ** is a sub-folder)
+- .devcontainer/devcontainer.json
+- .devcontainer.json
+- .devcontainer/**/devcontainer.json (where ** is a sub-folder)
 
 It is valid that these files may exist in more than one location, so consider providing a mechanism for users to select one when appropriate.
 
@@ -81,13 +81,24 @@ Mounts allow containers to have access to the underlying machine, share data bet
 
 It is important to note that these mounts are from the underlying compute environment and thus cloud environments might not have access to the same data as a local machine.
 
+A default mount is included so that the source code is accessible from inside the container. Inside the container this mount defaults to `/workspace`.
+`
+## worspaceFolder and worspaceMount
+
+The default mount point for the source code can be set with the `workspaceMount` property. This folder should point to the root of a repository (where the `.git` folder is found) so that source control operations work correctly inside the container. By default this value mirrors `workspaceFolder`. 
+
+> **Note**: It's important that this is not considered in the case of [Docker Compose](#docker-compose-based).
+
+The `workspaceFolder` can then be set to a subfolder if it is desired that IDEs should open this folder by default. This value should be taken into account in all scenarios.
+
+See [`workspaceMount` and `workspaceFolder`](devcontainerjson-reference.md#image-or-dockerfile-specific-properties) for reference.
+
 ## Users
 
 Users control the permissions of applications executed in the containers, allowing the developer to control them. The specification takes into account two types of user definitions:
 
-* Container User: The user that will be used for all operations that run inside a container. It is used to run lifecycle commands among others.
-* Remote User: In case the developer wants to use different users for different purposes, the remote user is the user that connecting tools should use to execute operations inside the container.
-
+* Container User: The user that will be used for all operations that run inside a container. This allows the ENTRYPOINT for the image to execute with different permissions than the developer.
+* Remote User: Used to run the [lifecycle](#lifecycle) scripts inside the container. This is also the user tools and editors that connect to the container should use to run their processes.
 
 # Lifecycle
 
@@ -140,13 +151,23 @@ This step executes the following:
 
 ### Post Container Creation
 
-- At the end of the container creation step, a set of commands are executed inside the **main** container: `on-create-command`, `update-content-command` and `post-create-command`. This set of commands is executed in sequence on a container the first time it's created and depending on the creation parameters received. You can learn more in the [documentation on lifecycle scripts](devcontainerjson-reference.md#lifecycle-scripts). By default, `post-create-command` is executed in the background after reporting the successful creation of the development environment.
-- If the `wait-for` property is defined, then execution should stop at the specified property.
+- At the end of the container creation step, a set of commands are executed inside the **main** container: `onCreateCommand`, `updateContentCommand` and `postCreateCommand`. This set of commands is executed in sequence on a container the first time it's created and depending on the creation parameters received. You can learn more in the [documentation on lifecycle scripts](devcontainerjson-reference.md#lifecycle-scripts). By default, `postCreateCommand` is executed in the background after reporting the successful creation of the development environment.
+- If the `waitFor` property is defined, then execution should stop at the specified property. This property defaults to `updateContentCommand`.
+- The `userEnvProbe` setting dictates whether environment variables present in a particular shell type (login, interactive, login and interactive, or an empty shell) should be passed into all post create or implementation specific commands that are executed. This allows implementors to emulate developer expected behaviors around values added to their profile and rc files. In addition, any remoteEnv values should also be applied to any of these commands.
 
 ## Environment Stop
 
 Stops all containers in the environment. The intention of this step is to ensure all containers are stopped correctly to ensure no data is lost.
 
 ## Environment Restart
 
-After an environment has been stopped, the containers are restarted according to the orchestrator defined. Additionally, `post-start-command` is executed in the **main** container.
+After an environment has been stopped, the containers are restarted according to the orchestrator defined. Additionally, `postStartCommand` is executed in the **main** container.
+
+
+# Implementation specific steps
+
+## Post creation
+
+After the all the steps executed in a succesful creation or restart, any implementation specific commands can safely execute. This specific implementations should take into account the `userEnvProbe` and `remoteEnv` properties.
+
+For example, in the CLI reference implementation, this is the point in which anything executed with `devcontainer exec` would run.

docs/specs/supporting-tools.md

@@ -67,6 +67,8 @@ A [codespace](https://docs.github.com/en/codespaces/overview) is a development e
 
 > **Tip:** If you've already built a codespace and connected to it, be sure to run **Codespaces: Rebuild Container** from the Command Palette (`kbstyle(F1)`) to pick up any changes you make.
 
+> **Tip** Codespaces implements an auto `workspaceFolder` mount in **Docker Compose** scenarios.
+
 #### Product specific properties
 GitHub Codespaces works with a growing number of tools and, where applicable, their `devcontainer.json` properties. For example, connecting the Codespaces web editor or VS Code enables the use of [VS Code properties](#visual-studio-code).