Codespaces: fix things raised in OS feedback (#37363)

Co-authored-by: github-actions <github-actions@github.com>
Co-authored-by: Ben Ahmady <32935794+subatoi@users.noreply.github.com>

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

@@ -57,6 +57,8 @@ For information on choosing a machine type when you create a codespace, see "[AU
 
 {% cli %}
 
+{% data reusables.codespaces.using-github-cli %}
+
 You can use the `gh codespace edit --machine MACHINE-TYPE-NAME` {% data variables.product.prodname_cli %} command to change the machine type of a codespace. To use this command, you'll first need to find out the available machine types for your codespace.
 
 1. To view your list of codespaces, in a terminal, enter the following command.

content/codespaces/customizing-your-codespace/configuring-automatic-deletion-of-your-codespaces.md

@@ -94,6 +94,8 @@ Codespaces that you have exempted from automatic deletion are indicated in your
 
 ## Setting a retention period for a codespace
 
+{% data reusables.codespaces.using-github-cli %}
+
 To set the codespace retention period when you create a codespace, use the `--retention-period` flag with the `codespace create` subcommand. Specify the period in days. The period must be between 0 and 30 days.
 
 ```shell

content/codespaces/customizing-your-codespace/renaming-a-codespace.md

@@ -48,9 +48,9 @@ Changing the display name of a codespace can be useful if you have multiple code
 
 {% cli %}
 
-You can change the display name for your codespace by using the {% data variables.product.prodname_cli %}.
+{% data reusables.codespaces.using-github-cli %}
 
-To rename a codespace, use the `gh codespace edit` subcommand:
+To change the display name of a codespace, use the `gh codespace edit` subcommand:
 
 ```shell
 gh codespace edit -c PERMANENT-CODESPACE-NAME -d NEW-DISPLAY-NAME

content/codespaces/developing-in-codespaces/forwarding-ports-in-your-codespace.md

@@ -63,8 +63,8 @@ By default, {% data variables.product.prodname_github_codespaces %} forwards por
 {% data reusables.codespaces.using-tools-to-access-ports-1 %}
 {% data reusables.codespaces.find-address-and-token %}
 {% data reusables.codespaces.using-tools-to-access-ports-2 %}
-{% data reusables.codespaces.port-forwarding-labeling-non-jetbrains %}
 {% data reusables.codespaces.port-forwarding-adding-non-jetbrains %}
+{% data reusables.codespaces.port-forwarding-labeling-non-jetbrains %}
 
 {% endwebui %}
 
@@ -97,8 +97,8 @@ By default, {% data variables.product.prodname_github_codespaces %} forwards por
 {% data reusables.codespaces.using-tools-to-access-ports-1 %}
 {% data reusables.codespaces.find-address-and-token %}
 {% data reusables.codespaces.using-tools-to-access-ports-2 %}
-{% data reusables.codespaces.port-forwarding-labeling-non-jetbrains %}
 {% data reusables.codespaces.port-forwarding-adding-non-jetbrains %}
+{% data reusables.codespaces.port-forwarding-labeling-non-jetbrains %}
 
 {% endvscode %}
 
@@ -174,11 +174,12 @@ Copy the address and paste it somewhere for later use.
    ```
 
 {% data reusables.codespaces.using-tools-to-access-ports-2 %}
+{% data reusables.codespaces.port-forwarding-adding-non-jetbrains %}
 {% data reusables.codespaces.port-forwarding-labeling-non-jetbrains %}
 
-You can see the port labels when you list the forwarded ports for a codespace. To do this, use the `gh codespace ports` command and then select a codespace.
+### Seeing port labels on the command line
 
-{% data reusables.codespaces.port-forwarding-adding-non-jetbrains %}
+You can see the port labels when you list the forwarded ports for a codespace. To do this, use the `gh codespace ports` command and then select a codespace.
 
 {% endcli %}
 

content/codespaces/developing-in-codespaces/getting-started-with-github-codespaces-for-machine-learning.md

@@ -13,7 +13,7 @@ topics:
 
 ## Introduction
 
-This guide introduces you to machine learning with {% data variables.product.prodname_github_codespaces %}. You’ll build a simple image classifier, learn about some of the tools that come preinstalled in {% data variables.product.prodname_github_codespaces %}, configure your development environment for NVIDIA CUDA, and open your codespace in JupyterLab.
+This guide introduces you to machine learning with {% data variables.product.prodname_github_codespaces %}. You’ll build a simple image classifier, learn about some of the tools that come preinstalled in {% data variables.product.prodname_github_codespaces %}, and find out how to open your codespace in JupyterLab.
 
 ## Building a simple image classifier
 
@@ -32,7 +32,7 @@ A codespace for this template will open in a web-based version of {% data variab
 
 ### Opening the image classifier notebook
 
-The default container image that's used by {% data variables.product.prodname_github_codespaces %} includes a set of machine learning libraries that are preinstalled in your codespace. For example, Numpy, pandas, SciPy, Matplotlib, seaborn, scikit-learn, Keras, PyTorch, Requests, and Plotly. For more information about the default image, see "[AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers#using-the-default-dev-container-configuration)" and [the `devcontainers/images` repository](https://github.com/devcontainers/images/tree/main/src/universal).
+The default container image that's used by {% data variables.product.prodname_github_codespaces %} includes a set of machine learning libraries that are preinstalled in your codespace. For example, Numpy, pandas, SciPy, Matplotlib, seaborn, scikit-learn, Keras, PyTorch, Requests, and Plotly. For more information about the default image, see "[AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers#using-the-default-dev-container-configuration)" and the [devcontainers/images](https://github.com/devcontainers/images/tree/main/src/universal) repository].
 
 1. In the {% data variables.product.prodname_vscode_shortname %} editor, close any "Get Started" tabs that are displayed.
 1. Open the `notebooks/image-classifier.ipynb` notebook file.
@@ -53,16 +53,24 @@ The image classifier notebook contains all the code you need to download a datas
 
    ![Screenshot of the cell in the editor, with the header "Step 3: Train the network and save model."](/assets/images/help/codespaces/jupyter-notebook-step3.png)
 
-## Configuring NVIDIA CUDA for your codespace
+## Opening your codespace in JupyterLab
 
-Some software requires you to install NVIDIA CUDA to use your codespace’s GPU. Where this is the case, you can create your own custom configuration, by using a `devcontainer.json` file, and specify that CUDA should be installed. For more information on creating a custom configuration, see "[AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers#creating-a-custom-dev-container-configuration)."
+You can open your codespace in JupyterLab from the "Your codespaces" page at [github.com/codespaces](https://github.com/codespaces), or by using {% data variables.product.prodname_cli %}. For more information, see "[AUTOTITLE](/codespaces/developing-in-codespaces/opening-an-existing-codespace)."
+
+{% data reusables.codespaces.jupyterlab-installed-in-codespace %}
+
+## Configuring NVIDIA CUDA for your codespace
 
 {% note %}
 
-**Note**: For full details of the script that's run when you add the `nvidia-cuda` feature, see [the devcontainers/features repository](https://github.com/devcontainers/features/tree/main/src/nvidia-cuda).
+**Note**: This section only applies to customers who can create codespaces on machines that use a GPU. The ability to choose a machine type that uses a GPU was offered to selected customers during a trial period. This option is not generally available.
 
 {% endnote %}
 
+Some software requires you to install NVIDIA CUDA to use your codespace’s GPU. Where this is the case, you can create your own custom configuration, by using a `devcontainer.json` file, and specify that CUDA should be installed. For more information on creating a custom configuration, see "[AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers#creating-a-custom-dev-container-configuration)."
+
+For full details of the script that's run when you add the `nvidia-cuda` feature, see the [devcontainers/features](https://github.com/devcontainers/features/tree/main/src/nvidia-cuda) repository.
+
 1. Within the codespace, open the `.devcontainer/devcontainer.json` file in the editor.
 1. Add a top-level `features` object with the following contents:
 
@@ -100,9 +108,3 @@ Some software requires you to install NVIDIA CUDA to use your codespace’s GPU.
 {% data reusables.codespaces.rebuild-command %}
    The codespace container will be rebuilt. This will take several minutes. When the rebuild is complete the codespace is automatically reopened.
 1. Publish your change to a repository so that CUDA will be installed in any new codespaces you create from this repository in future. For more information, see "[AUTOTITLE](/codespaces/developing-in-codespaces/creating-a-codespace-from-a-template#publishing-from-vs-code)."
-
-## Opening your codespace in JupyterLab
-
-You can open your codespace in JupyterLab from the "Your codespaces" page at [github.com/codespaces](https://github.com/codespaces), or by using {% data variables.product.prodname_cli %}. For more information, see "[AUTOTITLE](/codespaces/developing-in-codespaces/opening-an-existing-codespace)."
-
-{% data reusables.codespaces.jupyterlab-installed-in-codespace %}

content/codespaces/developing-in-codespaces/opening-an-existing-codespace.md

@@ -106,6 +106,8 @@ You can also access the commands listed above by navigating to the Remote Explor
 
 ## Reopening an existing codespace
 
+{% data reusables.codespaces.using-github-cli %}
+
 1. In a terminal, enter one of the following {% data variables.product.prodname_cli %} commands.
    - To open a codespace in {% data variables.product.prodname_vscode_shortname %}, enter:
 

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

@@ -14,6 +14,8 @@ redirect_from:
   - /codespaces/developing-in-codespaces/using-codespaces-for-pull-requests
 ---
 
+Using a codespace to work on a pull request gives you all the benefits of {% data variables.product.prodname_github_codespaces %}. For more information, see "[AUTOTITLE](/codespaces/overview#benefits-of-github-codespaces)."
+
 ## About pull requests in {% data variables.product.prodname_github_codespaces %}
 
 {% data variables.product.prodname_github_codespaces %} provides you with many of the capabilities you might need to work with pull requests:

content/codespaces/developing-in-codespaces/using-github-codespaces-in-your-jetbrains-ide.md

@@ -99,10 +99,11 @@ The first time you use JetBrains Gateway for {% data variables.product.prodname_
    ![Screenshot of the Gateway with the "Connect to {% data variables.product.prodname_codespaces %}" button.](/assets/images/help/codespaces/jetbrains-gateway-connect.png)
 
 1. In the "Welcome to JetBrains Gateway" dialog, click **Sign In with {% data variables.product.prodname_dotcom %}**.
-1. Click the icon beside the one-time code to copy it, then click the login link.
+1. Click the icon beside the one-time code to copy it.
 
    ![Screenshot of a one-time login code. The copy icon beside the code is highlighted with a dark orange outline.](/assets/images/help/codespaces/jetbrains-gateway-login-code.png)
 
+1. Click the login link, below the login code.
 1. If you are not currently signed in to {% data variables.product.prodname_dotcom %}, the sign-in page is displayed.
    - Enter your details and click **Sign in**.
    - Verify your authentication, for example by entering a two-factor authentication code.

content/codespaces/getting-started/index.md

@@ -9,7 +9,7 @@ redirect_from:
   - /codespaces/getting-started-with-codespaces
 children:
   - /quickstart
-  - /the-codespace-lifecycle
+  - /understanding-the-codespace-lifecycle
   - /deep-dive
 ---
 

content/codespaces/getting-started/understanding-the-codespace-lifecycle.md

@@ -1,5 +1,6 @@
 ---
-title: The codespace lifecycle
+title: Understanding the codespace lifecycle
+shortTitle: The codespace lifecycle
 intro: 'You can develop in a {% data variables.product.prodname_github_codespaces %} environment and maintain your data throughout the entire codespace lifecycle.'
 versions:
   fpt: '*'
@@ -11,8 +12,15 @@ topics:
 redirect_from:
   - /codespaces/developing-in-codespaces/codespaces-lifecycle
   - /codespaces/developing-in-codespaces/the-codespace-lifecycle
+  - /codespaces/getting-started/the-codespace-lifecycle
 ---
 
+{% note %}
+
+This article explains the stages in the life of a codespace, from creation to deletion. If you have read the "[AUTOTITLE](/codespaces/getting-started/quickstart)" article and you now want to start using {% data variables.product.prodname_github_codespaces %} for your own work, see the articles under "[AUTOTITLE](/codespaces/developing-in-codespaces)."
+
+{% endnote %}
+
 ## About the lifecycle of a codespace
 
 The lifecycle of a codespace begins when you create a codespace and ends when you delete it. You can disconnect and reconnect to an active codespace without affecting its running processes. You may stop and restart a codespace without losing changes that you have made to your project.

content/codespaces/managing-your-codespaces/managing-gpg-verification-for-github-codespaces.md

@@ -36,7 +36,7 @@ For more information about managing your preferences for Settings Sync, see "[AU
 
 {% data reusables.user-settings.access_settings %}
 {% data reusables.user-settings.codespaces-tab %}
-1. Under "GPG verification," enable or disable GPG verification by selecting or deselecting **Enable**.
+1. On the page that's displayed, under "GPG verification," enable or disable GPG verification by selecting or deselecting **Enable**.
 {% data reusables.codespaces.trusted-repos-step %}
 
 {% data reusables.codespaces.gpg-in-active-codespaces %}

content/codespaces/managing-your-codespaces/managing-repository-access-for-your-codespaces.md

@@ -21,7 +21,7 @@ By default, your codespace is assigned a token scoped with `read` permission or
 
 For more information, see "[AUTOTITLE](/codespaces/codespaces-reference/security-in-github-codespaces#authentication)."
 
-If your project needs additional permissions for other repositories, you can configure this in the `devcontainer.json` file and ensure other collaborators have the right set of permissions. When permissions are listed in the `devcontainer.json` file, you will be prompted to review and authorize the additional permissions as part of codespace creation for that repository. Once you've authorized the listed permissions, {% data variables.product.prodname_github_codespaces %} will remember your choice and will not prompt you for authorization unless the permissions in the `devcontainer.json` file change.
+If your project needs additional permissions for other repositories, you can configure this in the `devcontainer.json` file, as described in ["Setting additional repository permissions"](#setting-additional-repository-permissions) later in this article. When permissions are listed in the `devcontainer.json` file, you will be prompted to review and authorize the additional permissions as part of codespace creation for that repository. Once you've authorized the listed permissions, {% data variables.product.prodname_github_codespaces %} will remember your choice and will not prompt you for authorization unless the permissions in the `devcontainer.json` file change.
 
 {% note %}
 

content/codespaces/overview.md

@@ -29,6 +29,19 @@ You can connect to your codespaces from your browser, from {% data variables.pro
 
 ![Diagram showing the relationship between a code editor and a codespace running on an Azure virtual machine.](/assets/images/help/codespaces/codespaces-diagram.png)
 
+## Benefits of {% data variables.product.prodname_github_codespaces %}
+
+Reasons for choosing to work in a codespace include:
+
+- **Use a preconfigured development environment** - You can work in a development environment that has been specifically configured for the repository. It will have all of the tools, languages, and configurations you need to work on that project. Everyone who works on that repository in a codespace will have the same environment. This reduces the likelihood of environment-related problems occurring and being difficult to debug. Each repository can have settings that will give contributors a ready-to-use, fit-for-purpose environment, and the environment on your local machine will be unchanged.
+- **Access the resources you need** - Your local computer may not have the processing power, or storage space, you need to work on a project. {% data variables.product.prodname_github_codespaces %} allows you to work remotely on a machine with adequate resources.
+- **Work anywhere** - All you need is a web browser. You can work in a codespace on your own computer, on a friend's laptop, or on a tablet. Open your codespace and pick up from where you left off on a different device.
+- **Choose your editor** - Work in the browser in the {% data variables.product.prodname_vscode_shortname %} web client, or choose from a selection of desktop-based applications.
+- **Work on multiple projects** - You can use multiple codespaces to work on separate projects, or on different branches of the same repository, compartmentalizing your work to avoid changes made for one piece of work accidentally affecting something else you're working on.
+- **Pair program with a teammate** - If you work on a codespace in {% data variables.product.prodname_vscode_shortname %}, you can use Live Share to work collaboratively with other people on your team. For more information, see "[AUTOTITLE](/codespaces/developing-in-codespaces/working-collaboratively-in-a-codespace)."
+- **Publish your web app from a codespace** - Forward a port from your codespace and then share the URL, to allow teammates to try out the changes you've made to the application before you submit those changes in a pull request.
+- **Try out a framework** - {% data variables.product.prodname_github_codespaces %} reduces the setup time when you want to learn a new framework. Just create a codespace from one of the [quickstart templates](https://github.com/codespaces/templates).
+
 ## Using {% data variables.product.prodname_github_codespaces %}
 
 To begin developing using cloud-based compute resources, you can create a codespace from a template or from any branch or commit in a repository. When you create a codespace from a template, you can start from a blank template or choose a template suitable for the work you're doing.

data/reusables/codespaces/port-forwarding-adding-non-jetbrains.md

@@ -1,12 +1,14 @@
-## Adding a port to the codespace configuration
+## Automatically forwarding a port
 
-You can add a forwarded port to the {% data variables.product.prodname_github_codespaces %} configuration for the repository, so the port will automatically be forwarded for all codespaces created from the repository. After you update the configuration, any previously created codespaces must be rebuilt for the change to apply. For more information, see "[AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers#applying-configuration-changes-to-a-codespace)."
+You can add a forwarded port to the {% data variables.product.prodname_github_codespaces %} configuration for the repository, so that the port will be automatically forwarded for all codespaces created from the repository. After you update the configuration, any previously created codespaces must be rebuilt for the change to apply. For more information about the dev container configuration file, see "[AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers#applying-configuration-changes-to-a-codespace)."
 
-You can manually configure forwarded ports in a `.devcontainer.json` file using the `forwardPorts` property, or you can use the "Ports" panel in a codespace that you've opened in the browser or the {% data variables.product.prodname_vscode_shortname %} desktop application.
+1. In your codespace, open the dev container configuration file you want to update. Typically this file is `.devcontainer/devcontainer.json`.
+1. Add the `forwardPorts` property.
 
-{% data reusables.codespaces.navigate-to-ports-tab %}
-1. Right click the port you want to add to the codespace configuration, then click **Set Label and Update devcontainer.json**.
+   ```json
+   "forwardPorts": [NUMBER],
+   ```
 
-   ![Screenshot of the pop-up menu for a forwarded port, with the "Set Label and Update devcontainer.json" option highlighted with an orange outline.](/assets/images/help/codespaces/update-devcontainer-to-add-port-option.png)
+   Replace `NUMBER` with the port number you want to forward. This can be a comma-separated list of port numbers.
 
-{% data reusables.codespaces.type-port-label %}
+1. Save the file.

data/reusables/codespaces/port-forwarding-intro-non-jetbrains.md

@@ -1,6 +1,6 @@
 When an application running inside a codespace prints output to the terminal that contains a localhost URL, such as `http://localhost:PORT` or `http://127.0.0.1:PORT`, the port is automatically forwarded. If you're using {% data variables.product.prodname_github_codespaces %} in the browser or in {% data variables.product.prodname_vscode %}, the URL string in the terminal is converted into a link that you can click to view the web page on your local machine. By default, {% data variables.product.prodname_github_codespaces %} forwards ports using HTTP.
 
-You can also forward a port manually, label forwarded ports, share forwarded ports with members of your organization, share forwarded ports publicly, and add forwarded ports to the codespace configuration.
+You can edit the dev container configuration for the repository to automatically forward one or more ports. You can also forward a port manually, label forwarded ports, share forwarded ports with members of your organization, share forwarded ports publicly, and add forwarded ports to the codespace configuration.
 
 {% note %}
 

data/reusables/codespaces/port-forwarding-labeling-non-jetbrains.md

@@ -3,5 +3,36 @@
 When you open a codespace in the browser, or in the {% data variables.product.prodname_vscode_shortname %} desktop application, you can label a forwarded port to make it easier to identify in a list.
 
 {% data reusables.codespaces.navigate-to-ports-tab %}
-1. Hover over the port you want to label, then click the label icon.
+1. Right-click the port you want to label, then click **Set Port Label**.
+
+   ![Screenshot of the pop-up menu for a forwarded port, with the "Set Port Label" option highlighted with an orange outline.](/assets/images/help/codespaces/set-port-label.png)
+
 {% data reusables.codespaces.type-port-label %}
+
+### Automatically labeling a forwarded port
+
+You can label a port and write the change to a dev container configuration file for the repository. If you do this for a port that is automatically forwarded, using the `forwardPorts` property, then the label will be automatically applied to that forwarded port for all future codespaces created from the repository using that configuration file.
+
+{% data reusables.codespaces.navigate-to-ports-tab %}
+1. Right-click the port whose label attribute you want to add to the codespace configuration, then click **Set Label and Update devcontainer.json**.
+
+   ![Screenshot of the pop-up menu for a forwarded port, with the "Set Label and Update devcontainer.json" option highlighted with an orange outline.](/assets/images/help/codespaces/update-devcontainer-to-add-port-option.png)
+
+{% data reusables.codespaces.type-port-label %}
+1. If your repository has more than one dev container configuration file, you will be prompted to choose which file you want to update.
+
+   The dev container configuration file is updated to include the new label in the `portsAttributes` property. For example:
+
+   ```json
+   // Use 'forwardPorts' to make a list of ports inside the container available locally.
+   "forwardPorts": [3333, 4444],
+
+   "portsAttributes": {
+     "3333": {
+       "label": "app-standard-preview"
+     },
+     "4444": {
+       "label": "app-pro-preview"
+     }
+   }
+   ```

data/reusables/codespaces/stopping-a-codespace.md

@@ -1,4 +1,4 @@
-You can stop a codespace at any time. When you stop a codespace, any running processes are stopped and the terminal history is cleared. Any saved changes in your codespace will still be available when you next start it. If you do not explicitly stop a codespace, it will continue to run until it times out from inactivity. For more information, see "[AUTOTITLE](/codespaces/getting-started/the-codespace-lifecycle#timeouts-for-github-codespaces)."
+You can stop a codespace at any time. When you stop a codespace, any running processes are stopped and the terminal history is cleared. Any saved changes in your codespace will still be available when you next start it. If you do not explicitly stop a codespace, it will continue to run until it times out from inactivity. Closing a codespace does not stop the codespace. For example, if you're using a codespace in the {% data variables.product.prodname_vscode_shortname %} web client and you close the browser tab, the codespace remains running on the remote machine. For information about timeouts, see "[AUTOTITLE](/codespaces/getting-started/the-codespace-lifecycle#timeouts-for-github-codespaces)."
 
 Only running codespaces incur CPU charges. A stopped codespace incurs only storage costs.
 

data/reusables/codespaces/using-github-cli.md

@@ -0,0 +1 @@
+If you have installed {% data variables.product.prodname_cli %}, you can use it to work with {% data variables.product.prodname_github_codespaces %}. {% data reusables.cli.cli-installation %}