Multiple devcontainer.json files & advanced codespace creation options (GA) (#26708)

components/playground/content/codespaces/setting-up-your-project-for-codespaces/setting-up-your-project-for-codespaces/dotnet.tsx

@@ -2,8 +2,8 @@ import dedent from 'ts-dedent'
 import { PlaygroundArticleT } from 'components/playground/types'
 
 const article: PlaygroundArticleT = {
-  title: 'Add a dev container to your project',
+  title: 'Add a dev container configuration to your repository',
-  shortTitle: 'C# Codespaces',
+  shortTitle: 'C# codespaces',
   topics: ['Codespaces', 'Developer', 'Organization'],
   type: 'tutorial',
   slug: '/codespaces/setting-up-your-project-for-codespaces/setting-up-your-project-for-codespaces',
@@ -11,11 +11,13 @@ const article: PlaygroundArticleT = {
     '/codespaces/setting-up-your-project-for-codespaces/setting-up-your-dotnet-project-for-codespaces',
   codeLanguageId: 'dotnet',
   intro: dedent`
-  This guide shows you how to add a [dev container](/codespaces/setting-up-your-project-for-codespaces/configuring-codespaces-for-your-project) to define the Codespaces configuration for your **C# (.NET)** project. For other project languages, click the language button to the right.
+  This guide shows you how to add a dev container configuration to your repository to define the GitHub Codespaces development environment for your **C# (.NET)** codebase. For more information, see "[Introduction to dev containers](/codespaces/setting-up-your-project-for-codespaces/introduction-to-dev-containers)." 
+  
+  If you want to add a dev container configuration for another programming language, click the language button to the right.
  `,
   prerequisites: dedent`
     - You should have an existing C# (.NET) project in a repository on GitHub.com. If you don't have a project, you can try this tutorial with the following example: https://github.com/2percentsilk/python-quickstart.
-    - Codespaces must be enabled for your organization. For more information, see "[Enabling Codespaces for your organization](/codespaces/managing-codespaces-for-your-organization/enabling-codespaces-for-your-organization)."
+    - GitHub Codespaces must be enabled for your organization. For more information, see "[Enabling GitHub Codespaces for your organization](/codespaces/managing-codespaces-for-your-organization/enabling-codespaces-for-your-organization)."
   `,
   contentBlocks: [
     {
@@ -25,17 +27,19 @@ const article: PlaygroundArticleT = {
       type: 'default',
       title: 'Step 1: Open your project in a codespace',
       content: dedent`
-        1. Under the repository name, use the **Code** drop-down menu, and in the **Codespaces** tab, click **New codespace**.
+        1. Under the repository name, use the **Code** drop-down menu, and in the **Codespaces** tab, click **Create codespace on BRANCH**.
 
             ![New codespace button](/assets/images/help/codespaces/new-codespace-button.png)
 
-            If you don’t see this option, Codespaces isn't available for your project. See [Access to Codespaces](/codespaces/developing-in-codespaces/creating-a-codespace#access-to-codespaces) for more information.
+            If you don’t see this option, GitHub Codespaces isn't available for your project. See [Access to GitHub Codespaces](/codespaces/developing-in-codespaces/creating-a-codespace#access-to-codespaces) for more information.
 
         When you create a codespace, your project is created on a remote VM that is dedicated to you. By default, the container for your codespace has many languages and runtimes including .NET. It also includes a common set of tools like git, wget, rsync, openssh, and nano.
 
         You can customize your codespace by adjusting the amount of vCPUs and RAM, [adding dotfiles to personalize your environment](/codespaces/setting-up-your-codespace/personalizing-codespaces-for-your-account), or by modifying the tools and scripts installed.
         
-        Codespaces uses a file called \`devcontainer.json\` to store configurations. On launch Codespaces uses the file to install any tools, dependencies, or other set up that might be needed for the project. For more information, see "[Introduction to dev containers](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)."
+        GitHub Codespaces uses a file called \`devcontainer.json\` to configure the development container that you use when you work in a codespace. Each repository can contain one or more  \`devcontainer.json\` files, to give you exactly the development environment you need to work on your code in a codespace.
+        
+        On launch, GitHub Codespaces uses a \`devcontainer.json\` file, and any dependent files that make up the dev container configuration, to install tools and runtimes, and perform other setup tasks that the project requires. For more information, see "[Introduction to dev containers](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)."
       `,
     },
     {
@@ -43,11 +47,11 @@ const article: PlaygroundArticleT = {
         id: '0',
       },
       type: 'default',
-      title: 'Step 2: Add a dev container to your codespace from a template',
+      title: 'Step 2: Add a dev container configuration to your repository from a template',
       content: dedent`
-       The default codespaces container comes with the latest .NET version and common tools preinstalled. However, we recommend that you set up a custom container to define the tools and scripts that your project needs. This will ensure a fully reproducible environment for all Codespaces users in your repository.
+        The default development container, or "dev container," for GitHub Codespaces comes with the latest .NET version and common tools preinstalled. However, we recommend that you configure your own dev container to include all of the tools and scripts that your project needs. This will ensure a fully reproducible environment for all GitHub Codespaces users in your repository.
 
-        To set up your project with a custom container, you will need to use a \`devcontainer.json\` file to define the environment. In Codespaces you can add this either from a template or you can create your own. For more information on dev containers, see "[Introduction to dev containers](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)".
+        To set up your repository to use a custom dev container, you will need to create one or more \`devcontainer.json\` files. You can add these either from a template, in Visual Studio Code, or you can write your own. For more information on dev container configurations, see "[Introduction to dev containers](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)".
 
         1. Access the Command Palette (\`Shift + Command + P\` / \`Ctrl + Shift + P\`), then start typing "dev container". Select **Codespaces: Add Development Container Configuration Files...**.
           ![Codespaces: Add Development Container Configuration Files... in the command palette](/assets/images/help/codespaces/add-prebuilt-container-command.png)
@@ -70,7 +74,7 @@ const article: PlaygroundArticleT = {
       type: 'sub-section',
       title: 'Anatomy of your dev container',
       content: dedent`
-      Adding the C# (.NET) dev container template adds a \`.devcontainer\` folder to the root of your project's repository with the following files:
+      Adding the C# (.NET) dev container template adds a \`.devcontainer\` directory to the root of your project's repository with the following files:
 
         - \`devcontainer.json\`
         - Dockerfile
@@ -96,7 +100,7 @@ const article: PlaygroundArticleT = {
       },
       content: dedent`
         **\`build\`** - The build properties.
-          - **\`dockerfil\`e** - In the build object, dockerfile is a reference to the Dockerfile that was also added from the template.
+          - **\`dockerfile\`** - In the \`build\` object, \`dockerfile\` contains the path to the Dockerfile that was also added from the template.
           - **\`args\`**
             - **\`VARIANT\`**: This file only contains one build argument, which is the .NET Core version that we want to use.
       `,
@@ -140,7 +144,7 @@ const article: PlaygroundArticleT = {
         highlight: 29,
       },
       content: dedent`
-        **\`postCreateCommand\`** - If you want to run anything after you land in your codespace that’s not defined in the Dockerfile, like \`dotnet restore\`, you can do that here.
+      **\`postCreateCommand\`** - Use this to run commands that aren't defined in the Dockerfile, like \`dotnet restore\`, after your codespace is created.
       `,
     },
     {
@@ -160,7 +164,7 @@ const article: PlaygroundArticleT = {
       type: 'sub-section',
       title: 'Dockerfile',
       content: dedent`
-        You can use the Dockerfile to add additional container layers to specify OS packages, node versions, or global packages we want included in our Dockerfile.
+        You can use the Dockerfile to add additional container layers to specify OS packages, node versions, or global packages we want included in our container.
       `,
     },
     {
@@ -171,7 +175,7 @@ const article: PlaygroundArticleT = {
       type: 'default',
       title: 'Step 3: Modify your devcontainer.json file',
       content: dedent`
-        With your dev container added and a basic understanding of what everything does, you can now make changes to configure it for your environment. In this example, you'll add properties to install extensions and your project dependencies when your codespace launches.
+        With your dev container configuration added and a basic understanding of what everything does, you can now make changes to customize your environment further. In this example, you'll add properties to install extensions and your project dependencies when your codespace launches.
 
         1. In the Explorer, expand the \`.devcontainer\` folder and select the \`devcontainer.json\` file from the tree to open it.
 
@@ -182,7 +186,7 @@ const article: PlaygroundArticleT = {
            \`\`\`json{:copy}
            "extensions": [
                "ms-dotnettools.csharp",
-               "streetsidesoftware.code-spell-checker",
+               "streetsidesoftware.code-spell-checker"
              ],
            \`\`\`
          

components/playground/content/codespaces/setting-up-your-project-for-codespaces/setting-up-your-project-for-codespaces/java.tsx

@@ -2,8 +2,8 @@ import dedent from 'ts-dedent'
 import { PlaygroundArticleT } from 'components/playground/types'
 
 const article: PlaygroundArticleT = {
-  title: 'Add a dev container to your project',
+  title: 'Add a dev container configuration to your repository',
-  shortTitle: 'Add a dev container to your project',
+  shortTitle: 'Java codespaces',
   topics: ['Codespaces', 'Developer', 'Organization', 'Java'],
   type: 'tutorial',
   slug: '/codespaces/setting-up-your-project-for-codespaces/setting-up-your-project-for-codespaces',
@@ -11,11 +11,13 @@ const article: PlaygroundArticleT = {
     '/codespaces/setting-up-your-project-for-codespaces/setting-up-your-java-project-for-codespaces',
   codeLanguageId: 'java',
   intro: dedent`
-  This guide shows you how to add a [dev container](/codespaces/setting-up-your-project-for-codespaces/configuring-codespaces-for-your-project) to define the Codespaces configuration for your **Java** project. For other project languages, click the language button to the right.
+  This guide shows you how to add a dev container configuration to your repository to define the GitHub Codespaces development environment for your **Java** codebase. For more information, see "[Introduction to dev containers](/codespaces/setting-up-your-project-for-codespaces/introduction-to-dev-containers)." 
+  
+  If you want to add a dev container configuration for another programming language, click the language button to the right.
   `,
   prerequisites: dedent`
   - You should have an existing Java project in a repository on GitHub.com. If you don't have a project, you can try this tutorial with the following example: https://github.com/microsoft/vscode-remote-try-java
-  - Codespaces must be enabled for your organization. For more information, see "[Enabling Codespaces for your organization](/codespaces/managing-codespaces-for-your-organization/enabling-codespaces-for-your-organization)."
+  - GitHub Codespaces must be enabled for your organization. For more information, see "[Enabling GitHub Codespaces for your organization](/codespaces/managing-codespaces-for-your-organization/enabling-codespaces-for-your-organization)."
   `,
   contentBlocks: [
     {
@@ -25,15 +27,17 @@ const article: PlaygroundArticleT = {
       type: 'default',
       title: 'Step 1: Open your project in a codespace',
       content: dedent`
-        1. Under the repository name, use the **Code** drop-down menu, and in the **Codespaces** tab, click **New codespace**.
+        1. Under the repository name, use the **Code** drop-down menu, and in the **Codespaces** tab, click **Create codespace on BRANCH**.
 
             ![New codespace button](/assets/images/help/codespaces/new-codespace-button.png)
 
-           If you don’t see this option, Codespaces isn't available for your project. See [Access to Codespaces](/codespaces/developing-in-codespaces/creating-a-codespace#access-to-codespaces) for more information.
+           If you don’t see this option, GitHub Codespaces isn't available for your project. See [Access to GitHub Codespaces](/codespaces/developing-in-codespaces/creating-a-codespace#access-to-codespaces) for more information.
 
         When you create a codespace, your project is created on a remote VM that is dedicated to you. By default, the container for your codespace has many languages and runtimes including Java, nvm, npm, and yarn. It also includes a common set of tools like git, wget, rsync, openssh, and nano.
         
-        Codespaces uses a file called \`devcontainer.json\` to store configurations. On launch Codespaces uses the file to install any tools, dependencies, or other set up that might be needed for the project. For more information, see "[Introduction to dev containers](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)."
+        GitHub Codespaces uses a file called \`devcontainer.json\` to configure the development container that you use when you work in a codespace. Each repository can contain one or more  \`devcontainer.json\` files, to give you exactly the development environment you need to work on your code in a codespace. 
+        
+        On launch, GitHub Codespaces uses a \`devcontainer.json\` file, and any dependent files that make up the dev container configuration, to install tools and runtimes, and perform other setup tasks that the project requires. For more information, see "[Introduction to dev containers](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)."
       `,
     },
     {
@@ -41,11 +45,11 @@ const article: PlaygroundArticleT = {
         id: '0',
       },
       type: 'default',
-      title: 'Step 2: Add a dev container to your codespace from a template',
+      title: 'Step 2: Add a dev container configuration to your repository from a template',
       content: dedent`
-        The default codespaces container comes with the latest Java version, package managers (Maven, Gradle), and other common tools preinstalled. However, we recommend that you set up a custom container to define the tools and scripts that your project needs. This will ensure a fully reproducible environment for all Codespaces users in your repository.
+        The default development container, or "dev container," for GitHub Codespaces comes with the latest Java version, package managers (Maven, Gradle), and other common tools preinstalled. However, we recommend that you configure your own dev container to include all of the tools and scripts that your project needs. This will ensure a fully reproducible environment for all GitHub Codespaces users in your repository.
 
-        To set up your project with a custom container, you will need to use a \`devcontainer.json\` file to define the environment. In Codespaces you can add this either from a template or you can create your own. For more information on dev containers, see "[Introduction to dev containers](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)".
+        To set up your repository to use a custom dev container, you will need to create one or more \`devcontainer.json\` files. You can add these either from a template, in Visual Studio Code, or you can write your own. For more information on dev container configurations, see "[Introduction to dev containers](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)".
 
         1. Access the Command Palette (\`Shift + Command + P\` / \`Ctrl + Shift + P\`), then start typing "dev container". Select **Codespaces: Add Development Container Configuration Files...**.
           !["Codespaces: Add Development Container Configuration Files..." in the command palette](/assets/images/help/codespaces/add-prebuilt-container-command.png)
@@ -65,7 +69,7 @@ const article: PlaygroundArticleT = {
       type: 'sub-section',
       title: 'Anatomy of your dev container',
       content: dedent`
-        Adding the Java dev container template adds a .devcontainer folder to the root of your project's repository with the following files:
+        Adding the Java dev container template adds a .devcontainer directory to the root of your project's repository with the following files:
 
         - \`devcontainer.json\`
         - Dockerfile
@@ -91,7 +95,7 @@ const article: PlaygroundArticleT = {
       },
       content: dedent`
         **\`build\`** - The build properties.
-          - **\`dockerfile\`** - In the build object, dockerfile is a reference to the Dockerfile that was also added from the template.
+          - **\`dockerfile\`** - In the \`build\` object, \`dockerfile\` contains the path to the Dockerfile that was also added from the template.
           - **\`args\`**
             - **\`VARIANT\`**: This file only contains one build argument, which is the Java version that is passed into the Dockerfile.
       `,
@@ -135,7 +139,7 @@ const article: PlaygroundArticleT = {
         highlight: 34,
       },
       content: dedent`
-        **\`postCreateCommand\`** - If you want to run anything after you land in your codespace that’s not defined in the Dockerfile, you can do that here.
+        **\`postCreateCommand\`** - Use this to run commands that aren't defined in the Dockerfile, after your codespace is created.
       `,
     },
     {
@@ -155,7 +159,7 @@ const article: PlaygroundArticleT = {
       type: 'sub-section',
       title: 'Dockerfile',
       content: dedent`
-        You can use the Dockerfile to add additional container layers to specify OS packages, node versions, or global packages we want included in our Dockerfile.
+        You can use the Dockerfile to add additional container layers to specify OS packages, node versions, or global packages we want included in our container.
       `,
     },
     {
@@ -166,7 +170,7 @@ const article: PlaygroundArticleT = {
       type: 'default',
       title: 'Step 3: Modify your devcontainer.json file',
       content: dedent`
-        With your dev container added and a basic understanding of what everything does, you can now make changes to configure it for your environment. In this example, you'll add properties to install extensions and your project dependencies when your codespace launches.
+        With your dev container configuration added and a basic understanding of what everything does, you can now make changes to customize your environment further. In this example, you'll add properties to install extensions and your project dependencies when your codespace launches.
 
         1. In the Explorer, expand the \`.devcontainer\` folder and select the \`devcontainer.json\` file from the tree to open it.
 
@@ -179,7 +183,7 @@ const article: PlaygroundArticleT = {
            "forwardPorts": [4000],
            \`\`\`
          
-           For more information on \`devcontainer.json\` properties, see the [devcontainer.json reference](https://code.visualstudio.com/docs/remote/devcontainerjson-reference) on the Visual Studio Code docs.
+           For more information about \`devcontainer.json\` properties, see the Visual Studio Code documentation: "[devcontainer.json reference](https://code.visualstudio.com/docs/remote/devcontainerjson-reference)."
 
         4. Access the command palette (\`Shift + Command + P\`/ \`Ctrl + Shift + P\`), then start typing "rebuild". Select **Codespaces: Rebuild Container**. 
           ![Rebuild container option](/assets/images/help/codespaces/codespaces-rebuild.png)

components/playground/content/codespaces/setting-up-your-project-for-codespaces/setting-up-your-project-for-codespaces/nodejs.tsx

@@ -2,8 +2,8 @@ import dedent from 'ts-dedent'
 import { PlaygroundArticleT } from 'components/playground/types'
 
 const article: PlaygroundArticleT = {
-  title: 'Add a dev container to your project',
+  title: 'Add a dev container configuration to your repository',
-  shortTitle: 'Node.js Codespaces',
+  shortTitle: 'Node.js codespaces',
   topics: ['Codespaces', 'Developer', 'Organization', 'Node', 'JavaScript'],
   type: 'tutorial',
   slug: '/codespaces/setting-up-your-project-for-codespaces/setting-up-your-project-for-codespaces',
@@ -11,11 +11,13 @@ const article: PlaygroundArticleT = {
     '/codespaces/setting-up-your-project-for-codespaces/setting-up-your-nodejs-project-for-codespaces',
   codeLanguageId: 'nodejs',
   intro: dedent`
-  This guide shows you how to add a [dev container](/codespaces/setting-up-your-project-for-codespaces/configuring-codespaces-for-your-project) to define the Codespaces configuration for your **JavaScript**, **Node.js**, or **TypeScript** project. For other project languages, click the language button to the right.
+  This guide shows you how to add a dev container configuration to your repository to define the GitHub Codespaces development environment for your **Node.js** codebase. For more information, see "[Introduction to dev containers](/codespaces/setting-up-your-project-for-codespaces/introduction-to-dev-containers)." 
+  
+  If you want to add a dev container configuration for another programming language, click the language button to the right.
   `,
   prerequisites: dedent`
     - You should have an existing JavaScript, Node.js, or TypeScript project in a repository on GitHub.com. If you don't have a project, you can try this tutorial with the following example: https://github.com/microsoft/vscode-remote-try-node
-    - Codespaces must be enabled for your organization. For more information, see "[Enabling Codespaces for your organization](/codespaces/managing-codespaces-for-your-organization/enabling-codespaces-for-your-organization)."
+    - GitHub Codespaces must be enabled for your organization. For more information, see "[Enabling GitHub Codespaces for your organization](/codespaces/managing-codespaces-for-your-organization/enabling-codespaces-for-your-organization)."
   `,
   contentBlocks: [
     {
@@ -25,17 +27,17 @@ const article: PlaygroundArticleT = {
       type: 'default',
       title: 'Step 1: Open your project in a codespace',
       content: dedent`
-        1. Under the repository name, use the **Code** drop-down menu, and in the **Codespaces** tab, click **New codespace**.
+        1. Under the repository name, use the **Code** drop-down menu, and in the **Codespaces** tab, click **Create codespace on BRANCH**.
 
             ![New codespace button](/assets/images/help/codespaces/new-codespace-button.png)
 
-           If you don’t see this option, Codespaces isn't available for your project. See [Access to Codespaces](/codespaces/developing-in-codespaces/creating-a-codespace#access-to-codespaces) for more information.
+           If you don’t see this option, GitHub Codespaces isn't available for your project. See [Access to GitHub Codespaces](/codespaces/developing-in-codespaces/creating-a-codespace#access-to-codespaces) for more information.
 
         When you create a codespace, your project is created on a remote VM that is dedicated to you. By default, the container for your codespace has many languages and runtimes including Node.js, JavaScript, Typescript, nvm, npm, and yarn. It also includes a common set of tools like git, wget, rsync, openssh, and nano.
 
         You can customize your codespace by adjusting the amount of vCPUs and RAM, [adding dotfiles to personalize your environment](/codespaces/setting-up-your-codespace/personalizing-codespaces-for-your-account), or by modifying the tools and scripts installed.
 
-        Codespaces uses a file called \`devcontainer.json\` to store configurations. On launch, Codespaces uses the file to install any tools, dependencies, or other set up that might be needed for the project. For more information, see "[Introduction to dev containers](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)."
+        GitHub Codespaces uses a file called \`devcontainer.json\` to configure the development container that you use when you work in a codespace. Each repository can contain one or more  \`devcontainer.json\` files, to give you exactly the development environment you need to work on your code in a codespace. On launch, GitHub Codespaces uses a \`devcontainer.json\` file, and any dependent files that make up the dev container configuration, to install tools and runtimes, and perform other setup tasks that the project requires. For more information, see "[Introduction to dev containers](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)."
       `,
     },
     {
@@ -43,11 +45,11 @@ const article: PlaygroundArticleT = {
         id: '0',
       },
       type: 'default',
-      title: 'Step 2: Add a dev container to your codespace from a template',
+      title: 'Step 2: Add a dev container configuration to your repository from a template',
       content: dedent`
-        The default codespaces container will support running Node.js projects like [vscode-remote-try-node](https://github.com/microsoft/vscode-remote-try-node) out of the box. By setting up a custom container you can customize the tools and scripts that run as part of codespace creation and ensure a fully reproducible environment for all Codespaces users in your repository.
+        The default development container, or "dev container," for GitHub Codespaces supports running Node.js projects like [vscode-remote-try-node](https://github.com/microsoft/vscode-remote-try-node) out of the box. However, we recommend that you configure your own dev container to include all of the tools and scripts your project needs. This will ensure a fully reproducible environment for all GitHub Codespaces users in your repository.
 
-        To set up your project with a custom container, you will need to use a \`devcontainer.json\` file to define the environment. In Codespaces you can add this either from a template or you can create your own. For more information on dev containers, see "[Introduction to dev containers](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)".
+        To set up your repository to use a custom dev container, you will need to create one or more \`devcontainer.json\` files. You can add these either from a template, in Visual Studio Code, or you can write your own. For more information on dev container configurations, see "[Introduction to dev containers](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)".
 
         1. Access the Command Palette (\`Shift + Command + P\` / \`Ctrl + Shift + P\`), then start typing "dev container". Select **Codespaces: Add Development Container Configuration Files...**.
           !["Codespaces: Add Development Container Configuration Files..." in the command palette](/assets/images/help/codespaces/add-prebuilt-container-command.png)
@@ -67,7 +69,7 @@ const article: PlaygroundArticleT = {
       type: 'sub-section',
       title: 'Anatomy of your dev container',
       content: dedent`
-        Adding the Node.js dev container template adds a \`.devcontainer\` folder to the root of your project's repository with the following files:
+        Adding the Node.js dev container template adds a \`.devcontainer\` directory to the root of your project's repository with the following files:
 
         - \`devcontainer.json\`
         - Dockerfile
@@ -93,7 +95,7 @@ const article: PlaygroundArticleT = {
       },
       content: dedent`
         **\`build\`** - The build properties.
-          - **\`dockerfile\`** - In the build object, dockerfile is a reference to the Dockerfile that was also added from the template.
+          - **\`dockerfile\`** - In the \`build\` object, \`dockerfile\` contains the path to the Dockerfile that was also added from the template.
           - **\`args\`**
             - **\`VARIANT\`**: This file only contains one build argument, which is the node variant we want to use that is passed into the Dockerfile.
       `,
@@ -137,7 +139,7 @@ const article: PlaygroundArticleT = {
         highlight: 25,
       },
       content: dedent`
-        **\`postCreateCommand\`** - If you want to run anything after you land in your codespace that’s not defined in the Dockerfile, you can do that here.
+        **\`postCreateCommand\`** - Use this to run commands that aren't defined in the Dockerfile, after your codespace is created.
       `,
     },
     {
@@ -157,7 +159,7 @@ const article: PlaygroundArticleT = {
       type: 'sub-section',
       title: 'Dockerfile',
       content: dedent`
-        You can use the Dockerfile to add additional container layers to specify OS packages, node versions, or global packages we want included in our Dockerfile.
+        You can use the Dockerfile to add additional container layers to specify OS packages, node versions, or global packages we want included in our container.
       `,
     },
     {
@@ -168,7 +170,7 @@ const article: PlaygroundArticleT = {
       type: 'default',
       title: 'Step 3: Modify your devcontainer.json file',
       content: dedent`
-        With your dev container added and a basic understanding of what everything does, you can now make changes to configure it for your environment. In this example, you'll add properties to install npm when your codespace launches and make a list of ports inside the container available locally.
+        With your dev container configuration added and a basic understanding of what everything does, you can now make changes to customize your environment further. In this example, you'll add properties to install npm when your codespace launches and make a list of ports inside the container available locally.
 
         1. In the Explorer, select the \`devcontainer.json\` file from the tree to open it. You might have to expand the \`.devcontainer\` folder to see it.
           ![devcontainer.json file in the Explorer](/assets/images/help/codespaces/devcontainers-options.png)
@@ -178,7 +180,7 @@ const article: PlaygroundArticleT = {
             "postCreateCommand": "npm install",
             "forwardPorts": [4000],
             \`\`\`
-            For more information on \`devcontainer.json\` properties, see the [devcontainer.json reference](https://code.visualstudio.com/docs/remote/devcontainerjson-reference) in the Visual Studio Code docs.
+            For more information about \`devcontainer.json\` properties, see the Visual Studio Code documentation: "[devcontainer.json reference](https://code.visualstudio.com/docs/remote/devcontainerjson-reference)."
 
         1. Access the command palette (\`Shift + Command + P\`/ \`Ctrl + Shift + P\`), then start typing "rebuild". Select **Codespaces: Rebuild Container**. 
             ![Rebuild container option](/assets/images/help/codespaces/codespaces-rebuild.png)

components/playground/content/codespaces/setting-up-your-project-for-codespaces/setting-up-your-project-for-codespaces/python.tsx

@@ -2,8 +2,8 @@ import dedent from 'ts-dedent'
 import { PlaygroundArticleT } from 'components/playground/types'
 
 const article: PlaygroundArticleT = {
-  title: 'Add a dev container to your repository',
+  title: 'Add a dev container configuration to your repository',
-  shortTitle: 'Python Codespaces',
+  shortTitle: 'Python codespaces',
   topics: ['Codespaces', 'Developer', 'Organization', 'Python'],
   type: 'tutorial',
   slug: '/codespaces/setting-up-your-project-for-codespaces/setting-up-your-project-for-codespaces',
@@ -11,11 +11,13 @@ const article: PlaygroundArticleT = {
     '/codespaces/setting-up-your-project-for-codespaces/setting-up-your-python-project-for-codespaces',
   codeLanguageId: 'py',
   intro: dedent`
-    This guide shows you how to add a [dev container](/codespaces/setting-up-your-project-for-codespaces/configuring-codespaces-for-your-project) to define the Codespaces configuration for your **Python** project. For other project languages, click the language button to the right.
+  This guide shows you how to add a dev container configuration to your repository to define the GitHub Codespaces development environment for your **Python** codebase. For more information, see "[Introduction to dev containers](/codespaces/setting-up-your-project-for-codespaces/introduction-to-dev-containers)." 
+  
+  If you want to add a dev container configuration for another programming language, click the language button to the right.
   `,
   prerequisites: dedent`
     - You should have an existing Python project in a repository on GitHub.com. If you don't have a project, you can try this tutorial with the following example: https://github.com/2percentsilk/python-quickstart.
-    - Codespaces must be enabled for your organization. For more information, see "[Enabling Codespaces for your organization](/codespaces/managing-codespaces-for-your-organization/enabling-codespaces-for-your-organization)."
+    - GitHub Codespaces must be enabled for your organization. For more information, see "[Enabling GitHub Codespaces for your organization](/codespaces/managing-codespaces-for-your-organization/enabling-codespaces-for-your-organization)."
   `,
   contentBlocks: [
     {
@@ -25,17 +27,19 @@ const article: PlaygroundArticleT = {
       type: 'default',
       title: 'Step 1: Open your project in a codespace',
       content: dedent`
-        1. Under the repository name, use the **Code** drop-down menu, and in the **Codespaces** tab, click **New codespace**.
+        1. Under the repository name, use the **Code** drop-down menu, and in the **Codespaces** tab, click **Create codespace on BRANCH**.
 
             ![New codespace button](/assets/images/help/codespaces/new-codespace-button.png)
 
-            If you don’t see this option, Codespaces isn't available for your project. See [Access to Codespaces](/codespaces/developing-in-codespaces/creating-a-codespace#access-to-codespaces) for more information.
+            If you don’t see this option, GitHub Codespaces isn't available for your project. See [Access to GitHub Codespaces](/codespaces/developing-in-codespaces/creating-a-codespace#access-to-codespaces) for more information.
 
         When you create a codespace, your project is created on a remote VM that is dedicated to you. By default, the container for your codespace has many languages and runtimes including Python, pip, and Miniconda. It also includes a common set of tools like git, wget, rsync, openssh, and nano.
 
         You can customize your codespace by adjusting the amount of vCPUs and RAM, [adding dotfiles to personalize your environment](/codespaces/setting-up-your-codespace/personalizing-codespaces-for-your-account), or by modifying the tools and scripts installed.
 
-        Codespaces uses a file called \`devcontainer.json\` to store configurations. On launch Codespaces uses the file to install any tools, dependencies, or other set up that might be needed for the project. For more information, see "[Introduction to dev containers](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)."
+        GitHub Codespaces uses a file called \`devcontainer.json\` to configure the development container that you use when you work in a codespace. Each repository can contain one or more  \`devcontainer.json\` files, to give you exactly the development environment you need to work on your code in a codespace. 
+        
+        On launch, GitHub Codespaces uses a \`devcontainer.json\` file, and any dependent files that make up the dev container configuration, to install tools and runtimes, and perform other setup tasks that the project requires. For more information, see "[Introduction to dev containers](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)."
       `,
     },
     {
@@ -43,11 +47,11 @@ const article: PlaygroundArticleT = {
         id: '0',
       },
       type: 'default',
-      title: 'Step 2: Add a dev container to your codespace from a template',
+      title: 'Step 2: Add a dev container configuration to your repository from a template',
       content: dedent`
-        The default codespaces container comes with the latest Python version, package managers (pip, Miniconda), and other common tools preinstalled. However, we recommend that you set up a custom container to define the tools and scripts that your project needs. This will ensure a fully reproducible environment for all Codespaces users in your repository.
+        The default development container, or "dev container," for GitHub Codespaces comes with the latest Python version, package managers (pip, Miniconda), and other common tools preinstalled. However, we recommend that you configure your own dev container to include all of the tools and scripts that your project needs. This will ensure a fully reproducible environment for all GitHub Codespaces users in your repository.
 
-        To set up your project with a custom container, you will need to use a \`devcontainer.json\` file to define the environment. In Codespaces you can add this either from a template or you can create your own. For more information on dev containers, see "[Introduction to dev containers](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)".
+        To set up your repository to use a custom dev container, you will need to create one or more \`devcontainer.json\` files. You can add these either from a template, in Visual Studio Code, or you can write your own. For more information on dev container configurations, see "[Introduction to dev containers](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)".
 
         1. Access the Command Palette (\`Shift + Command + P\` / \`Ctrl + Shift + P\`), then start typing "dev container". Select **Codespaces: Add Development Container Configuration Files...**.
           !["Codespaces: Add Development Container Configuration Files..." in the command palette](/assets/images/help/codespaces/add-prebuilt-container-command.png)
@@ -69,7 +73,7 @@ const article: PlaygroundArticleT = {
       type: 'sub-section',
       title: 'Anatomy of your dev container',
       content: dedent`
-        Adding the Python dev container template adds a .devcontainer folder to the root of your project's repository with the following files:
+        Adding the Python dev container template adds a .devcontainer directory to the root of your project's repository with the following files:
 
         - \`devcontainer.json\`
         - Dockerfile
@@ -95,7 +99,7 @@ const article: PlaygroundArticleT = {
       },
       content: dedent`
         **\`build\`** - The build properties.
-          - **\`dockerfile\`** - In the build object, dockerfile is a reference to the Dockerfile that was also added from the template.
+          - **\`dockerfile\`** - In the \`build\` object, \`dockerfile\` contains the path to the Dockerfile that was also added from the template.
           - **\`args\`**
             - **\`VARIANT\`**: This is the node variant we want to use that is passed into the Dockerfile.
       `,
@@ -139,7 +143,7 @@ const article: PlaygroundArticleT = {
         highlight: 41,
       },
       content: dedent`
-        **\`postCreateCommand\`** - If you want to run anything after you land in your codespace that’s not defined in the Dockerfile, like pip3 install -r requirements, you can do that here.
+        **\`postCreateCommand\`** - Use this to run commands that aren't defined in the Dockerfile, like \`pip3 install -r requirements\`, after your codespace is created.
       `,
     },
     {
@@ -159,7 +163,7 @@ const article: PlaygroundArticleT = {
       type: 'sub-section',
       title: 'Dockerfile',
       content: dedent`
-        You can use the Dockerfile to add additional container layers to specify OS packages, node versions, or global packages we want included in our Dockerfile.
+        You can use the Dockerfile to add additional container layers to specify OS packages, node versions, or global packages we want included in our container.
       `,
     },
     {
@@ -170,7 +174,7 @@ const article: PlaygroundArticleT = {
       type: 'default',
       title: 'Step 3: Modify your devcontainer.json file',
       content: dedent`
-        With your dev container added and a basic understanding of what everything does, you can now make changes to configure it for your environment. In this example, you'll add properties to install extensions and your project dependencies when your codespace launches.
+        With your dev container configuration added and a basic understanding of what everything does, you can now make changes to customize your environment further. In this example, you'll add properties to install extensions and your project dependencies when your codespace launches.
 
         1. In the Explorer, expand the \`.devcontainer\` folder and select the \`devcontainer.json\` file from the tree to open it.
 
@@ -182,7 +186,7 @@ const article: PlaygroundArticleT = {
            "extensions": [
                "ms-python.python",
                "cstrap.flask-snippets",
-               "streetsidesoftware.code-spell-checker",
+               "streetsidesoftware.code-spell-checker"
              ],
            \`\`\`
 
@@ -271,7 +275,7 @@ const article: PlaygroundArticleT = {
       
         // Add the IDs of extensions you want installed when the container is created.
         "extensions": [
-          "ms-python.python",
+          "ms-python.python"
         ],
       
         // Use 'forwardPorts' to make a list of ports inside the container available locally.

content/billing/managing-billing-for-github-codespaces/about-billing-for-codespaces.md

@@ -56,7 +56,9 @@ For information on managing and changing your account's spending limit, see "[Ma
 
 ## Limiting the choice of machine types
 
-The type of machine a user chooses when they create a codespace affects the per-minute charge for that codespace, as shown above. 
+By default the machine type with the lowest valid resources is used when a codespace is created. However, users may be able to choose a machine type with more resources. They can do this either when they create a codespace, or they can change the machine type of an existing codespace. For more information, see "[Creating a codespace"](/codespaces/developing-in-codespaces/creating-a-codespace#creating-a-codespace)" and "[Changing the machine type for your codespace](/codespaces/customizing-your-codespace/changing-the-machine-type-for-your-codespace)."
+
+If a machine type that has more resources is chosen, this will affect the per-minute charge for that codespace, as shown above. 
 
 Organization owners can create a policy to restrict the machine types that are available to users. For more information, see "[Restricting access to machine types](/codespaces/managing-codespaces-for-your-organization/restricting-access-to-machine-types)."
 

content/codespaces/codespaces-reference/security-in-codespaces.md

@@ -99,7 +99,9 @@ There are some additional good practices and risks that you should be aware of w
 
 #### Understanding a repository's devcontainer.json file
 
-When creating a codespace, the [devcontainer.json](https://code.visualstudio.com/docs/remote/devcontainerjson-reference) is parsed and applied from the source repo, if one exists.  The devcontainer contains powerful features, such as installing third-party extensions and running arbitrary code through a supplied `postCreateCommand`.
+When you create a codespace, if a `devcontainer.json` file is found for your repository, it is parsed and used to configure your codespace. The `devcontainer.json` file can contain powerful features, such as installing third-party extensions and running arbitrary code supplied in a `postCreateCommand`.
+
+For more information, see "[Introduction to dev containers](/codespaces/setting-up-your-project-for-codespaces/introduction-to-dev-containers)."
 
 #### Granting access through features
 

content/codespaces/codespaces-reference/using-github-copilot-in-codespaces.md

@@ -19,5 +19,5 @@ redirect_from:
 
 [{% data variables.product.prodname_copilot %}](https://copilot.github.com/), an AI pair programmer, can be used in any codespace. To start using {% data variables.product.prodname_copilot_short %} in {% data variables.product.prodname_codespaces %}, install the [{% data variables.product.prodname_copilot_short %} extension from the {% data variables.product.prodname_vscode %} marketplace](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot).
 
-To include {% data variables.product.prodname_copilot_short %}, or other extensions, in all of your codespaces, enable Settings Sync. For more information, see "[Personalizing {% data variables.product.prodname_codespaces %} for your account](/codespaces/customizing-your-codespace/personalizing-codespaces-for-your-account#settings-sync)." Additionally, to include {% data variables.product.prodname_copilot_short %} in a given project for all users, you can specify `GitHub.copilot` as an extension in your `devcontainer.json` file. For information about configuring a `devcontainer.json` file, see "[Configuring {% data variables.product.prodname_codespaces %} for your project](/codespaces/customizing-your-codespace/configuring-codespaces-for-your-project#creating-a-custom-codespace-configuration)."
+To include {% data variables.product.prodname_copilot_short %}, or other extensions, in all of your codespaces, enable Settings Sync. For more information, see "[Personalizing {% data variables.product.prodname_codespaces %} for your account](/codespaces/customizing-your-codespace/personalizing-codespaces-for-your-account#settings-sync)." Additionally, to include {% data variables.product.prodname_copilot_short %} in a given project for all users, you can specify `GitHub.copilot` as an extension in your `devcontainer.json` file. For information about configuring a `devcontainer.json` file, see "[Introduction to dev containers](/codespaces/customizing-your-codespace/configuring-codespaces-for-your-project#creating-a-custom-dev-container-configuration)."
 

content/codespaces/customizing-your-codespace/changing-the-machine-type-for-your-codespace.md

@@ -20,9 +20,7 @@ topics:
 
 {% endnote %}
 
-{% data reusables.codespaces.codespaces-machine-types %}
+{% data reusables.codespaces.codespaces-machine-types %} You can choose an alternative machine type either when you create a codespace or at any time after you've created a codespace. 
-
-You can choose a machine type either when you create a codespace or you can change the machine type at any time after you've created a codespace. 
 
 For information on choosing a machine type when you create a codespace, see "[Creating a codespace](/codespaces/developing-in-codespaces/creating-a-codespace#creating-a-codespace)." For information on changing the machine type within {% data variables.product.prodname_vscode %}, see "[Using {% data variables.product.prodname_codespaces %} in {% data variables.product.prodname_vscode %}](/codespaces/developing-in-codespaces/using-codespaces-in-visual-studio-code#changing-the-machine-type-in-visual-studio-code)."
 
@@ -43,7 +41,11 @@ For information on choosing a machine type when you create a codespace, see "[Cr
 
    ![Dialog box showing available machine types to choose](/assets/images/help/codespaces/change-machine-type-choice.png)
 
-   {% data reusables.codespaces.codespaces-machine-type-availability %}
+   {% note %}
+
+   **Note**: {% data reusables.codespaces.codespaces-machine-type-availability %}
+
+   {% endnote %}
 
 2. Click **Update codespace**. 
 

content/codespaces/customizing-your-codespace/personalizing-codespaces-for-your-account.md

@@ -64,7 +64,7 @@ Any changes to your selected dotfiles repository will apply only to each new cod
 
 {% note %}
 
-**Note:** Currently, {% data variables.product.prodname_codespaces %} does not support personalizing the _User_ settings for the {% data variables.product.prodname_vscode %} editor with your `dotfiles` repository. You can set default _Workspace_ and _Remote [Codespaces]_ settings for a specific project in the project's repository. For more information, see "[Configuring {% data variables.product.prodname_codespaces %} for your project](/github/developing-online-with-codespaces/configuring-codespaces-for-your-project#creating-a-custom-codespace-configuration)."
+**Note:** Currently, {% data variables.product.prodname_codespaces %} does not support personalizing the _User_ settings for the {% data variables.product.prodname_vscode %} editor with your `dotfiles` repository. You can set default _Workspace_ and _Remote [Codespaces]_ settings for a specific project in the project's repository. For more information, see "[Introduction to dev containers](/github/developing-online-with-codespaces/configuring-codespaces-for-your-project#creating-a-custom-dev-container-configuration)."
 
 {% endnote %}
 

content/codespaces/developing-in-codespaces/creating-a-codespace.md

@@ -72,19 +72,53 @@ If you would like to create a codespace for a repository owned by your personal
 {% webui %}
 
 {% data reusables.repositories.navigate-to-repo %}
-2. Under the repository name, use the "Branch" drop-down menu, and select the branch you want to create a codespace for.
+1. Under the repository name, use the "Branch" drop-down menu, and select the branch you want to create a codespace for.
 
    ![Branch drop-down menu](/assets/images/help/codespaces/branch-drop-down.png)
 
-3. Under the repository name, use the **{% octicon "code" aria-label="The code icon" %} Code** drop-down menu, and in the **Codespaces** tab, click {% octicon "plus" aria-label="The plus icon" %} **New codespace**.
+1. Click the **{% octicon "code" aria-label="The code icon" %} Code** button, then click the **Codespaces** tab.
 
    ![New codespace button](/assets/images/help/codespaces/new-codespace-button.png)
 
-   If you are a member of an organization and are creating a codespace on a repository owned by that organization, you can select the option of a different machine type. From the dialog box, choose a machine type and then click **Create codespace**.
+1. Create your codespace, either using the default options, or after configuring advanced options:
  
-   ![Machine type choice](/assets/images/help/codespaces/choose-custom-machine-type.png)
+   * **Use the default options**
 
-   {% data reusables.codespaces.codespaces-machine-type-availability %}
+      To create a codespace using the default options, click **Create codespace on BRANCH**.
+
+      Optionally, before clicking **Create codespace on BRANCH**, you can click the down arrow at the side of the button to see what machine type will be used for your codespace.
+
+      ![View the default machine type](/assets/images/help/codespaces/default-machine-type.png)
+
+      {% note %}
+
+      **Note**: The machine type with the lowest resources that are valid for the repository is selected by default.
+
+      {% endnote %}
+
+   * **Configure options**
+
+      To configure advanced options for your codespace, such as a different machine type or a particular `devcontainer.json` file:
+
+      1. Click the down arrow at the side of the **Create codespace on BRANCH** button, then click **Configure and create codespace**.
+      1. Click the **Configure and create codespace** button.
+      1. On the options page for your codespace, choose your preferred options from the drop-down menus.
+
+         ![The codespace options page](/assets/images/help/codespaces/advanced-options.png)
+
+         {% note %}
+      
+         **Notes**
+      
+         * You can bookmark the options page to give you a quick way to create a codespace for this repository and branch.
+         * The [https://github.com/codespaces/new](https://github.com/codespaces/new) page provides a quick way to create a codespace for any repository and branch.
+         * For more information about the `devcontainer.json` file, see "[Introduction to dev containers](/codespaces/setting-up-your-project-for-codespaces/introduction-to-dev-containers#devcontainerjson)."
+         * For more information about machine types, see "[Changing the machine type for your codespace](/codespaces/customizing-your-codespace/changing-the-machine-type-for-your-codespace#about-machine-types)."
+         * {% data reusables.codespaces.codespaces-machine-type-availability %}
+      
+         {% endnote %}
+
+      1. Click **Start session**.
 
 {% endwebui %}
    
@@ -106,6 +140,12 @@ gh codespace create
 
 You are prompted to choose a repository, a branch, and a machine type (if more than one is available).
 
+{% note %}
+
+**Note**: Currently, {% data variables.product.prodname_cli %} doesn't allow you to choose a dev container configuration when you create a codespace. If you want to choose a specific dev container configuration, use the {% data variables.product.prodname_dotcom %} web interface to create your codespace. For more information, click the "Web browser" tab at the top of this page.
+
+{% endnote %}
+
 Alternatively, you can use flags to specify some or all of the options:
 
 ```shell

content/codespaces/developing-in-codespaces/deleting-a-codespace.md

@@ -26,6 +26,7 @@ shortTitle: Delete a codespace
 
 {% endnote %}
 
+## Deleting a codespace
 
 {% webui %}
 
@@ -54,11 +55,48 @@ To delete a codespace use the `gh codespace delete` subcommand and then choose a
 gh codespace delete
 ```
 
-If you have unsaved changes, you'll be prompted to confirm deletion. You can use the `-f` flag to force deletion, avoiding this prompt.
+If you have unsaved changes, you'll be prompted to confirm deletion. You can use the `--force` flag to force deletion, avoiding this prompt.
 
 For more information about this command, see [the {% data variables.product.prodname_cli %} manual](https://cli.github.com/manual/gh_codespace_delete).
 
 {% endcli %}
 
+## Bulk deleting codespaces
+
+{% webui %}
+
+You can use {% data variables.product.prodname_cli %} to delete several or all of your codespaces with a single command. For more information, click the **{% data variables.product.prodname_cli %}** tab near the top of this page.
+
+{% endwebui %}
+
+{% vscode %}
+
+You can use {% data variables.product.prodname_cli %} to delete several or all of your codespaces with a single command. For more information, click the **{% data variables.product.prodname_cli %}** tab near the top of this page.
+
+{% endvscode %}
+
+
+{% cli %}
+
+You can delete several or all of your codespaces with a single command, using `gh codespace delete` followed by one of these flags:
+
+`--all` - Delete all of your codespaces.
+
+`--repo REPOSITORY` - Delete all of your codespaces for this repository. Or use together with the `--days` flag to filter by age of the codespace.
+
+`--days NUMBER` - Delete all of your codespaces that are older than the specified number of days. Can be used together with the `--repo` flag.
+
+By default you are prompted to confirm deletion of any codespaces that contain unsaved changes. You can use the `--force` flag to skip this confirmation. 
+
+### Example
+
+Delete all of the codespaces for the `octo-org/octo-repo` repository that you created more than 7 days ago.
+
+```
+gh cs delete --repo octo-org/octo-repo --days 7
+```
+
+{% endcli %}
+
 ## Further reading
 - [Codespaces lifecycle](/codespaces/developing-in-codespaces/codespaces-lifecycle)

content/codespaces/developing-in-codespaces/using-codespaces-for-pull-requests.md

@@ -27,7 +27,7 @@ topics:
 
 2. In the list of pull requests, click the pull request you'd like to open in {% data variables.product.prodname_codespaces %}.
 3. On the right-hand side of your screen, click **{% octicon "code" aria-label="The code icon" %} Code**. 
-4. From the {% data variables.product.prodname_codespaces %} tab, click **New codespace**.
+4. In the {% data variables.product.prodname_codespaces %} tab, click **Create codespace on BRANCH**.
   ![Option to open PR in a codespace](/assets/images/help/codespaces/open-with-codespaces-pr.png)
 
 ## Reviewing a pull request in {% data variables.product.prodname_codespaces %}

content/codespaces/developing-in-codespaces/using-codespaces-in-visual-studio-code.md

@@ -75,9 +75,7 @@ Use the {% data variables.product.prodname_vs %} Marketplace to install the [{%
 
 ## Changing the machine type in {% data variables.product.prodname_vscode %}
 
-{% data reusables.codespaces.codespaces-machine-types %}
+{% data reusables.codespaces.codespaces-machine-types %} You can change the machine type of your codespace at any time.
-
-You can change the machine type of your codespace at any time.
 
 1. In {% data variables.product.prodname_vscode %}, open the Command Palette (`shift command P` / `shift control P`).
 1. Search for and select "Codespaces: Change Machine Type."
@@ -90,7 +88,11 @@ You can change the machine type of your codespace at any time.
 
 1. Choose the machine type you want to use. 
 
-   {% data reusables.codespaces.codespaces-machine-type-availability %}
+   {% note %}
+
+   **Note**: {% data reusables.codespaces.codespaces-machine-type-availability %}
+
+   {% endnote %}
 
 1. If the codespace is currently running, a message is displayed asking if you would like to restart and reconnect to your codespace now.
 
@@ -100,7 +102,6 @@ You can change the machine type of your codespace at any time.
 
 ## Deleting a codespace in {% data variables.product.prodname_vscode %}
 
-{% data reusables.codespaces.click-remote-explorer-icon-vscode %}
 {% data reusables.codespaces.deleting-a-codespace-in-vscode %}
 
 ## Switching to the Insiders build of {% data variables.product.prodname_vscode %}

content/codespaces/getting-started/deep-dive.md

@@ -24,7 +24,7 @@ There are a number of entry points to create a codespace.
   
 Your codespace can be ephemeral if you need to test something or you can return to the same codespace to work on long-running feature work. For more information, see "[Creating a codespace](/codespaces/developing-in-codespaces/creating-a-codespace)."
 
-Once you've selected the option to create a new codespace, and chosen a machine type for your codespace, some steps happen in the background before the codespace is available to you.
+Once you've selected the option to create a new codespace, and optionally selected from the various configuration options for your codespace, some steps happen in the background before the codespace is available to you.
 
 ![Open with Codespaces button](/assets/images/help/codespaces/new-codespace-button.png)
 

content/codespaces/getting-started/quickstart.md

@@ -25,9 +25,9 @@ For more information on exactly how {% data variables.product.prodname_codespace
 
 1. Navigate to the [template repository](https://github.com/2percentsilk/haikus-for-codespaces) and select **Use this template**. 
 
-2. Name your repository, select your preferred privacy setting, and click **Create repository from this template**.
+2. Name your repository, select your preferred privacy setting, and click **Create repository from template**.
 
-3. Navigate to the main page of the newly created repository. Under the repository name, use the **{% octicon "code" aria-label="The code icon" %} Code** drop-down menu, and in the **Codespaces** tab, click {% octicon "plus" aria-label="The plus icon" %} **New codespace**.
+3. Navigate to the main page of the newly created repository. Under the repository name, use the **{% octicon "code" aria-label="The code icon" %} Code** drop-down menu, and in the **Codespaces** tab, click **Create codespace on main**.
 
   ![New codespace button](/assets/images/help/codespaces/new-codespace-button.png)
 

content/codespaces/overview.md

@@ -30,9 +30,9 @@ A codespace is a development environment that's hosted in the cloud. You can cus
 
 You can create a codespace from any branch or commit in your repository and begin developing using cloud-based compute resources. {% data reusables.codespaces.links-to-get-started %}
 
-To customize the runtimes and tools in your codespace, you can create a custom configuration to define an environment (or _dev container_) that is specific for your repository. Using a dev container allows you to specify a Docker environment for development with a well-defined tool and runtime stack that can reference an image, Dockerfile, or docker-compose. This means that anyone using the repository will have the same tools available to them when they create a codespace.
+To customize the runtimes and tools in your codespace, you can create one or more dev container configurations for your repository. Adding dev container configurations to your repository allows you to define a choice of different development environments that are appropriate for the work people will do in your repository. 
 
-If you don't do any custom configuration, {% data variables.product.prodname_codespaces %} will clone your repository into an environment with the default codespace image that includes many tools, languages, and runtime environments. For more information, see "[Introduction to dev containers](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)".
+If you don't add a dev container configuration, {% data variables.product.prodname_codespaces %} will clone your repository into an environment with the default codespace image that includes many tools, languages, and runtime environments. For more information, see "[Introduction to dev containers](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)".
 
 You can also personalize aspects of your codespace environment by using a public [dotfiles](https://dotfiles.github.io/tutorials/) repository and [Settings Sync](https://code.visualstudio.com/docs/editor/settings-sync). Personalization can include shell preferences, additional tools, editor settings, and VS Code extensions. For more information, see "[Customizing your codespace](/codespaces/customizing-your-codespace)".
 

content/codespaces/prebuilding-your-codespaces/about-codespaces-prebuilds.md

@@ -18,10 +18,16 @@ Prebuilding your codespaces allows you to be more productive and access your cod
 
 By default, whenever you push changes to your repository, {% data variables.product.prodname_codespaces %} uses {% data variables.product.prodname_actions %} to automatically update your prebuilds.
 
-When prebuilds are available for a particular branch of a repository, and for your region, you'll see the "{% octicon "zap" aria-label="The zap icon" %} Prebuild ready" label in the machine type dialog box that's displayed when you create a codespace and multiple machine types are available.
+When prebuilds are available for a particular branch of a repository, and for your region, you'll see the "{% octicon "zap" aria-label="The zap icon" %} Prebuild ready" label in the list of machine type options when you create a codespace. For more information, see "[Creating a codespace](/codespaces/developing-in-codespaces/creating-a-codespace#creating-a-codespace)."
 
 ![The dialog box for choosing a machine type](/assets/images/help/codespaces/choose-custom-machine-type.png)
 
+{% note %}
+
+{% data reusables.codespaces.prebuilds-not-available %}
+
+{% endnote %}
+
 ## About billing for {% data variables.product.prodname_codespaces %} prebuilds
 
 {% data reusables.codespaces.billing-for-prebuilds %} For details of {% data variables.product.prodname_codespaces %} storage pricing, see "[About billing for {% data variables.product.prodname_codespaces %}](/billing/managing-billing-for-github-codespaces/about-billing-for-codespaces)." 
@@ -30,7 +36,7 @@ Use of codespaces created using prebuilds is charged at the same rate as regular
 
 ## About pushing changes to prebuild-enabled branches
 
-By default, each push to a branch that has a prebuild configuration results in a {% data variables.product.prodname_dotcom %}-managed Actions workflow run to update the prebuild template. The prebuild workflow has a concurrency limit of one workflow run at a time for a given prebuild configuration, unless changes were made that affect the dev container configuration for the associated repository. For more information, see "[Introduction to dev containers](/codespaces/setting-up-your-project-for-codespaces/configuring-codespaces-for-your-project)." If a run is already in progress, the workflow run that was queued most recently queued will run next, after the current run completes. 
+By default, each push to a branch that has a prebuild configuration results in a {% data variables.product.prodname_dotcom %}-managed Actions workflow run to update the prebuild template. The prebuild workflow has a concurrency limit of one workflow run at a time for a given prebuild configuration, unless changes were made that affect the dev container configuration for the associated repository. For more information, see "[Introduction to dev containers](/codespaces/setting-up-your-project-for-codespaces/introduction-to-dev-containers)." If a run is already in progress, the workflow run that was queued most recently queued will run next, after the current run completes. 
 
 With the prebuild template set to be updated on each push, it means that if there are very frequent pushes to your repository, prebuild template updates will occur at least as often as it takes to run the prebuild workflow. That is, if your workflow run typically takes one hour to complete, prebuilds will be created for your repository roughly hourly, if the run succeeds, or more often if there were pushes that change the dev container configuration on the branch.
 

content/codespaces/prebuilding-your-codespaces/configuring-prebuilds.md

@@ -17,10 +17,12 @@ permissions: People with admin access to a repository can configure prebuilds fo
 
 You can set up a prebuild configuration for a specific branch of your repository.
 
-Any branch created from a prebuild-enabled base branch will typically also get assigned a prebuild during codespace creation. This is true if the dev container on the branch is the same as on the base branch. This is because the majority of the prebuild configuration for branches with the same dev container configuration are identical, so developers can benefit from faster codespace creation times on those branches also. For more information, see "[Introduction to dev containers](/codespaces/setting-up-your-project-for-codespaces/configuring-codespaces-for-your-project)."
+Any branch created from a prebuild-enabled base branch will typically also get assigned a prebuild during codespace creation. This is true if the dev container on the branch is the same as on the base branch. This is because the majority of the prebuild configuration for branches with the same dev container configuration are identical, so developers can benefit from faster codespace creation times on those branches also. For more information, see "[Introduction to dev containers](/codespaces/setting-up-your-project-for-codespaces/introduction-to-dev-containers)."
 
 Typically, when you configure prebuilds for a branch, prebuilds will be available for {% data variables.product.prodname_codespaces %} machine types for that branch. However, if your repository is greater than 32 GB, prebuilds won't be available for 2-core and 4-core machine types, since the storage these provide is limited to 32 GB.
 
+{% data reusables.codespaces.prebuilds-not-available %}
+
 ## Prerequisites 
 
 Before you can configure prebuilds for your project the following must be true: 

content/codespaces/prebuilding-your-codespaces/testing-dev-container-changes.md

@@ -18,7 +18,7 @@ permissions: People with write permissions to a repository can create or edit th
 
 Any changes you make to the dev container configuration for a prebuild-enabled branch will result in an update to the codespace configuration and the associated prebuild template. It’s therefore important to test such changes in a codespace from a test branch before committing your changes to a branch of your repository that's actively used. This will ensure you’re not introducing breaking changes for your team.
 
-For more information, see "[Introduction to dev containers](/codespaces/setting-up-your-project-for-codespaces/configuring-codespaces-for-your-project)."
+For more information, see "[Introduction to dev containers](/codespaces/setting-up-your-project-for-codespaces/introduction-to-dev-containers)."
 
 ## Testing changes to the dev container configuration
 
@@ -26,7 +26,7 @@ For more information, see "[Introduction to dev containers](/codespaces/setting-
 ](/codespaces/developing-in-codespaces/creating-a-codespace#creating-a-codespace)."
 1. In the codespace, check out a test branch. For more information, see "[Using source control in your codespace](/codespaces/developing-in-codespaces/using-source-control-in-your-codespace#creating-or-switching-branches)."
 1. Make the required changes to the dev container configuration.
-1. Apply the changes by rebuilding the container. For more information, see "[Introduction to dev containers](/codespaces/setting-up-your-project-for-codespaces/configuring-codespaces-for-your-project#applying-changes-to-your-configuration)."
+1. Apply the changes by rebuilding the container. For more information, see "[Introduction to dev containers](/codespaces/setting-up-your-project-for-codespaces/introduction-to-dev-containers#applying-changes-to-your-configuration)."
 1. After everything looks good, we also recommend creating a new codespace from your test branch to ensure everything is working. You can then commit your changes to your repository's default branch, or an active feature branch, triggering an update of the prebuild template for that branch.
 
    {% note %}

content/codespaces/setting-up-your-project-for-codespaces/configuring-codespaces-for-your-project.md

@@ -1,177 +0,0 @@
----
-title: Introduction to dev containers
-intro: 'You can use a `devcontainer.json` file to define a {% data variables.product.prodname_codespaces %} environment for your repository.'
-allowTitleToDifferFromFilename: true
-permissions: People with write permissions to a repository can create or edit the codespace configuration.
-redirect_from:
-  - /github/developing-online-with-github-codespaces/configuring-github-codespaces-for-your-project
-  - /codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project
-  - /github/developing-online-with-codespaces/configuring-codespaces-for-your-project
-  - /codespaces/customizing-your-codespace/configuring-codespaces-for-your-project
-versions:
-  fpt: '*'
-  ghec: '*'
-type: how_to
-topics:
-  - Codespaces
-  - Set up
-  - Fundamentals
-product: '{% data reusables.gated-features.codespaces %}'
----
-
- 
-
-## About dev containers
-
-A development container, or dev container, is the environment that {% data variables.product.prodname_codespaces %} uses to provide the tools and runtimes that your project needs for development. If your project does not already have a dev container defined, {% data variables.product.prodname_codespaces %} will use the default configuration, which contains many of the common tools that your team might need for development with your project. For more information, see "[Using the default configuration](#using-the-default-configuration)."
-
-If you want all users of your project to have a consistent environment that is tailored to your project, you can add a dev container to your repository. You can use a predefined configuration to select a common configuration for various project types with the option to further customize your project or you can create your own custom configuration. For more information, see "[Using a predefined container configuration](#using-a-predefined-container-configuration)" and "[Creating a custom codespace configuration](#creating-a-custom-codespace-configuration)." The option you choose is dependent on the tools, runtimes, dependencies, and workflows that a user might need to be successful with your project.
-
-{% data variables.product.prodname_codespaces %} allows for customization on a per-project and per-branch basis with a `devcontainer.json` file. This configuration file determines the environment of every new codespace anyone creates for your repository by defining a development container that can include frameworks, tools, extensions, and port forwarding. A Dockerfile can also be used alongside the `devcontainer.json` file in the `.devcontainer` folder to define everything required to create a container image.
-
-### devcontainer.json
-
-{% data reusables.codespaces.devcontainer-location %}
-
-You can use your `devcontainer.json` to set default settings for the entire codespace environment, including the editor, but you can also set editor-specific settings for individual [workspaces](https://code.visualstudio.com/docs/editor/workspaces) in a codespace in a file named `.vscode/settings.json`.
-
-For information about the settings and properties that you can set in a `devcontainer.json`, see [devcontainer.json reference](https://aka.ms/vscode-remote/devcontainer.json) in the {% data variables.product.prodname_vscode %} documentation.
-
-### Dockerfile
-
-A Dockerfile also lives in the `.devcontainer` folder. 
-
-You can add a Dockerfile to your project to define a container image and install software. In the Dockerfile, you can use `FROM` to specify the container image.
-
-```Dockerfile
-FROM mcr.microsoft.com/vscode/devcontainers/javascript-node:0-14
-
-# ** [Optional] Uncomment this section to install additional packages. **
-# USER root
-#
-# RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
-#     && apt-get -y install --no-install-recommends <your-package-list-here>
-#
-# USER codespace
-```
-
-You can use the `RUN` instruction to install any software and `&&` to join commands.
-
-Reference your Dockerfile in your `devcontainer.json` file by using the `dockerfile` property.
-
-```json
-{
-  ...
-  "build": { "dockerfile": "Dockerfile" },
-  ...
-}
-```
-
-For more information on using a Dockerfile in a dev container, see [Create a development container](https://code.visualstudio.com/docs/remote/create-dev-container#_dockerfile) in the {% data variables.product.prodname_vscode %} documentation. 
-
-## Using the default configuration
-
-If you don't define a configuration in your repository, {% data variables.product.prodname_dotcom %} creates a codespace with a base Linux image. The base Linux image includes languages and runtimes like Python, Node.js, JavaScript, TypeScript, C++, Java, .NET, PHP, PowerShell, Go, Ruby, and Rust. It also includes other developer tools and utilities like git, GitHub CLI, yarn, openssh, and vim. To see all the languages, runtimes, and tools that are included use the `devcontainer-info content-url` command inside your codespace terminal and follow the url that the command outputs.
-
-Alternatively, for more information about everything that is included in the base Linux image, see the latest file in the [`microsoft/vscode-dev-containers`](https://github.com/microsoft/vscode-dev-containers/tree/main/containers/codespaces-linux) repository. 
-
-The default configuration is a good option if you're working on a small project that uses the languages and tools that {% data variables.product.prodname_codespaces %} provides.
-
-
-## Using a predefined container configuration
-
-Predefined container definitions include a common configuration for a particular project type, and can help you quickly get started with a configuration that already has the appropriate container options, {% data variables.product.prodname_vscode %} settings, and {% data variables.product.prodname_vscode %} extensions that should be installed.
-
-Using a predefined configuration is a great idea if you need some additional extensibility. You can also start with a predefined configuration and amend it as needed for your project's setup.
-
-{% data reusables.codespaces.command-palette-container %}
-1. Click the definition you want to use.
-  ![List of predefined container definitions](/assets/images/help/codespaces/predefined-container-definitions-list.png)
-1. Follow the prompts to customize your definition. For more information on the options to customize your definition, see "[Adding additional features to your `devcontainer.json` file](#adding-additional-features-to-your-devcontainerjson-file)."
-1. Click **OK**.
-  ![OK button](/assets/images/help/codespaces/prebuilt-container-ok-button.png)
-1. To apply the changes, in the bottom right corner of the screen, click **Rebuild now**. For more information about rebuilding your container, see "[Applying changes to your configuration](#applying-changes-to-your-configuration)."
-  !["Codespaces: Rebuild Container" in the {% data variables.product.prodname_vscode_command_palette %}](/assets/images/help/codespaces/rebuild-prompt.png)
-
-### Adding additional features to your `devcontainer.json` file
-
-{% note %}
-
-**Note:** This feature is in beta and subject to change.
-
-{% endnote %}
-
-You can add features to your predefined container configuration to customize which tools are available and extend the functionality of your workspace without creating a custom codespace configuration. For example, you could use a predefined container configuration and add the {% data variables.product.prodname_cli %} as well. You can make these additional features available for your project by adding the features to your `devcontainer.json` file when you set up your container configuration.
-
-You can add some of the most common features by selecting them when configuring your predefined container. For more information on the available features, see the [script library](https://github.com/microsoft/vscode-dev-containers/tree/main/script-library#scripts) in the `vscode-dev-containers` repository.
-
-![The select additional features menu during container configuration.](/assets/images/help/codespaces/select-additional-features.png)
-
-You can also add or remove features outside of the **Add Development Container Configuration Files** workflow. 
-1. Access the Command Palette (`Shift + Command + P` / `Ctrl + Shift + P`), then start typing "configure". Select **Codespaces: Configure Devcontainer Features**.
-  ![The Configure Devcontainer Features command in the command palette](/assets/images/help/codespaces/codespaces-configure-features.png)
-2. Update your feature selections, then click **OK**.
-  ![The select additional features menu during container configuration.](/assets/images/help/codespaces/select-additional-features.png)
-1. To apply the changes, in the bottom right corner of the screen, click **Rebuild now**. For more information about rebuilding your container, see "[Applying changes to your configuration](#applying-changes-to-your-configuration)."
-  !["Codespaces: Rebuild Container" in the command palette](/assets/images/help/codespaces/rebuild-prompt.png)
-
-
-## Creating a custom codespace configuration
-
-If none of the predefined configurations meet your needs, you can create a custom configuration by adding a `devcontainer.json` file. {% data reusables.codespaces.devcontainer-location %}
-
-In the file, you can use [supported configuration keys](https://code.visualstudio.com/docs/remote/devcontainerjson-reference) to specify aspects of the codespace's environment, like which {% data variables.product.prodname_vscode %} extensions will be installed.
-
-{% data reusables.codespaces.vscode-settings-order %}
-
-You can define default editor settings for {% data variables.product.prodname_vscode %} in two places.
-
-* Editor settings defined in `.vscode/settings.json` are applied as _Workspace_-scoped settings in the codespace.
-* Editor settings defined in the `settings` key in `devcontainer.json` are applied as _Remote [Codespaces]_-scoped settings in the codespace.
-
-After updating the `devcontainer.json` file, you can rebuild the container for your codespace to apply the changes. For more information, see "[Applying changes to your configuration](#applying-changes-to-your-configuration)."
-
-<!--
-## Supported codespace configuration keys
-
-You can use configuration keys supported by {% data variables.product.prodname_codespaces %} in `devcontainer.json`.
-
-### General settings
-
-- `name`
-- `settings`
-- `extensions`
-- `forwardPorts`
-- `postCreateCommand`
-
-### Docker, Dockerfile, or image settings
-
-- `image`
-- `dockerFile`
-- `context`
-- `containerEnv`
-- `remoteEnv`
-- `containerUser`
-- `remoteUser`
-- `mounts`
-- `runArgs`
-- `overrideCommand`
-- `dockerComposeFile`
-
-For more information about the available settings for `devcontainer.json`, see [devcontainer.json reference](https://aka.ms/vscode-remote/devcontainer.json) in the {% data variables.product.prodname_vscode %} documentation.
--->
-
-## Applying changes to your configuration
-
-{% data reusables.codespaces.apply-devcontainer-changes %}
-
-{% data reusables.codespaces.rebuild-command %}
-1. {% data reusables.codespaces.recovery-mode %} Fix the errors in the configuration.
-  ![Error message about recovery mode](/assets/images/help/codespaces/recovery-mode-error-message.png)
-   - To diagnose the error by reviewing the creation logs, click **View creation log**.
-   - To fix the errors identified in the logs, update your `devcontainer.json` file.
-   - To apply the changes, rebuild your container. 
-
-## Further reading
-
-- "[Prebuilding your codespaces](/codespaces/prebuilding-your-codespaces)"

content/codespaces/setting-up-your-project-for-codespaces/index.md

@@ -9,7 +9,7 @@ versions:
 redirect_from:
   - /codespaces/getting-started-with-codespaces
 children:
-  - /configuring-codespaces-for-your-project
+  - /introduction-to-dev-containers
   - /setting-up-your-project-for-codespaces
   - /setting-up-your-nodejs-project-for-codespaces
   - /setting-up-your-dotnet-project-for-codespaces

content/codespaces/setting-up-your-project-for-codespaces/introduction-to-dev-containers.md

@@ -0,0 +1,229 @@
+---
+title: Introduction to dev containers
+intro: When you work in a codespace, the environment you are working in is created using a development container, or dev container, hosted on a virtual machine.
+permissions: People with write permissions to a repository can create or edit the codespace configuration.
+redirect_from:
+  - /github/developing-online-with-github-codespaces/configuring-github-codespaces-for-your-project
+  - /codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project
+  - /github/developing-online-with-codespaces/configuring-codespaces-for-your-project
+  - /codespaces/customizing-your-codespace/configuring-codespaces-for-your-project
+  - /codespaces/setting-up-your-project-for-codespaces/configuring-codespaces-for-your-project
+versions:
+  fpt: '*'
+  ghec: '*'
+type: how_to
+topics:
+  - Codespaces
+  - Set up
+  - Fundamentals
+product: '{% data reusables.gated-features.codespaces %}'
+---
+
+## About dev containers
+
+Development containers, or dev containers, are Docker containers that are specifically configured to provide a full-featured development environment. Whenever you work in a codespace, you are using a dev container on a virtual machine.
+
+You can configure the dev container for a repository so that codespaces created for that repository give you a tailored development environment, complete with all the tools and runtimes you need to work on a specific project. If you don't define a configuration in the repository then {% data variables.product.prodname_github_codespaces %} uses a default configuration, which contains many of the common tools that your team might need for development with your project. For more information, see "[Using the default dev container configuration](#using-the-default-dev-container-configuration)."
+
+The configuration files for a dev container are contained in a `.devcontainer` directory in your repository. You can use {% data variables.product.prodname_vscode %} to add configuration files for you. You can choose from a selection of predefined configurations for various project types. You can use these without further configuration, or you can edit the configurations to refine the development environment they produce. For more information, see "[Using a predefined dev container configuration](#using-a-predefined-dev-container-configuration)."
+
+Alternatively, you can add your own custom configuration files. For more information, see "[Creating a custom dev container configuration](#creating-a-custom-dev-container-configuration)."
+
+You can define a single dev container configuration for a repository, different configurations for different branches, or multiple configurations. When multiple configurations are available, users can choose their preferred configuration when they create a codespace. This is particularly useful for large repositories that contain source code in different programming languages or for different projects. You can create a choice of configurations that allow different teams to work in a codespace that's set up appropriately for the work they are doing.
+
+### devcontainer.json
+
+The primary file in a dev container configuration is the `devcontainer.json` file. You can use this file to determine the environment of codespaces created for your repository. The contents of this file define a dev container that can include frameworks, tools, extensions, and port forwarding. The `devcontainer.json` file usually contains a reference to a Dockerfile, which is typically located alongside the `devcontainer.json` file.
+
+If you don't add a `devcontainer.json` file to your repository. the default dev container configuration is used. For more information, see "[Using the default dev container configuration](#using-the-default-dev-container-configuration)."
+
+The `devcontainer.json` file is usually located in the `.devcontainer` directory of your repository. Alternatively, you can locate it directly in the root of the repository, in which case the file name must begin with a period: `.devcontainer.json`. 
+
+If you want to have a choice of dev container configurations in your repository, any alternatives to the  `.devcontainer/devcontainer.json` (or `.devcontainer.json`) file must be located in their own subdirectory at the path `.devcontainer/SUBDIRECTORY/devcontainer.json`. For example, you could have a choice of two configurations: 
+* `.devcontainer/database-dev/devcontainer.json` 
+* `.devcontainer/gui-dev/devcontainer.json`
+
+When you have multiple `devcontainer.json` files in your repository, each codespace is created from only one of the configurations. Settings cannot be imported or inherited between `devcontainer.json` files. If a `devcontainer.json` file in a custom subdirectory has dependent files, such as the Dockerfile or scripts that are run by commands in the `devcontainer.json` file, it's recommended that you co-locate these files in the same subdirectory.
+
+For information about how to choose your preferred dev container configuration when you create a codespace, see "[Creating a codespace](/codespaces/developing-in-codespaces/creating-a-codespace#creating-a-codespace)."
+
+{% data reusables.codespaces.more-info-devcontainer %}
+
+#### How to use the devcontainer.json
+
+It's useful to think of the `devcontainer.json` file as providing "customization" rather than "personalization." You should only include things that everyone working on your codebase needs as standard elements of the development environment, not things that are personal preferences. Things like linters are good to standardize on, and to require everyone to have installed, so they're good to include in your `devcontainer.json` file. Things like user interface decorators or themes are personal choices that should not be put in the `devcontainer.json` file.
+
+You can personalize your codespaces by using dotfiles and Settings Sync. For more information, see "[Personalizing Codespaces for your account](/codespaces/customizing-your-codespace/personalizing-codespaces-for-your-account)."
+
+### Dockerfile
+
+You can add a Dockerfile as part of your dev container configuration. 
+
+The Dockerfile is a text file that contains the instructions needed to create a Docker container image. This image is used to generate a development container each time someone creates a codespace using the `devcontainer.json` file that references this Dockerfile. The instructions in the Dockerfile typically begin by referencing a parent image on which the new image that will be created is based. This is followed by commands that are run during the image creation process, for example to install software packages.
+
+The Dockerfile for a dev container is typically located in the `.devcontainer` folder, alongside the `devcontainer.json` in which it is referenced. 
+
+{% note %}
+
+**Note**: As an alternative to using a Dockerfile you can use the `image` property in the `devcontainer.json` file to refer directly to an existing image you want to use. If neither a Dockerfile nor an image is found then the default container image is used. For more information, see "[Using the default dev container configuration](#using-the-default-dev-container-configuration)."
+
+{% endnote %}
+
+#### Simple Dockerfile example
+
+The following example uses four instructions:
+
+`ARG` defines a build-time variable.
+
+`FROM` specifies the parent image on which the generated Docker image will be based.
+
+`COPY` copies a file and adds it to the filesystem. 
+
+`RUN` updates package lists and runs a script. You can also use a `RUN` instruction to install software, as shown by the commented out instructions. To run multiple commands, use `&&` to combine the commands into a single `RUN` statement.
+
+```Dockerfile{:copy}
+ARG VARIANT="16-buster"
+FROM mcr.microsoft.com/vscode/devcontainers/javascript-node:0-${VARIANT}
+
+# [Optional] Uncomment if you want to install an additional version of node using nvm
+# ARG EXTRA_NODE_VERSION=10
+# RUN su node -c "source /usr/local/share/nvm/nvm.sh && nvm install ${EXTRA_NODE_VERSION}"
+
+# [Optional] Uncomment if you want to install more global node modules
+# RUN su node -c "npm install -g <your-package-list-here>"
+
+COPY library-scripts/github-debian.sh /tmp/library-scripts/
+RUN apt-get update && bash /tmp/library-scripts/github-debian.sh
+```
+
+For more information about Dockerfile instructions, see "[Dockerfile reference](https://docs.docker.com/engine/reference/builder)" in the Docker documentation.
+
+#### Using a Dockerfile
+
+To use a Dockerfile as part of a dev container configuration, reference it in your `devcontainer.json` file by using the `dockerfile` property.
+
+```json{:copy}
+{
+  ...
+  "build": { "dockerfile": "Dockerfile" },
+  ...
+}
+```
+
+For more information about using a Dockerfile in a dev container configuration, see the {% data variables.product.prodname_vscode %} documentation "[Create a development container](https://code.visualstudio.com/docs/remote/create-dev-container#_dockerfile)."
+
+## Using the default dev container configuration
+
+If you don't define a configuration in your repository, {% data variables.product.prodname_dotcom %} creates a codespace using a default Linux image. This Linux image includes languages and runtimes like Python, Node.js, JavaScript, TypeScript, C++, Java, .NET, PHP, PowerShell, Go, Ruby, and Rust. It also includes other developer tools and utilities like Git, GitHub CLI, yarn, openssh, and vim. To see all the languages, runtimes, and tools that are included use the `devcontainer-info content-url` command inside your codespace terminal and follow the URL that the command outputs.
+
+Alternatively, for more information about everything that's included in the default Linux image, see the latest file in the [`microsoft/vscode-dev-containers`](https://github.com/microsoft/vscode-dev-containers/tree/main/containers/codespaces-linux) repository. 
+
+The default configuration is a good option if you're working on a small project that uses the languages and tools that {% data variables.product.prodname_github_codespaces %} provides.
+
+## Using a predefined dev container configuration
+
+You can choose from a list of predefined configurations to create a dev container configuration for your repository. These configurations provide common setups for particular project types, and can help you quickly get started with a configuration that already has the appropriate container options, {% data variables.product.prodname_vscode %} settings, and {% data variables.product.prodname_vscode %} extensions that should be installed.
+
+Using a predefined configuration is a great idea if you need some additional extensibility. You can also start with a predefined configuration and amend it as needed for your project.
+
+You can add a predefined dev container configuration either while working in a codespace, or while working on a repository locally. 
+
+{% data reusables.codespaces.command-palette-container %}
+1. Click the definition you want to use.
+
+   ![List of predefined container definitions](/assets/images/help/codespaces/predefined-container-definitions-list.png)
+
+1. Follow the prompts to customize your definition. For more information on the options to customize your definition, see "[Adding additional features to your `devcontainer.json` file](#adding-additional-features-to-your-devcontainerjson-file)."
+1. Click **OK**.
+
+   ![OK button](/assets/images/help/codespaces/prebuilt-container-ok-button.png)
+
+1. If you are working in a codespace, apply your changes, by clicking **Rebuild now** in the message at the bottom right of the window. For more information about rebuilding your container, see "[Applying changes to your configuration](#applying-changes-to-your-configuration)."
+
+   !["Codespaces: Rebuild Container" in the {% data variables.product.prodname_vscode_command_palette %}](/assets/images/help/codespaces/rebuild-prompt.png)
+
+### Adding additional features to your `devcontainer.json` file
+
+{% note %}
+
+**Note:** This feature is in beta and subject to change.
+
+{% endnote %}
+
+You can add features to your predefined container configuration to customize which tools are available and extend the functionality of your workspace without having to create a custom dev container configuration from scratch. For example, you could use a predefined container configuration and add the {% data variables.product.prodname_cli %}. You can make these additional features available for your project by adding the features to your `devcontainer.json` file when you set up your container configuration.
+
+You can add some of the most common features by selecting them when configuring your predefined container. For more information on the available features, see the [script library](https://github.com/microsoft/vscode-dev-containers/tree/main/script-library#scripts) in the `vscode-dev-containers` repository.
+
+
+1. Access the Command Palette (`Shift + Command + P` / `Ctrl + Shift + P`), then start typing "configure". Select **Codespaces: Configure Devcontainer Features**.
+
+   ![The Configure Devcontainer Features command in the command palette](/assets/images/help/codespaces/codespaces-configure-features.png)
+
+1. Update your feature selections, then click **OK**.
+
+   ![The select additional features menu during container configuration](/assets/images/help/codespaces/select-additional-features.png)
+
+1. To apply the changes, in the bottom right corner of the screen, click **Rebuild now**. For more information about rebuilding your container, see "[Applying changes to your configuration](#applying-changes-to-your-configuration)."
+
+   !["Codespaces: Rebuild Container" in the command palette](/assets/images/help/codespaces/rebuild-prompt.png)
+
+## Creating a custom dev container configuration
+
+If none of the predefined configurations meets your needs, you can create a custom configuration by writing your own `devcontainer.json` file.
+
+* If you're adding a single `devcontainer.json` file that will be used by everyone who creates a codespace from your repository, create the file within a `.devcontainer` directory at the root of the repository. 
+* If you want to offer users a choice of configuration, you can create multiple custom `devcontainer.json` files, each located within a separate subdirectory of the `.devcontainer` directory.
+
+   {% note %}
+
+   **Note**: You can't locate your `devcontainer.json` files in directories more than one level below `.devcontainer`. For example, a file at `.devcontainer/teamA/devcontainer.json` will work, but `.devcontainer/teamA/testing/devcontainer.json` will not. 
+
+   {% endnote %}
+
+   If multiple `devcontainer.json` files are found in the repository, they are listed in the codespace creation options page. For more information, see "[Creating a codespace](/codespaces/developing-in-codespaces/creating-a-codespace#creating-a-codespace)."
+
+   ![A choice of configuration files](/assets/images/help/codespaces/configuration-file-choice.png)
+
+### Default configuration selection during codespace creation
+
+If `.devcontainer/devcontainer.json` or `.devcontainer.json` exists, it will be the default selection in the list of available configuration files when you create a codespace. If neither file exists, the default dev container configuration will be selected by default. 
+
+![The default configuration choice selected](/assets/images/help/codespaces/configuration-file-choice-default.png)
+
+### Editing the devcontainer.json file
+
+You can add and edit the supported configuration keys in the `devcontainer.json` file to specify aspects of the codespace's environment, like which {% data variables.product.prodname_vscode %} extensions will be installed. {% data reusables.codespaces.more-info-devcontainer %}
+
+The `devcontainer.json` file is written using the JSONC format. This allows you to include comments within the configuration file. For more information, see "[Editing JSON with Visual Studio Code](https://code.visualstudio.com/docs/languages/json#_json-with-comments)" in the {% data variables.product.prodname_vscode %} documentation.
+
+{% note %}
+
+**Note**: If you use a linter to valid the `devcontainer.json` file, make sure it is set to JSONC and not JSON or comments will be reported as errors.
+
+{% endnote %}
+
+### Editor settings for Visual Studio Code
+
+{% data reusables.codespaces.vscode-settings-order %}
+
+You can define default editor settings for {% data variables.product.prodname_vscode %} in two places.
+
+* Editor settings defined in the `.vscode/settings.json` file in your repository are applied as _Workspace_-scoped settings in the codespace.
+* Editor settings defined in the `settings` key in the `devcontainer.json` file are applied as _Remote [Codespaces]_-scoped settings in the codespace.
+
+## Applying changes to your configuration
+
+{% data reusables.codespaces.apply-devcontainer-changes %}
+
+{% data reusables.codespaces.rebuild-command %}
+1. {% data reusables.codespaces.recovery-mode %} Fix the errors in the configuration.
+
+   ![Error message about recovery mode](/assets/images/help/codespaces/recovery-mode-error-message.png)
+
+   - To diagnose the error by reviewing the creation logs, click **View creation log**.
+   - To fix the errors identified in the logs, update your `devcontainer.json` file.
+   - To apply the changes, rebuild your container. 
+
+## Further reading
+
+- "[Prebuilding your codespaces](/codespaces/prebuilding-your-codespaces)"

content/codespaces/setting-up-your-project-for-codespaces/setting-a-minimum-specification-for-codespace-machines.md

@@ -15,9 +15,9 @@ product: '{% data reusables.gated-features.codespaces %}'
 
 ## Overview
 
-When you create a codespace for a repository you are typically offered a choice of available machine types. Each machine type has a different level of resources. For more information, see "[Changing the machine type for your codespace](/codespaces/customizing-your-codespace/changing-the-machine-type-for-your-codespace#about-machine-types)."
+Each codespace that you create is hosted on a separate virtual machine, and you can usually choose from different types of virtual machines. Each machine type has different resources (CPUs, memory, storage) and, by default, the machine type with the least resources is used. For more information, see "[Changing the machine type for your codespace](/codespaces/customizing-your-codespace/changing-the-machine-type-for-your-codespace#about-machine-types)."
 
-If your project needs a certain level of compute power, you can configure {% data variables.product.prodname_github_codespaces %} so that only machine types that meet these requirements are available for people to select. You configure this in the `devcontainer.json` file.
+If your project needs a certain level of compute power, you can configure {% data variables.product.prodname_github_codespaces %} so that only machine types that meet these requirements can be used by default, or selected by users. You configure this in a `devcontainer.json` file.
 
 {% note %}
 
@@ -27,7 +27,7 @@ If your project needs a certain level of compute power, you can configure {% dat
 
 ## Setting a minimum machine specification
 
-1. {% data variables.product.prodname_codespaces %} for your repository are configured in the `devcontainer.json` file. If your repository does not already contain a `devcontainer.json` file, add one now. See "[Add a dev container to your project](/free-pro-team@latest/codespaces/setting-up-your-project-for-codespaces/setting-up-your-project-for-codespaces)."
+1. {% data variables.product.prodname_codespaces %} for your repository are configured in a `devcontainer.json` file. If your repository does not already contain a `devcontainer.json` file, add one now. See "[Add a dev container configuration to your repository](/free-pro-team@latest/codespaces/setting-up-your-project-for-codespaces/setting-up-your-project-for-codespaces)."
 1. Edit the `devcontainer.json` file, adding a `hostRequirements` property such as this:
 
    ```json{:copy}
@@ -44,10 +44,10 @@ If your project needs a certain level of compute power, you can configure {% dat
    
 1. Save the file and commit your changes to the required branch of the repository.
 
-   Now when you create a codespace for that branch of the repository you will only be able to select machine types that match or exceed the resources you've specified.
+   Now when you create a codespace for that branch of the repository, and you go to the creation configuration options, you will only be able to select machine types that match or exceed the resources you've specified.
 
    ![Dialog box showing a limited choice of machine types](/assets/images/help/codespaces/machine-types-limited-choice.png)
 
 ## Further reading
 
-- "[Introduction to dev containers](/codespaces/setting-up-your-project-for-codespaces/configuring-codespaces-for-your-project)"
+- "[Introduction to dev containers](/codespaces/setting-up-your-project-for-codespaces/introduction-to-dev-containers)"

content/codespaces/setting-up-your-project-for-codespaces/setting-up-your-dotnet-project-for-codespaces.md

@@ -15,8 +15,6 @@ hasExperimentalAlternative: true
 hidden: true
 ---
 
-
-
 ## Introduction
 
 This guide shows you how to set up your C# (.NET) project in {% data variables.product.prodname_codespaces %}. It will take you through an example of opening your project in a codespace, and adding and modifying a dev container configuration from a template.
@@ -28,7 +26,7 @@ This guide shows you how to set up your C# (.NET) project in {% data variables.p
 
 ## Step 1: Open your project in a codespace
 
-1. Under the repository name, use the **{% octicon "code" aria-label="The code icon" %} Code** drop-down menu, and in the **Codespaces** tab, click {% octicon "plus" aria-label="The plus icon" %} **New codespace**.
+1. Under the repository name, use the **{% octicon "code" aria-label="The code icon" %} Code** drop-down menu, and in the **Codespaces** tab, click **Create codespace on main**.
 
   ![New codespace button](/assets/images/help/codespaces/new-codespace-button.png)
 
@@ -36,25 +34,20 @@ This guide shows you how to set up your C# (.NET) project in {% data variables.p
 
 When you create a codespace, your project is created on a remote VM that is dedicated to you. By default, the container for your codespace has many languages and runtimes including .NET. It also includes a common set of tools like git, wget, rsync, openssh, and nano.
 
-You can customize your codespace by adjusting the amount of vCPUs and RAM, [adding dotfiles to personalize your environment](/codespaces/setting-up-your-codespace/personalizing-codespaces-for-your-account), or by modifying the tools and scripts installed.
+{% data reusables.codespaces.customize-vcpus-and-ram %}
 
-{% data variables.product.prodname_codespaces %} uses a file called `devcontainer.json` to store configurations. On launch {% data variables.product.prodname_codespaces %} uses the file to install any tools, dependencies, or other set up that might be needed for the project. For more information, see "[Introduction to dev containers](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)."
+## Step 2: Add a dev container configuration to your repository from a template
 
+The default development container, or "dev container," for {% data variables.product.prodname_github_codespaces %} comes with the latest .NET version and common tools preinstalled. However, we recommend that you configure your own dev container to include all of the tools and scripts that your project needs. This will ensure a fully reproducible environment for all {% data variables.product.prodname_github_codespaces %} users in your repository.
 
-## Step 2: Add a dev container to your codespace from a template
+{% data reusables.codespaces.setup-custom-devcontainer %}
-
-The default codespaces container comes with the latest .NET version and common tools preinstalled. However, we encourage you to set up a custom container so you can tailor the tools and scripts that run as part of codespace creation to your project's needs and ensure a fully reproducible environment for all {% data variables.product.prodname_codespaces %} users in your repository.
-
-To set up your project with a custom container, you will need to use a `devcontainer.json` file to define the environment. In {% data variables.product.prodname_codespaces %} you can add this either from a template or you can create your own. For more information on dev containers, see "[Introduction to dev containers
-](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)."
-
 
 {% data reusables.codespaces.command-palette-container %}
-2. For this example, click **C# (.NET)**. If you need additional features you can select any container that’s specific to C# (.NET) or a combination of tools such as C# (.NET) and MS SQL.
+1. For this example, click **C# (.NET)**. If you need additional features you can select any container that’s specific to C# (.NET) or a combination of tools such as C# (.NET) and MS SQL.
   ![Select C# (.NET) option from the list](/assets/images/help/codespaces/add-dotnet-prebuilt-container.png)
-3. Click the recommended version of .NET.
+1. Click the recommended version of .NET.
   ![.NET version selection](/assets/images/help/codespaces/add-dotnet-version.png)
-4. Accept the default option to add Node.js to your customization.
+1. Accept the default option to add Node.js to your customization.
   ![Add Node.js selection](/assets/images/help/codespaces/dotnet-options.png)
 {% data reusables.codespaces.rebuild-command %}
 
@@ -128,17 +121,17 @@ The newly added `devcontainer.json` file defines a few properties that are descr
 }
 ```
 
-- **Name** - You can name our dev container anything, this is just the default.
+- **name** - You can name our dev container anything, this is just the default.
-- **Build** - The build properties.
+- **build** - The build properties.
-  - **Dockerfile** - In the build object, `dockerfile` is a reference to the Dockerfile that was also added from the template.
+  - **dockerfile** - In the `build` object, `dockerfile` contains the path to the Dockerfile that was also added from the template.
-  - **Args**
+  - **args**
-    - **Variant**: This file only contains one build argument, which is the .NET Core version that we want to use.
+    - **variant**: This file only contains one build argument, which is the .NET Core version that we want to use.
-- **Settings** - These are {% data variables.product.prodname_vscode %} settings.
+- **settings** - These are {% data variables.product.prodname_vscode %} settings.
-  - **Terminal.integrated.shell.linux** - While bash is the default here, you could use other terminal shells by modifying this.
+  - **terminal.integrated.shell.linux** - While bash is the default here, you could use other terminal shells by modifying this.
-- **Extensions** - These are extensions included by default.
+- **extensions** - These are extensions included by default.
   - **ms-dotnettools.csharp** - The Microsoft C# extension provides rich support for developing in C#, including features such as IntelliSense, linting, debugging, code navigation, code formatting, refactoring, variable explorer, test explorer, and more.
 - **forwardPorts** - Any ports listed here will be forwarded automatically. For more information, see "[Forwarding ports in your codespace](/codespaces/developing-in-codespaces/forwarding-ports-in-your-codespace)."
-- **postCreateCommand** - If you want to run anything after you land in your codespace that’s not defined in the Dockerfile, like `dotnet restore`, you can do that here.
+- **postCreateCommand** - Use this to run commands that aren't defined in the Dockerfile, after your codespace is created.
 - **remoteUser** - By default, you’re running as the vscode user, but you can optionally set this to root.
 
 #### Dockerfile
@@ -171,9 +164,9 @@ You can use the Dockerfile to add additional container layers to specify OS pack
 
 ## Step 3: Modify your devcontainer.json file
 
-With your dev container added and a basic understanding of what everything does, you can now make changes to configure it for your environment. In this example, you'll add properties to install extensions and restore your project dependencies when your codespace launches.
+With your dev container configuration added and a basic understanding of what everything does, you can now make changes to customize your environment further. In this example, you'll add properties to install extensions and your project dependencies when your codespace launches.
 
-1. In the Explorer, expand the `.devcontainer` folder and select the `devcontainer.json` file from the tree to open it.
+1. In the Explorer, select the `devcontainer.json` file from the tree to open it. You might have to expand the `.devcontainer` folder to see it.
 
    ![devcontainer.json file in the Explorer](/assets/images/help/codespaces/devcontainers-options.png)
 
@@ -193,9 +186,11 @@ With your dev container added and a basic understanding of what everything does,
    "postCreateCommand": "dotnet restore",
    ```
 
+   {% data reusables.codespaces.more-info-devcontainer %}
+
 {% data reusables.codespaces.rebuild-command %}
 
-  Rebuilding inside your codespace ensures your changes work as expected before you commit the changes to the repository. If something does result in a failure, you’ll be placed in a codespace with a recovery container that you can rebuild from to keep adjusting your container.
+   {% data reusables.codespaces.rebuild-reason %}
 
 5. Check your changes were successfully applied by verifying the "Code Spell Checker" extension was installed.
 
@@ -219,6 +214,4 @@ In the previous section, you used the `postCreateCommand` to install a set of pa
 
 You should now be ready start developing your C# (.NET) project in {% data variables.product.prodname_codespaces %}. Here are some additional resources for more advanced scenarios.
 
-- [Managing encrypted secrets for {% data variables.product.prodname_codespaces %}](/codespaces/working-with-your-codespace/managing-encrypted-secrets-for-codespaces)
+{% data reusables.codespaces.next-steps-adding-devcontainer %}
-- [Managing GPG verification for {% data variables.product.prodname_codespaces %}](/codespaces/working-with-your-codespace/managing-gpg-verification-for-codespaces)
-- [Forwarding ports in your codespace](/codespaces/developing-in-codespaces/forwarding-ports-in-your-codespace)

content/codespaces/setting-up-your-project-for-codespaces/setting-up-your-java-project-for-codespaces.md

@@ -14,8 +14,6 @@ hasExperimentalAlternative: true
 hidden: true
 ---
 
-
-
 ## Introduction
 
 This guide shows you how to set up your Java project in {% data variables.product.prodname_codespaces %}. It will take you through an example of opening your project in a codespace, and adding and modifying a dev container configuration from a template.
@@ -27,7 +25,7 @@ This guide shows you how to set up your Java project in {% data variables.produc
 
 ## Step 1: Open your project in a codespace
 
-1. Under the repository name, use the **{% octicon "code" aria-label="The code icon" %} Code** drop-down menu, and in the **Codespaces** tab, click {% octicon "plus" aria-label="The plus icon" %} **New codespace**.
+1. Under the repository name, use the **{% octicon "code" aria-label="The code icon" %} Code** drop-down menu, and in the **Codespaces** tab, click **Create codespace on main**.
 
   ![New codespace button](/assets/images/help/codespaces/new-codespace-button.png)
 
@@ -35,28 +33,24 @@ This guide shows you how to set up your Java project in {% data variables.produc
 
 When you create a codespace, your project is created on a remote VM that is dedicated to you. By default, the container for your codespace has many languages and runtimes including Java, nvm, npm, and Yarn. It also includes a common set of tools like git, wget, rsync, openssh, and nano.
 
-You can customize your codespace by adjusting the amount of vCPUs and RAM, [adding dotfiles to personalize your environment](/codespaces/setting-up-your-codespace/personalizing-codespaces-for-your-account), or by modifying the tools and scripts installed.
+{% data reusables.codespaces.customize-vcpus-and-ram %}
 
-{% data variables.product.prodname_codespaces %} uses a file called `devcontainer.json` to store configurations. On launch {% data variables.product.prodname_codespaces %} uses the file to install any tools, dependencies, or other set up that might be needed for the project. For more information, see "[Introduction to dev containers](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)."
+## Step 2: Add a dev container configuration to your repository from a template
 
+The default development container, or "dev container," for {% data variables.product.prodname_github_codespaces %} comes with the latest Java version, package managers (Maven, Gradle), and other common tools preinstalled. However, we recommend that you configure your own dev container to include all of the tools and scripts that your project needs. This will ensure a fully reproducible environment for all {% data variables.product.prodname_github_codespaces %} users in your repository.
 
-## Step 2: Add a dev container to your codespace from a template
+{% data reusables.codespaces.setup-custom-devcontainer %}
-
-The default codespaces container comes with the latest Java version, package managers (Maven, Gradle), and other common tools preinstalled. However, we recommend that you set up a custom container to define the tools and scripts that your project needs. This will ensure a fully reproducible environment for all {% data variables.product.prodname_codespaces %} users in your repository.
-
-To set up your project with a custom container, you will need to use a `devcontainer.json` file to define the environment. In {% data variables.product.prodname_codespaces %} you can add this either from a template or you can create your own. For more information on dev containers, see "[Introduction to dev containers](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)."
-
 
 {% data reusables.codespaces.command-palette-container %}
-3. For this example, click **Java**. In practice, you could select any container that’s specific to Java or a combination of tools such as Java and Azure Functions.
+1. For this example, click **Java**. In practice, you could select any container that’s specific to Java or a combination of tools such as Java and Azure Functions.
   ![Select Java option from the list](/assets/images/help/codespaces/add-java-prebuilt-container.png)
-4. Click the recommended version of Java.
+1. Click the recommended version of Java.
   ![Java version selection](/assets/images/help/codespaces/add-java-version.png)
 {% data reusables.codespaces.rebuild-command %}
 
 ### Anatomy of your dev container
 
-Adding the Java dev container template adds a `.devcontainer` folder to the root of your project's repository with the following files:
+Adding the Java dev container template adds a `.devcontainer` directory to the root of your project's repository with the following files:
 
 - `devcontainer.json`
 - Dockerfile
@@ -106,17 +100,17 @@ The newly added `devcontainer.json` file defines a few properties that are descr
 }
 ```
 
-- **Name** - You can name your dev container anything, this is just the default.
+- **name** - You can name your dev container anything, this is just the default.
-- **Build** - The build properties.
+- **build** - The build properties.
-  - **Dockerfile** - In the build object, dockerfile is a reference to the Dockerfile that was also added from the template.
+  - **dockerfile** - In the `build` object, `dockerfile` contains the path to the Dockerfile that was also added from the template.
-  - **Args**
+  - **args**
-    - **Variant**: This file only contains one build argument, which is the Java version that is passed into the Dockerfile.
+    - **variant**: This file only contains one build argument, which is the Java version that is passed into the Dockerfile.
-- **Settings** - These are {% data variables.product.prodname_vscode %} settings that you can set.
+- **settings** - These are {% data variables.product.prodname_vscode %} settings that you can set.
-  - **Terminal.integrated.shell.linux** - While bash is the default here, you could use other terminal shells by modifying this.
+  - **terminal.integrated.shell.linux** - While bash is the default here, you could use other terminal shells by modifying this.
-- **Extensions** - These are extensions included by default.
+- **extensions** - These are extensions included by default.
-  - **Vscjava.vscode-java-pack** - The Java Extension Pack provides popular extensions for Java development to get you started.
+  - **vscjava.vscode-java-pack** - The Java Extension Pack provides popular extensions for Java development to get you started.
 - **forwardPorts** - Any ports listed here will be forwarded automatically. For more information, see "[Forwarding ports in your codespace](/codespaces/developing-in-codespaces/forwarding-ports-in-your-codespace)."
-- **postCreateCommand** - If you want to run anything after you land in your codespace that’s not defined in the Dockerfile, you can do that here.
+- **postCreateCommand** - Use this to run commands that aren't defined in the Dockerfile, after your codespace is created.
 - **remoteUser** - By default, you’re running as the `vscode` user, but you can optionally set this to `root`.
 
 #### Dockerfile
@@ -147,11 +141,11 @@ RUN if [ "${INSTALL_NODE}" = "true" ]; then su vscode -c "source /usr/local/shar
 # RUN su vscode -c "source /usr/local/share/nvm/nvm.sh && npm install -g <your-package-here>" 2>&1
 ```
 
-You can use the Dockerfile to add additional container layers to specify OS packages, Java versions, or global packages we want included in our Dockerfile.
+You can use the Dockerfile to add additional container layers to specify OS packages, Java versions, or global packages we want included in our container.
 
 ## Step 3: Modify your devcontainer.json file
 
-With your dev container added and a basic understanding of what everything does, you can now make changes to configure it for your environment. In this example, you'll add properties to install extensions and your project dependencies when your codespace launches.
+With your dev container configuration added and a basic understanding of what everything does, you can now make changes to customize your environment further. In this example, you'll add properties to install extensions and your project dependencies when your codespace launches.
 
 1. In the Explorer, select the `devcontainer.json` file from the tree to open it. You might have to expand the `.devcontainer` folder to see it.
 
@@ -164,12 +158,11 @@ With your dev container added and a basic understanding of what everything does,
    "forwardPorts": [4000],
    ```
 
-  For more information on `devcontainer.json` properties, see the [devcontainer.json reference](https://code.visualstudio.com/docs/remote/devcontainerjson-reference) on the Visual Studio Code docs.
+   {% data reusables.codespaces.more-info-devcontainer %}
 
 {% data reusables.codespaces.rebuild-command %}
 
-  Rebuilding inside your codespace ensures your changes work as expected before you commit the changes to the repository. If something does result in a failure, you’ll be placed in a codespace with a recovery container that you can rebuild from to keep adjusting your container.
+   {% data reusables.codespaces.rebuild-reason %}
-
 
 ## Step 4: Run your application
 
@@ -189,6 +182,4 @@ In the previous section, you used the `postCreateCommand` to install a set of pa
 
 You should now be ready start developing your Java project in {% data variables.product.prodname_codespaces %}. Here are some additional resources for more advanced scenarios.
 
-- [Managing encrypted secrets for {% data variables.product.prodname_codespaces %}](/codespaces/working-with-your-codespace/managing-encrypted-secrets-for-codespaces)
+{% data reusables.codespaces.next-steps-adding-devcontainer %}
-- [Managing GPG verification for {% data variables.product.prodname_codespaces %}](/codespaces/working-with-your-codespace/managing-gpg-verification-for-codespaces)
-- [Forwarding ports in your codespace](/codespaces/developing-in-codespaces/forwarding-ports-in-your-codespace)

content/codespaces/setting-up-your-project-for-codespaces/setting-up-your-nodejs-project-for-codespaces.md

@@ -31,7 +31,7 @@ This guide shows you how to set up your JavaScript, Node.js, or TypeScript proje
 
 ## Step 1: Open your project in a codespace
 
-1. Under the repository name, use the **{% octicon "code" aria-label="The code icon" %} Code** drop-down menu, and in the **Codespaces** tab, click {% octicon "plus" aria-label="The plus icon" %} **New codespace**.
+1. Under the repository name, use the **{% octicon "code" aria-label="The code icon" %} Code** drop-down menu, and in the **Codespaces** tab, click **Create codespace on main**.
 
    ![New codespace button](/assets/images/help/codespaces/new-codespace-button.png)
 
@@ -40,26 +40,28 @@ This guide shows you how to set up your JavaScript, Node.js, or TypeScript proje
 
 When you create a codespace, your project is created on a remote VM that is dedicated to you. By default, the container for your codespace has many languages and runtimes including Node.js, JavaScript, Typescript, nvm, npm, and yarn. It also includes a common set of tools like git, wget, rsync, openssh, and nano.
 
-You can customize your codespace by adjusting the amount of vCPUs and RAM, [adding dotfiles to personalize your environment](/codespaces/setting-up-your-codespace/personalizing-codespaces-for-your-account), or by modifying the tools and scripts installed.
+{% data reusables.codespaces.customize-vcpus-and-ram %}
 
-{% data variables.product.prodname_codespaces %} uses a file called `devcontainer.json` to store configurations. On launch {% data variables.product.prodname_codespaces %} uses the file to install any tools, dependencies, or other set up that might be needed for the project. For more information, see "[Introduction to dev containers](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)."
+## Step 2: Add a dev container configuration to your repository from a template
 
-## Step 2: Add a dev container to your codespace from a template
+The default development container, or "dev container," for {% data variables.product.prodname_github_codespaces %} will support running Node.js projects like [vscode-remote-try-node](https://github.com/microsoft/vscode-remote-try-node) out of the box. However, we recommend that you configure your own dev container, as this allows you to define any particular tools and scripts your project needs. This will ensure a fully reproducible environment for all GitHub Codespaces users in your repository.
 
-The default codespaces container will support running Node.js projects like [vscode-remote-try-node](https://github.com/microsoft/vscode-remote-try-node) out of the box. By setting up a custom container you can customize the tools and scripts that run as part of codespace creation and ensure a fully reproducible environment for all {% data variables.product.prodname_codespaces %} users in your repository.
+{% data reusables.codespaces.setup-custom-devcontainer %}
-
-To set up your project with a custom container, you will need to use a `devcontainer.json` file to define the environment. In {% data variables.product.prodname_codespaces %} you can add this either from a template or you can create your own. For more information on dev containers, see "[Introduction to dev containers](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)".
 
 {% data reusables.codespaces.command-palette-container %}
-3. For this example, click **Node.js**.  If you need additional features you can select any container that’s specific to Node or a combination of tools such as Node and MongoDB.
+1. For this example, click **Node.js**.  If you need additional features you can select any container that’s specific to Node or a combination of tools such as Node and MongoDB.
+
    ![Select Node option from the list](/assets/images/help/codespaces/add-node-prebuilt-container.png)
-4. Click the recommended version of Node.js.
+
+1. Click the recommended version of Node.js.
+
    ![Node.js version selection](/assets/images/help/codespaces/add-node-version.png)
+
 {% data reusables.codespaces.rebuild-command %}
 
 ### Anatomy of your dev container
 
-Adding the Node.js dev container template adds a `.devcontainer` folder to the root of your project's repository with the following files:
+Adding the Node.js dev container template adds a `.devcontainer` directory to the root of your project's repository with the following files:
 
 - `devcontainer.json`
 - Dockerfile
@@ -100,17 +102,17 @@ The newly added `devcontainer.json` file defines a few properties that are descr
 }
 ```
 
-- **Name** - You can name your dev container anything, this is just the default.
+- **name** - You can name your dev container anything, this is just the default.
-- **Build** - The build properties.
+- **build** - The build properties.
-  - **dockerfile** - In the build object, dockerfile is a reference to the Dockerfile that was also added from the template.
+  - **dockerfile** - In the `build` object, `dockerfile` contains the path to the Dockerfile that was also added from the template.
-  - **Args**
+  - **args**
-    - **Variant**: This file only contains one build argument, which is the node variant we want to use that is passed into the Dockerfile.
+    - **variant**: This file only contains one build argument, which is the node variant we want to use that is passed into the Dockerfile.
-- **Settings** - These are {% data variables.product.prodname_vscode %} settings that you can set.
+- **settings** - These are {% data variables.product.prodname_vscode %} settings that you can set.
-  - **Terminal.integrated.shell.linux** - While bash is the default here, you could use other terminal shells by modifying this.
+  - **terminal.integrated.shell.linux** - While bash is the default here, you could use other terminal shells by modifying this.
-- **Extensions** - These are extensions included by default.
+- **extensions** - These are extensions included by default.
-  - **Dbaeumer.vscode-eslint** - ES lint is a great extension for linting, but for JavaScript there are a number of great Marketplace extensions you could also include.
+  - **dbaeumer.vscode-eslint** - ES lint is a great extension for linting, but for JavaScript there are a number of great Marketplace extensions you could also include.
 - **forwardPorts** - Any ports listed here will be forwarded automatically. For more information, see "[Forwarding ports in your codespace](/codespaces/developing-in-codespaces/forwarding-ports-in-your-codespace)."
-- **postCreateCommand** - If you want to run anything after you land in your codespace that’s not defined in the Dockerfile, you can do that here.
+- **postCreateCommand** - Use this to run commands that aren't defined in the Dockerfile, after your codespace is created.
 - **remoteUser** - By default, you’re running as the vscode user, but you can optionally set this to root.
 
 #### Dockerfile
@@ -132,11 +134,11 @@ FROM mcr.microsoft.com/vscode/devcontainers/javascript-node:0-${VARIANT}
 # RUN su node -c "npm install -g <your-package-list-here>"
 ```
 
-You can use the Dockerfile to add additional container layers to specify OS packages, node versions, or global packages we want included in our Dockerfile.
+You can use the Dockerfile to add additional container layers to specify OS packages, node versions, or global packages we want included in our container.
 
 ## Step 3: Modify your devcontainer.json file
 
-With your dev container added and a basic understanding of what everything does, you can now make changes to configure it for your environment. In this example, you'll add properties to install npm when your codespace launches and make a list of ports inside the container available locally.
+With your dev container configuration added and a basic understanding of what everything does, you can now make changes to customize your environment further. In this example, you'll add properties to install npm when your codespace launches and make a list of ports inside the container available locally.
 
 1. In the Explorer, select the `devcontainer.json` file from the tree to open it. You might have to expand the `.devcontainer` folder to see it.
 
@@ -149,12 +151,11 @@ With your dev container added and a basic understanding of what everything does,
    "forwardPorts": [4000],
    ```
 
-  For more information on `devcontainer.json` properties, see the [devcontainer.json reference](https://code.visualstudio.com/docs/remote/devcontainerjson-reference) in the {% data variables.product.prodname_vscode %} docs.
+   {% data reusables.codespaces.more-info-devcontainer %}
 
 {% data reusables.codespaces.rebuild-command %}
 
-  Rebuilding inside your codespace ensures your changes work as expected before you commit the changes to the repository. If something does result in a failure, you’ll be placed in a codespace with a recovery container that you can rebuild from to keep adjusting your container.
+   {% data reusables.codespaces.rebuild-reason %}
-
 
 ## Step 4: Run your application
 
@@ -176,6 +177,4 @@ In the previous section, you used the `postCreateCommand` to installing a set of
 
 You should now be ready start developing your JavaScript project in {% data variables.product.prodname_codespaces %}. Here are some additional resources for more advanced scenarios.
 
-- [Managing encrypted secrets for your codespaces](/codespaces/managing-your-codespaces/managing-encrypted-secrets-for-your-codespaces)
+{% data reusables.codespaces.next-steps-adding-devcontainer %}
-- [Managing GPG verification for {% data variables.product.prodname_codespaces %}](/codespaces/managing-your-codespaces/managing-gpg-verification-for-codespaces)
-- [Forwarding ports in your codespace](/codespaces/developing-in-codespaces/forwarding-ports-in-your-codespace)

content/codespaces/setting-up-your-project-for-codespaces/setting-up-your-python-project-for-codespaces.md

@@ -17,8 +17,6 @@ hasExperimentalAlternative: true
 hidden: true
 ---
 
-
-
 ## Introduction
 
 This guide shows you how to set up your Python project in {% data variables.product.prodname_codespaces %}. It will take you through an example of opening your project in a codespace, and adding and modifying a dev container configuration from a template.
@@ -30,40 +28,34 @@ This guide shows you how to set up your Python project in {% data variables.prod
 
 ## Step 1: Open your project in a codespace
 
-1. Under the repository name, use the **{% octicon "code" aria-label="The code icon" %} Code** drop-down menu, and in the **Codespaces** tab, click {% octicon "plus" aria-label="The plus icon" %} **New codespace**.
+1. Under the repository name, use the **{% octicon "code" aria-label="The code icon" %} Code** drop-down menu, and in the **Codespaces** tab, click **Create codespace on main**.
 
   ![New codespace button](/assets/images/help/codespaces/new-codespace-button.png)
 
   If you don’t see this option, {% data variables.product.prodname_codespaces %} isn't available for your project. See [Access to {% data variables.product.prodname_codespaces %}](/codespaces/developing-in-codespaces/creating-a-codespace#access-to-codespaces) for more information.
 
-
-
 When you create a codespace, your project is created on a remote VM that is dedicated to you. By default, the container for your codespace has many languages and runtimes including Node.js, JavaScript, Typescript, nvm, npm, and yarn. It also includes a common set of tools like git, wget, rsync, openssh, and nano.
 
-You can customize your codespace by adjusting the amount of vCPUs and RAM, [adding dotfiles to personalize your environment](/codespaces/setting-up-your-codespace/personalizing-codespaces-for-your-account), or by modifying the tools and scripts installed.
+{% data reusables.codespaces.customize-vcpus-and-ram %}
 
-{% data variables.product.prodname_codespaces %} uses a file called `devcontainer.json` to store configurations. On launch {% data variables.product.prodname_codespaces %} uses the file to install any tools, dependencies, or other set up that might be needed for the project. For more information, see "[Introduction to dev containers](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)."
+## Step 2: Add a dev container configuration to your repository from a template
 
+The default development container, or "dev container," for {% data variables.product.prodname_github_codespaces %} comes with the latest Python version, package managers (pip, Miniconda), and other common tools preinstalled. However, we recommend that you configure your own dev container to include all of the tools and scripts that your project needs. This will ensure a fully reproducible environment for all {% data variables.product.prodname_github_codespaces %} users in your repository.
 
-## Step 2: Add a dev container to your codespace from a template
+{% data reusables.codespaces.setup-custom-devcontainer %}
-
-The default codespaces container comes with the latest Python version, package managers (pip, Miniconda), and other common tools preinstalled. However, we recommend that you set up a custom container to define the tools and scripts that your project needs. This will ensure a fully reproducible environment for all {% data variables.product.prodname_codespaces %} users in your repository.
-
-To set up your project with a custom container, you will need to use a `devcontainer.json` file to define the environment. In {% data variables.product.prodname_codespaces %} you can add this either from a template or you can create your own. For more information on dev containers, see "[Introduction to dev containers](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)."
-
 
 {% data reusables.codespaces.command-palette-container %}
-2. For this example, click **Python 3**. If you need additional features you can select any container that’s specific to Python or a combination of tools such as Python 3 and PostgreSQL.
+1. For this example, click **Python 3**. If you need additional features you can select any container that’s specific to Python or a combination of tools such as Python 3 and PostgreSQL.
   ![Select Python option from the list](/assets/images/help/codespaces/add-python-prebuilt-container.png)
-3. Click the recommended version of Python.
+1. Click the recommended version of Python.
   ![Python version selection](/assets/images/help/codespaces/add-python-version.png)
-4. Accept the default option to add Node.js to your customization.
+1. Accept the default option to add Node.js to your customization.
   ![Add Node.js selection](/assets/images/help/codespaces/add-nodejs-selection.png)
 {% data reusables.codespaces.rebuild-command %}
 
 ### Anatomy of your dev container
 
-Adding the Python dev container template adds a `.devcontainer` folder to the root of your project's repository with the following files:
+Adding the Python dev container template adds a `.devcontainer` directory to the root of your project's repository with the following files:
 
 - `devcontainer.json`
 - Dockerfile
@@ -106,7 +98,7 @@ The newly added `devcontainer.json` file defines a few properties that are descr
 
 	// Add the IDs of extensions you want installed when the container is created.
 	"extensions": [
-		"ms-python.python",
+		"ms-python.python"
 	],
 
 	// Use 'forwardPorts' to make a list of ports inside the container available locally.
@@ -120,17 +112,17 @@ The newly added `devcontainer.json` file defines a few properties that are descr
 }
 ```
 
-- **Name** - You can name our dev container anything, this is just the default.
+- **name** - You can name our dev container anything, this is just the default.
-- **Build** - The build properties.
+- **build** - The build properties.
-  - **Dockerfile** - In the build object, `dockerfile` is a reference to the Dockerfile that was also added from the template.
+  - **dockerfile** - In the `build` object, `dockerfile` contains the path to the Dockerfile that was also added from the template.
-  - **Args**
+  - **args**
-    - **Variant**: This file only contains one build argument, which is the node variant we want to use that is passed into the Dockerfile.
+    - **variant**: This file only contains one build argument, which is the node variant we want to use that is passed into the Dockerfile.
-- **Settings** - These are {% data variables.product.prodname_vscode %} settings.
+- **settings** - These are {% data variables.product.prodname_vscode %} settings.
-  - **Terminal.integrated.shell.linux** - While bash is the default here, you could use other terminal shells by modifying this.
+  - **terminal.integrated.shell.linux** - While bash is the default here, you could use other terminal shells by modifying this.
-- **Extensions** - These are extensions included by default.
+- **extensions** - These are extensions included by default.
   - **ms-python.python** - The Microsoft Python extension provides rich support for the Python language (for all actively supported versions of the language: >=3.6), including features such as IntelliSense, linting, debugging, code navigation, code formatting, refactoring, variable explorer, test explorer, and more.
 - **forwardPorts** - Any ports listed here will be forwarded automatically. For more information, see "[Forwarding ports in your codespace](/codespaces/developing-in-codespaces/forwarding-ports-in-your-codespace)."
-- **postCreateCommand** - If you want to run anything after you land in your codespace that’s not defined in the Dockerfile, like `pip3 install -r requirements`, you can do that here.
+- **postCreateCommand** - Use this to run commands that aren't defined in the Dockerfile, like `pip3 install -r requirements`, after your codespace is created.
 - **remoteUser** - By default, you’re running as the `vscode` user, but you can optionally set this to `root`.
 
 #### Dockerfile
@@ -162,7 +154,7 @@ You can use the Dockerfile to add additional container layers to specify OS pack
 
 ## Step 3: Modify your devcontainer.json file
 
-With your dev container added and a basic understanding of what everything does, you can now make changes to configure it for your environment. In this example, you'll add properties to install extensions and your project dependencies when your codespace launches.
+With your dev container configuration added and a basic understanding of what everything does, you can now make changes to customize your environment further. In this example, you'll add properties to install extensions and your project dependencies when your codespace launches.
 
 1. In the Explorer, expand the `.devcontainer` folder and select the `devcontainer.json` file from the tree to open it.
 
@@ -174,7 +166,7 @@ With your dev container added and a basic understanding of what everything does,
   "extensions": [
 		  "ms-python.python",
 		  "cstrap.flask-snippets",
-		  "streetsidesoftware.code-spell-checker",
+		  "streetsidesoftware.code-spell-checker"
 	  ],
   ```
 
@@ -187,7 +179,7 @@ With your dev container added and a basic understanding of what everything does,
 
 {% data reusables.codespaces.rebuild-command %}
 
-  Rebuilding inside your codespace ensures your changes work as expected before you commit the changes to the repository. If something does result in a failure, you’ll be placed in a codespace with a recovery container that you can rebuild from to keep adjusting your container.
+   {% data reusables.codespaces.rebuild-reason %}
 
 5. Check your changes were successfully applied by verifying the Code Spell Checker and Flask Snippet extensions were installed.
 
@@ -211,6 +203,4 @@ In the previous section, you used the `postCreateCommand` to install a set of pa
 
 You should now be ready start developing your Python project in {% data variables.product.prodname_codespaces %}. Here are some additional resources for more advanced scenarios.
 
-- [Managing encrypted secrets for {% data variables.product.prodname_codespaces %}](/codespaces/working-with-your-codespace/managing-encrypted-secrets-for-codespaces)
+{% data reusables.codespaces.next-steps-adding-devcontainer %}
-- [Managing GPG verification for {% data variables.product.prodname_codespaces %}](/codespaces/working-with-your-codespace/managing-gpg-verification-for-codespaces)
-- [Forwarding ports in your codespace](/codespaces/developing-in-codespaces/forwarding-ports-in-your-codespace)

content/codespaces/troubleshooting/troubleshooting-creation-and-deletion-of-codespaces.md

@@ -32,6 +32,8 @@ If you still cannot create a codespace for a repository where {% data variables.
 
 The owner of a codespace has full control over it and only they can delete their codespaces. You cannot delete a codespace created by another user.
 
+You can delete your codespaces in the browser, in {% data variables.product.prodname_vscode %}, or by using {% data variables.product.prodname_cli %}. {% data variables.product.prodname_cli %} also allows you to bulk delete codespaces. For more information, see "[Deleting a codespace](/codespaces/developing-in-codespaces/deleting-a-codespace)."
+
 ## Container storage
 
 When you create a codespace, it has a finite amount of storage and over time it may be necessary for you to free up space. Try running any of the following commands in the {% data variables.product.prodname_codespaces %} terminal to free up storage space.
@@ -54,4 +56,4 @@ Some more destructive options:
 This codespace is currently running in recovery mode due to a container error.
 ```
 
-Review the creation logs, update the configuration as needed, and run **Codespaces: Rebuild Container** in the {% data variables.product.prodname_vscode_command_palette %} to retry. For more information, see " [Codespaces logs](/codespaces/troubleshooting/codespaces-logs)" and "[Configuring {% data variables.product.prodname_codespaces %} for your project](/github/developing-online-with-codespaces/configuring-codespaces-for-your-project#apply-changes-to-your-configuration)."
+Review the creation logs, update the dev container configuration as needed, and run **Codespaces: Rebuild Container** in the {% data variables.product.prodname_vscode_command_palette %} to retry. For more information, see " [Codespaces logs](/codespaces/troubleshooting/codespaces-logs)" and "[Configuring {% data variables.product.prodname_codespaces %} for your project](/github/developing-online-with-codespaces/configuring-codespaces-for-your-project#apply-changes-to-your-configuration)."

content/codespaces/troubleshooting/troubleshooting-prebuilds.md

@@ -18,11 +18,15 @@ For more information about {% data variables.product.prodname_codespaces %} preb
 
 ## Checking whether a codespace was created from a prebuild?
 
-If multiple machine types are available when you create a codespace then a dialog box is displayed giving you a choice of machine types. This will display the "{% octicon "zap" aria-label="The zap icon" %} Prebuild ready" label beside machine types for which prebuilds are available.
+When you create a codespace, you can choose the type of the virtual machine you want to use. If a prebuild is available for the type of virtual machine, "{% octicon "zap" aria-label="The zap icon" %} Prebuild ready" is shown next to it.
 
-![The dialog box for choosing a machine type](/assets/images/help/codespaces/choose-custom-machine-type.png)
+![A list of available machine types](/assets/images/help/codespaces/choose-custom-machine-type.png)
 
-If you have your {% data variables.product.prodname_codespaces %} editor preference set to "Visual Studio Code for Web" then the "Setting up your codespace" page will show the message "Prebuilt codespace found" if a prebuild is being used. Similarly, if your editor preference is "Visual Studio Code" then the integrated terminal will contain the message "You are on a prebuilt codespace defined by the prebuild configuration for your repository" when you create a new codespace. For more information, see "[Setting your default editor for Codespaces](/codespaces/customizing-your-codespace/setting-your-default-editor-for-codespaces)."
+If you have your {% data variables.product.prodname_codespaces %} editor preference set to "Visual Studio Code for Web" then the "Setting up your codespace" page will show the message "Prebuilt codespace found" if a prebuild is being used. 
+
+![The 'prebuilt codespace found' message](/assets/images/help/codespaces/prebuilt-codespace-found.png)
+
+Similarly, if your editor preference is "Visual Studio Code" then the integrated terminal will contain the message "You are on a prebuilt codespace defined by the prebuild configuration for your repository" when you create a new codespace. For more information, see "[Setting your default editor for Codespaces](/codespaces/customizing-your-codespace/setting-your-default-editor-for-codespaces)."
 
 After you have created a codespace you can check whether it was created from a prebuild by running the following {% data variables.product.prodname_cli %} command in the terminal:
 
@@ -42,16 +46,16 @@ cat /workspaces/.codespaces/shared/environment-variables.json | jq '.ACTION_NAME
 
 You may notice that sometimes, when you create a new codespace from a prebuild-enabled branch, the "{% octicon "zap" aria-label="The zap icon" %} Prebuild Ready" label is not displayed in the dialog box for choosing a machine type. This means that prebuilds are not currently available.
 
-By default, each time you push to a prebuild-enabled branch, the prebuild template is updated. If the push involves a change to the dev container then, while the update is in progress, the "{% octicon "zap" aria-label="The zap icon" %} Prebuild Ready" label is removed from the machine types dialog box. During this time you can still create codespaces without a prebuild template. If required, you can reduce the occasions on which prebuilds are unavailable for a repository by setting the prebuild template to be updated only when you make a change to your dev container configuration files, or only on a custom schedule. For more information, see "[Configuring prebuilds](/codespaces/prebuilding-your-codespaces/configuring-prebuilds#configuring-a-prebuild)."
+By default, each time you push to a prebuild-enabled branch, the prebuild template is updated. If the push involves a change to the dev container configuration then, while the update is in progress, the "{% octicon "zap" aria-label="The zap icon" %} Prebuild Ready" label is removed from the list of machine types. During this time you can still create codespaces without a prebuild template. If required, you can reduce the occasions on which prebuilds are unavailable for a repository by setting the prebuild template to be updated only when you make a change to your dev container configuration files, or only on a custom schedule. For more information, see "[Configuring prebuilds](/codespaces/prebuilding-your-codespaces/configuring-prebuilds#configuring-a-prebuild)."
 
-If your branch is not specifically enabled for prebuilds it may still benefit from prebuilds if it was branched from a prebuild-enabled branch. However, if the dev container configuration is changed on your branch, so that it's not the same as the dev container configuration on the base branch, prebuilds will no longer be available on your branch.
+If your branch is not specifically enabled for prebuilds it may still benefit from prebuilds if it was branched from a prebuild-enabled branch. However, if the dev container configuration is changed on your branch, so that it's not the same as the configuration on the base branch, prebuilds will no longer be available on your branch.
 
 Here are things to check if the "{% octicon "zap" aria-label="The zap icon" %} Prebuild Ready" label is not displayed for a particular branch:
 
 * Confirm that a prebuild configuration exists for this branch. If you’re not a repository administrator, you'll need to reach out to one to confirm this. 
 * Confirm that the prebuild configuration includes your region.
 * Check whether a change to the dev container configuration was pushed to the prebuild-enabled branch recently. If so, you will typically have to wait until the prebuild workflow run for this push completes before prebuilds are available again.
-* If no configuration changes were recently made, go to the **Actions** tab of your repository, click **{% octicon "codespaces" aria-label="The Codespaces icon" %} {% data variables.product.prodname_codespaces %} Prebuilds** in the workflows list, and check that prebuild workflow runs for the branch are succeeding. If latest runs of a workflow failed, and one or more of these failed runs contained changes to the dev container, then there will be no available prebuilds for the associated branch. 
+* If no configuration changes were recently made, go to the **Actions** tab of your repository, click **{% octicon "codespaces" aria-label="The Codespaces icon" %} {% data variables.product.prodname_codespaces %} Prebuilds** in the workflows list, and check that prebuild workflow runs for the branch are succeeding. If latest runs of a workflow failed, and one or more of these failed runs contained changes to the dev container configuration, then there will be no available prebuilds for the associated branch. 
 
 ## Further reading
 

data/reusables/codespaces/codespaces-machine-type-availability.md

@@ -1,5 +1 @@
-   {% note %}
+Your choice of available machine types may be limited by a policy configured for your organization, or by a minimum machine type specification for your repository. For more information, see "[Restricting access to machine types](/codespaces/managing-codespaces-for-your-organization/restricting-access-to-machine-types)" and "[Setting a minimum specification for codespace machines](/codespaces/setting-up-your-project-for-codespaces/setting-a-minimum-specification-for-codespace-machines)."
-
-   **Note**: Your choice of available machine types may be limited by a policy configured for your organization, or by a minimum machine type specification for your repository. For more information, see "[Restricting access to machine types](/codespaces/managing-codespaces-for-your-organization/restricting-access-to-machine-types)" and "[Setting a minimum specification for codespace machines](/codespaces/setting-up-your-project-for-codespaces/setting-a-minimum-specification-for-codespace-machines)."
-
-   {% endnote %}

data/reusables/codespaces/codespaces-machine-types.md

@@ -1 +1,3 @@
-You can run your codespace on a choice of remote machine, from 2 cores to 32 cores. Each of these has a different level of resources and a different billing tier. For information, see "[About billing for Codespaces](/github/developing-online-with-codespaces/about-billing-for-codespaces)."
+Typically, you can run your codespace on a choice of remote machine, from 2 cores to 32 cores. Each of these has a different level of resources and a different billing tier. For information, see "[About billing for Codespaces](/github/developing-online-with-codespaces/about-billing-for-codespaces)."
+
+By default the machine type with the lowest valid resources is used when you create a codespace. 

data/reusables/codespaces/creating-a-codespace-in-vscode.md

@@ -1,11 +1,17 @@
-After you connect your account on {% data variables.product.product_location %} to the {% data variables.product.prodname_github_codespaces %} extension, you can create a new codespace.
+After you connect your account on {% data variables.product.product_location %} to the {% data variables.product.prodname_github_codespaces %} extension, you can create a new codespace. For more information about the {% data variables.product.prodname_github_codespaces %} extension, see the [{% data variables.product.prodname_vscode %} marketplace](https://marketplace.visualstudio.com/items?itemName=GitHub.codespaces).
+
+{% note %}
+
+**Note**: Currently, {% data variables.product.prodname_vscode %} doesn't allow you to choose a dev container configuration when you create a codespace. If you want to choose a specific dev container configuration, use the {% data variables.product.prodname_dotcom %} web interface to create your codespace. For more information, click the **Web browser** tab at the top of this page.
+
+{% endnote %}
 
 {% data reusables.codespaces.click-remote-explorer-icon-vscode %}
-2. Click the Add icon, then click **Create New Codespace**.
+2. Click the Add icon: {% octicon "plus" aria-label="The plus icon" %}.
 
    ![The Create new Codespace option in {% data variables.product.prodname_codespaces %}](/assets/images/help/codespaces/create-codespace-vscode.png)
 
-3. Type, then click the repository's name you want to develop in.
+3. Type the name of the repository you want to develop in, then select it.
 
    ![Searching for repository to create a new {% data variables.product.prodname_codespaces %}](/assets/images/help/codespaces/choose-repository-vscode.png)
 
@@ -13,8 +19,12 @@ After you connect your account on {% data variables.product.product_location %}
 
    ![Searching for a branch to create a new {% data variables.product.prodname_codespaces %}](/assets/images/help/codespaces/choose-branch-vscode.png)
 
-5. Click the machine type you want to develop in.
+5. Click the machine type you want to use.
 
    ![Instance types for a new {% data variables.product.prodname_codespaces %}](/assets/images/help/codespaces/choose-sku-vscode.png)
 
-   {% data reusables.codespaces.codespaces-machine-type-availability %}
+   {% note %}
+
+   **Note**: {% data reusables.codespaces.codespaces-machine-type-availability %}
+
+   {% endnote %}

data/reusables/codespaces/customize-vcpus-and-ram.md

@@ -0,0 +1,5 @@
+You can customize your codespace by adjusting the amount of vCPUs and RAM, [adding dotfiles to personalize your environment](/codespaces/setting-up-your-codespace/personalizing-codespaces-for-your-account), or by modifying the tools and scripts installed.
+
+{% data variables.product.prodname_codespaces %} uses a file called `devcontainer.json` to configure the development container that you use when you work in a codespace. Each repository can contain one or more  `devcontainer.json` files, to give you exactly the development environment you need to work on your code in a codespace. 
+
+On launch, {% data variables.product.prodname_codespaces %} uses a `devcontainer.json` file, and any dependent files that make up the dev container configuration, to install tools and runtimes, and perform other setup tasks that the project requires. For more information, see "[Introduction to dev containers](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)."

data/reusables/codespaces/deleting-a-codespace-in-vscode.md

@@ -1,4 +1,7 @@
-1. Under "Codespaces", right-click the codespace you want to delete.
+You can delete codespaces from within {% data variables.product.prodname_vscode %} when you are not currently working in a codespace.
-2. In the drop-down menu, click **Delete Codespace**.
+
+{% data reusables.codespaces.click-remote-explorer-icon-vscode %}
+1. Under "GITHUB CODESPACES", right-click the codespace you want to delete.
+1. Click **Delete Codespace**.
 
    ![Deleting a codespace in {% data variables.product.prodname_dotcom %}](/assets/images/help/codespaces/delete-codespace-vscode.png)

data/reusables/codespaces/devcontainer-location.md

@@ -1 +0,0 @@
-This file can be located in the root of the repository or in a folder called `.devcontainer`. If the file is located in the root of the repository, the filename must begin with a period: `.devcontainer.json`.

data/reusables/codespaces/more-info-devcontainer.md

@@ -0,0 +1 @@
+For information about the settings and properties that you can set in a `devcontainer.json` file, see "[devcontainer.json reference](https://aka.ms/vscode-remote/devcontainer.json)" in the {% data variables.product.prodname_vscode %} documentation.

data/reusables/codespaces/next-steps-adding-devcontainer.md

@@ -0,0 +1,3 @@
+- [Managing encrypted secrets for {% data variables.product.prodname_codespaces %}](/codespaces/working-with-your-codespace/managing-encrypted-secrets-for-codespaces)
+- [Managing GPG verification for {% data variables.product.prodname_codespaces %}](/codespaces/working-with-your-codespace/managing-gpg-verification-for-codespaces)
+- [Forwarding ports in your codespace](/codespaces/developing-in-codespaces/forwarding-ports-in-your-codespace)

data/reusables/codespaces/prebuilds-not-available.md

@@ -0,0 +1 @@
+Prebuilds are not available if you choose to use a `devcontainer.json` file from a `.devcontainer/SUBDIRECTORY` location when you create a codespace. For information about choosing a `devcontainer.json` file, see "[Creating a codespace](/codespaces/developing-in-codespaces/creating-a-codespace#creating-a-codespace)."

data/reusables/codespaces/rebuild-reason.md

@@ -0,0 +1 @@
+Rebuilding inside your codespace ensures your changes work as expected before you commit the changes to the repository. If something does result in a failure, you’ll be placed in a codespace with a recovery container that you can rebuild from to keep adjusting your container.

data/reusables/codespaces/recovery-mode.md

@@ -1 +1 @@
-If changes to your codespace's configuration cause a container error, your codespace will run in recovery mode, and you will see an error message.
+If changes to your dev container configuration cause a container error, your codespace will run in recovery mode, and you will see an error message.

data/reusables/codespaces/setup-custom-devcontainer.md

@@ -0,0 +1 @@
+To set up your repository to use a custom dev container, you will need to create one or more `devcontainer.json` files. You can add these either from a template, in {% data variables.product.prodname_vscode %}, or you can write your own. For more information on dev container configurations, see "[Introduction to dev containers](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)".