Merge branch 'main' into gdomingu-patch-1

Author: sophietheking

.gitattributes

@@ -2,5 +2,5 @@
 * text=auto
 # Explicitly declare text files we want to always be normalized and converted
 # to native line endings on checkout.
-*.md text
+*.md text diff=markdown
 *.json.br filter=lfs diff=lfs merge=lfs -text

.github/workflows/move-help-wanted-issues.yml

@@ -23,6 +23,6 @@ jobs:
     steps:
       - uses: alex-page/github-project-automation-plus@bb266ff4dde9242060e2d5418e120a133586d488
         with:
-          project: Docs team reviews
+          project: Docs open source board
           column: Help wanted
           repo-token: ${{ secrets.DOCUBOT_READORG_REPO_WORKFLOW_SCOPES }}

.github/workflows/openapi-decorate.yml

@@ -57,7 +57,7 @@ jobs:
         uses: EndBug/add-and-commit@050a66787244b10a4874a2a5f682130263edc192
         with:
           # The arguments for the `git add` command
-          add: '["lib/rest/static/apps", "lib/rest/static/decorated"]'
+          add: '["lib/rest/static/apps", "lib/rest/static/decorated", "lib/redirects/static/client-side-rest-api-redirects.json"]'
 
           # The message for the commit
           message: 'Add decorated OpenAPI schema files'

.husky/post-checkout

@@ -7,5 +7,5 @@ then
     printf >&2 "\nGitHub Docs requires Git LFS but using the 'git-lfs' on your path failed.\n"
   fi
 else
-  printf >&2 "\nGitHub Docs requires Git LFS but 'git-lfs' was not found on your path.\nLearn how to install Git LFS at <https://git.io/JBCId>.\n"
+  printf >&2 "\nGitHub Docs requires Git LFS but 'git-lfs' was not found on your path.\nLearn how to install Git LFS at <https://docs.github.com/en/github/managing-large-files/versioning-large-files/installing-git-large-file-storage>.\n"
 fi

.husky/post-commit

@@ -7,5 +7,5 @@ then
     printf >&2 "\nGitHub Docs requires Git LFS but using the 'git-lfs' on your path failed.\n"
   fi
 else
-  printf >&2 "\nGitHub Docs requires Git LFS but 'git-lfs' was not found on your path.\nLearn how to install Git LFS at <https://git.io/JBCId>.\n"
+  printf >&2 "\nGitHub Docs requires Git LFS but 'git-lfs' was not found on your path.\nLearn how to install Git LFS at <https://docs.github.com/en/github/managing-large-files/versioning-large-files/installing-git-large-file-storage>.\n"
 fi

.husky/post-merge

@@ -7,5 +7,5 @@ then
     printf >&2 "\nGitHub Docs requires Git LFS but using the 'git-lfs' on your path failed.\n"
   fi
 else
-  printf >&2 "\nGitHub Docs requires Git LFS but 'git-lfs' was not found on your path.\nLearn how to install Git LFS at <https://git.io/JBCId>.\n"
+  printf >&2 "\nGitHub Docs requires Git LFS but 'git-lfs' was not found on your path.\nLearn how to install Git LFS at <https://docs.github.com/en/github/managing-large-files/versioning-large-files/installing-git-large-file-storage>.\n"
 fi

.husky/pre-push

@@ -7,7 +7,7 @@ then
     printf >&2 "\nGitHub Docs requires Git LFS but using the 'git-lfs' on your path failed.\n"
   fi
 else
-  printf >&2 "\nGitHub Docs requires Git LFS but 'git-lfs' was not found on your path.\nLearn how to install Git LFS at <https://git.io/JBCId>.\n"
+  printf >&2 "\nGitHub Docs requires Git LFS but 'git-lfs' was not found on your path.\nLearn how to install Git LFS at <https://docs.github.com/en/github/managing-large-files/versioning-large-files/installing-git-large-file-storage>.\n"
 fi
 
 . "$(dirname "$0")/_/husky.sh"

assets/images/help/codespaces/add-constraint-dropdown-ports.png

@@ -1,4 +1,5 @@
 import { useEffect, useState } from 'react'
+import { useRouter } from 'next/router'
 import Cookies from 'js-cookie'
 import { UnderlineNav } from '@primer/react'
 import { sendEvent, EventType } from 'components/lib/events'
@@ -75,6 +76,7 @@ type Props = {
   variant?: 'subnav' | 'tabnav' | 'underlinenav'
 }
 export const ToolPicker = ({ variant = 'subnav' }: Props) => {
+  const { asPath } = useRouter()
   const { defaultTool, detectedTools } = useArticleContext()
   const [currentTool, setCurrentTool] = useState(getDefaultTool(defaultTool, detectedTools))
 
@@ -100,7 +102,7 @@ export const ToolPicker = ({ variant = 'subnav' }: Props) => {
     preserveAnchorNodePosition(document, () => {
       showToolSpecificContent(currentTool)
     })
-  }, [currentTool])
+  }, [currentTool, asPath])
 
   function onClickTool(tool: string) {
     setCurrentTool(tool)

assets/images/help/codespaces/add-constraint-dropdown-timeout.png

@@ -9,12 +9,12 @@ type Props = {
 export function RestOperationHeading({ slug, title, descriptionHTML }: Props) {
   return (
     <>
-      <h3 id={slug}>
+      <h2 id={slug}>
         <a href={`#${slug}`}>
           <LinkIcon size={16} className="m-1" />
         </a>
         {title}
-      </h3>
+      </h2>
       <div dangerouslySetInnerHTML={{ __html: descriptionHTML }} />
     </>
   )

assets/images/help/codespaces/add-constraint-dropdown.png

@@ -24,7 +24,7 @@ To access your personal dashboard once you're signed in, click the {% octicon "m
 
 ## Finding your recent activity
 
-In the "Recent activity" section of your news feed, you can quickly find and follow up with recently updated issues and pull requests you're working on. Under "Recent activity", you can preview up to 12 recent updates made in the last two weeks.
+In the "Recent activity" section of your news feed, you can quickly find and follow up with recently updated issues and pull requests you're working on. Under "Recent activity", you can preview up to 4 recent updates made in the last two weeks.
 
 {% data reusables.dashboard.recent-activity-qualifying-events %}
 

assets/images/help/codespaces/edit-timeout-constraint.png

@@ -20,14 +20,6 @@ You may want to use a dark theme to reduce power consumption on certain devices,
 
 {% ifversion fpt or ghes > 3.2 or ghae-issue-4618 or ghec %}If you have low vision, you may benefit from a high contrast theme, with greater contrast between foreground and background elements.{% endif %}{% ifversion fpt or ghae-issue-4619 or ghec %} If you have colorblindness, you may benefit from our light and dark colorblind themes.
 
-{% ifversion fpt or ghec %}
-{% note %}
-
-**Note:** The colorblind themes are currently in public beta. For more information on enabling features in public beta, see "[Exploring early access releases with feature preview](/get-started/using-github/exploring-early-access-releases-with-feature-preview)."
-
-{% endnote %}
-{% endif %}
-
 {% endif %}
 
 {% data reusables.user-settings.access_settings %}

assets/images/help/codespaces/maximum-minutes-timeout.png

@@ -65,7 +65,7 @@ The examples below demonstrate using the `fwal/setup-swift` action.
 
 ### Using multiple Swift versions
 
-You can configure your job to use a multiple versions of Swift in a build matrix.
+You can configure your job to use multiple versions of Swift in a matrix.
 
 ```yaml{:copy}
 {% data reusables.actions.actions-not-certified-by-github-comment %}

assets/images/help/desktop/branch-drop-down-pull-request-tab.png

@@ -23,7 +23,7 @@ miniTocMaxHeadingLevel: 3
 
 Contexts are a way to access information about workflow runs, runner environments, jobs, and steps. Each context is an object that contains properties, which can be strings or other objects.
 
-{% data reusables.actions.context-contents %} For example, the `matrix` context is only populated for jobs in a [build matrix](/actions/learn-github-actions/workflow-syntax-for-github-actions#jobsjob_idstrategymatrix).
+{% data reusables.actions.context-contents %} For example, the `matrix` context is only populated for jobs in a [matrix](/actions/learn-github-actions/workflow-syntax-for-github-actions#jobsjob_idstrategymatrix).
 
 You can access contexts using the expression syntax. For more information, see "[Expressions](/actions/learn-github-actions/expressions)."
 
@@ -552,19 +552,19 @@ The following example contents of the `secrets` context shows the automatic `GIT
 
 ## `strategy` context
 
-For workflows with a build matrix, the `strategy` context contains information about the matrix execution strategy for the current job.
+For workflows with a matrix, the `strategy` context contains information about the matrix execution strategy for the current job.
 
 | Property name | Type | Description |
 |---------------|------|-------------|
 | `strategy` | `object` | This context changes for each job in a workflow run. You can access this context from any job or step in a workflow. This object contains all the properties listed below. |
-| `strategy.fail-fast` | `string` | When `true`, all in-progress jobs are canceled if any job in a build matrix fails. For more information, see "[Workflow syntax for {% data variables.product.prodname_actions %}](/actions/learn-github-actions/workflow-syntax-for-github-actions#jobsjob_idstrategyfail-fast)." |
-| `strategy.job-index` | `string` | The index of the current job in the build matrix. **Note:** This number is a zero-based number. The first job's index in the build matrix is `0`. |
-| `strategy.job-total` | `string` | The total number of jobs in the build matrix. **Note:** This number **is not** a zero-based number. For example, for a build matrix with four jobs, the value of `job-total` is `4`. |
+| `strategy.fail-fast` | `string` | When `true`, all in-progress jobs are canceled if any job in a matrix fails. For more information, see "[Workflow syntax for {% data variables.product.prodname_actions %}](/actions/learn-github-actions/workflow-syntax-for-github-actions#jobsjob_idstrategyfail-fast)." |
+| `strategy.job-index` | `string` | The index of the current job in the matrix. **Note:** This number is a zero-based number. The first job's index in the matrix is `0`. |
+| `strategy.job-total` | `string` | The total number of jobs in the matrix. **Note:** This number **is not** a zero-based number. For example, for a matrix with four jobs, the value of `job-total` is `4`. |
 | `strategy.max-parallel` | `string` | The maximum number of jobs that can run simultaneously when using a `matrix` job strategy. For more information, see "[Workflow syntax for {% data variables.product.prodname_actions %}](/actions/learn-github-actions/workflow-syntax-for-github-actions#jobsjob_idstrategymax-parallel)." |
 
 ### Example contents of the `strategy` context
 
-The following example contents of the `strategy` context is from a build matrix with four jobs, and is taken from the final job. Note the difference between the zero-based `job-index` number, and `job-total` which is not zero-based.
+The following example contents of the `strategy` context is from a matrix with four jobs, and is taken from the final job. Note the difference between the zero-based `job-index` number, and `job-total` which is not zero-based.
 
 ```yaml
 {
@@ -577,7 +577,7 @@ The following example contents of the `strategy` context is from a build matrix
 
 ### Example usage of the `strategy` context
 
-This example workflow uses the `strategy.job-index` property to set a unique name for a log file for each job in a build matrix.
+This example workflow uses the `strategy.job-index` property to set a unique name for a log file for each job in a matrix.
 
 ```yaml{:copy}
 name: Test matrix
@@ -602,18 +602,18 @@ jobs:
 
 ## `matrix` context
 
-For workflows with a build matrix, the `matrix` context contains the matrix properties defined in the workflow file that apply to the current job. For example, if you configure a build matrix with the `os` and `node` keys, the `matrix` context object includes the `os` and `node` properties with the values that are being used for the current job.
+For workflows with a matrix, the `matrix` context contains the matrix properties defined in the workflow file that apply to the current job. For example, if you configure a matrix with the `os` and `node` keys, the `matrix` context object includes the `os` and `node` properties with the values that are being used for the current job.
 
 There are no standard properties in the `matrix` context, only those which are defined in the workflow file.
 
 | Property name | Type | Description |
 |---------------|------|-------------|
-| `matrix` | `object` | This context is only available for jobs in a build matrix, and changes for each job in a workflow run. You can access this context from any job or step in a workflow. This object contains the properties listed below. |
+| `matrix` | `object` | This context is only available for jobs in a matrix, and changes for each job in a workflow run. You can access this context from any job or step in a workflow. This object contains the properties listed below. |
 | `matrix.<property_name>` | `string` | The value of a matrix property. |
 
 ### Example contents of the `matrix` context
 
-The following example contents of the `matrix` context is from a job in a build matrix that has the `os` and `node` matrix properties defined in the workflow. The job is executing the matrix combination of an `ubuntu-latest` OS and Node.js version `16`.
+The following example contents of the `matrix` context is from a job in a matrix that has the `os` and `node` matrix properties defined in the workflow. The job is executing the matrix combination of an `ubuntu-latest` OS and Node.js version `16`.
 
 ```yaml
 {
@@ -624,7 +624,7 @@ The following example contents of the `matrix` context is from a job in a build
 
 ### Example usage of the `matrix` context
 
-This example workflow creates a build matrix with `os` and `node` keys. It uses the `matrix.os` property to set the runner type for each job, and uses the `matrix.node` property to set the Node.js version for each job.
+This example workflow creates a matrix with `os` and `node` keys. It uses the `matrix.os` property to set the runner type for each job, and uses the `matrix.node` property to set the Node.js version for each job.
 
 ```yaml{:copy}
 name: Test matrix

assets/images/help/desktop/checks-dialog.png

@@ -50,7 +50,7 @@ Both CircleCI and {% data variables.product.prodname_actions %} configure `jobs`
 
 Both CircleCI and {% data variables.product.prodname_actions %} provide a mechanism to reuse and share tasks in a workflow. CircleCI uses a concept called orbs, written in YAML, to provide tasks that people can reuse in a workflow. {% data variables.product.prodname_actions %} has powerful and flexible reusable components called actions, which you build with either JavaScript files or Docker images. You can create actions by writing custom code that interacts with your repository in any way you'd like, including integrating with {% data variables.product.product_name %}'s APIs and any publicly available third-party API. For example, an action can publish npm modules, send SMS alerts when urgent issues are created, or deploy production-ready code. For more information, see "[Creating actions](/actions/creating-actions)."
 
-CircleCI can reuse pieces of workflows with YAML anchors and aliases. {% data variables.product.prodname_actions %} supports the most common need for reusability using build matrixes. For more information about build matrixes, see "[Managing complex workflows](/actions/learn-github-actions/managing-complex-workflows/#using-a-build-matrix)."
+CircleCI can reuse pieces of workflows with YAML anchors and aliases. {% data variables.product.prodname_actions %} supports the most common need for reusability using matrices. For more information about matrices, see "[Using a matrix for your jobs](/actions/using-jobs/using-a-matrix-for-your-jobs)."
 
 ## Using Docker images
 

assets/images/help/desktop/checks-failed-dialog.png

@@ -82,9 +82,9 @@ Jenkins can run the `stages` and `steps` in parallel, while {% data variables.pr
 | ------------- | ------------- |
 | [`parallel`](https://jenkins.io/doc/book/pipeline/syntax/#parallel) | [`jobs.<job_id>.strategy.max-parallel`](/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#jobsjob_idstrategymax-parallel) |
 
-### Build matrix
+### Matrix
 
-Both {% data variables.product.prodname_actions %} and Jenkins let you use a build matrix to define various system combinations.
+Both {% data variables.product.prodname_actions %} and Jenkins let you use a matrix to define various system combinations.
 
 | Jenkins       | {% data variables.product.prodname_actions %} |
 | ------------- | ------------- |

assets/images/help/desktop/click-pull-request.png

@@ -60,9 +60,9 @@ Travis CI can use `stages` to run jobs in parallel. Similarly, {% data variables
 Travis CI and {% data variables.product.prodname_actions %} both support status badges, which let you indicate whether a build is passing or failing.
 For more information, see ["Adding a workflow status badge to your repository](/actions/managing-workflow-runs/adding-a-workflow-status-badge)."
 
-### Using a build matrix
+### Using a matrix
 
-Travis CI and {% data variables.product.prodname_actions %} both support a build matrix, allowing you to perform testing using combinations of operating systems and software packages. For more information, see "[Using a build matrix](/actions/learn-github-actions/managing-complex-workflows#using-a-build-matrix)."
+Travis CI and {% data variables.product.prodname_actions %} both support a matrix, allowing you to perform testing using combinations of operating systems and software packages. For more information, see "[Using a matrix for your jobs](/actions/using-jobs/using-a-matrix-for-your-jobs)."
 
 Below is an example comparing the syntax for each system:
 

assets/images/help/desktop/mac-enable-notifications.png

@@ -13,7 +13,7 @@ children:
   - /using-jobs-in-a-workflow
   - /choosing-the-runner-for-a-job
   - /using-conditions-to-control-job-execution
-  - /using-a-build-matrix-for-your-jobs
+  - /using-a-matrix-for-your-jobs
   - /using-concurrency
   - /using-environments-for-jobs
   - /running-jobs-in-a-container

assets/images/help/desktop/pull-request-checks-failed-notification.png

@@ -0,0 +1,60 @@
+---
+title: Using a matrix for your jobs
+shortTitle: Using a matrix
+intro: Create a matrix to define variations for each job.
+versions:
+  fpt: '*'
+  ghes: '*'
+  ghae: '*'
+  ghec: '*'
+miniTocMaxHeadingLevel: 4
+redirect_from:
+  - /actions/using-jobs/using-a-build-matrix-for-your-jobs
+---
+
+{% data reusables.actions.enterprise-beta %}
+{% data reusables.actions.enterprise-github-hosted-runners %}
+
+## About matrix strategies
+
+{% data reusables.actions.jobs.about-matrix-strategy %}
+
+## Using a matrix strategy
+
+{% data reusables.actions.jobs.using-matrix-strategy %}
+
+### Example: Using a single-dimension matrix
+
+{% data reusables.actions.jobs.single-dimension-matrix %}
+
+### Example: Using a multi-dimension matrix
+
+{% data reusables.actions.jobs.multi-dimension-matrix %}
+
+### Example: Using contexts to create matrices
+
+{% data reusables.actions.jobs.matrix-from-context %}
+
+## Expanding or adding matrix configurations
+
+{% data reusables.actions.jobs.matrix-include %}
+
+### Example: Expanding configurations
+
+{% data reusables.actions.jobs.matrix-expand-with-include %}
+
+### Example: Adding configurations
+
+{% data reusables.actions.jobs.matrix-add-with-include %}
+
+## Excluding matrix configurations
+
+{% data reusables.actions.jobs.matrix-exclude %}
+
+## Handling failures
+
+{% data reusables.actions.jobs.section-using-a-build-matrix-for-your-jobs-failfast %}
+
+## Defining the maximum number of concurrent jobs
+
+{% data reusables.actions.jobs.section-using-a-build-matrix-for-your-jobs-max-parallel %}