Merge pull request #40208 from github/repo-sync

Repo sync

Author: docs-bot

content/copilot/concepts/code-review/code-review.md

@@ -57,6 +57,10 @@ When you reach your monthly quota you will not be able to get a code review from
   * Premium feature. Uses one premium request from your monthly quota per review.
   * Supports custom instructions and custom coding guidelines.
 
+## Providing instructions for {% data variables.product.prodname_copilot_short %} code reviews
+
+You can tailor the reviews that {% data variables.product.prodname_copilot_short %} generates by providing custom instructions. This helps {% data variables.product.prodname_copilot_short %} to review the code in a way that matches your team's coding standards, tools, and practices. See [AUTOTITLE](/copilot/how-tos/configure-custom-instructions/add-repository-instructions?tool=webui) and [AUTOTITLE](/copilot/how-tos/configure-custom-instructions/add-organization-instructions).
+
 ## Validating {% data variables.product.prodname_copilot_short %} code reviews
 
 {% data variables.product.prodname_copilot_short %} isn't guaranteed to spot all problems or issues in a pull request, and sometimes it will make mistakes. Always validate {% data variables.product.prodname_copilot_short %}'s feedback carefully, and supplement {% data variables.product.prodname_copilot_short %}'s feedback with a human review.

content/copilot/concepts/response-customization.md

@@ -59,13 +59,9 @@ contentType: concepts
 
 ### About repository custom instructions
 
-Repository custom instructions consist of a single file, `.github/copilot-instructions.md`, that you create in a repository.
+You can create two types of repository custom instructions for {% data variables.copilot.copilot_chat_short %} on {% data variables.product.prodname_dotcom_the_website %}:
 
-Repository custom instructions files are used for chat responses, for code review, and also by {% data variables.product.prodname_copilot_short %} when you assign it to an issue or ask it to create a pull request. Instructions included in this file can help {% data variables.product.prodname_copilot_short %} to work on files in a way that matches your team's working practices and conforms to coding standards for your project. See [AUTOTITLE](/copilot/using-github-copilot/coding-agent/about-assigning-tasks-to-copilot).
-
-{% data reusables.copilot.repository-custom-instructions-example %}
-
-{% data reusables.copilot.repository-cust-instr-code-review %}
+{% data reusables.copilot.custom-instructions-about %}
 
 {% endwebui %}
 
@@ -75,7 +71,7 @@ Repository custom instructions files are used for chat responses, for code revie
 
 There are two types of files you can use to provide context and instructions to {% data variables.copilot.copilot_chat %} in {% data variables.product.prodname_vscode_shortname %}:
 
-* **Repository custom instructions** allow you to specify repository-wide instructions and preferences, in a single file, that apply to any conversation held in the context of the repository.
+* **Repository custom instructions** allow you to specify instructions and preferences that {% data variables.product.prodname_copilot_short %} will consider when working in the context of the repository.
 * **Prompt files** (public preview) allow you to save common prompt instructions and relevant context in Markdown files (`*.prompt.md`) that you can then reuse in your chat prompts. Prompt files are only available in {% data variables.product.prodname_vscode_shortname %}.
 
 While custom instructions help to add codebase-wide context to each AI workflow, prompt files let you add instructions to a specific chat interaction.
@@ -117,7 +113,9 @@ There are two types of repository custom instructions you can use to provide con
 
 Custom instructions consist of natural language instructions and are most effective when they are short, self-contained statements. Consider the scope over which you want the instruction to apply when choosing whether to add an instruction on the personal, repository, or (if available) organization level.
 
-{% data reusables.copilot.custom-instructions-interactions-note %}
+> [!NOTE]
+> * {% data reusables.copilot.custom-instructions-chat-precedence %}
+> * {% data reusables.copilot.custom-instructions-conflict %}
 
 Here are some common use cases and examples for each type of custom instructions:
 * **Personal custom instructions:**
@@ -138,19 +136,9 @@ Here are some common use cases and examples for each type of custom instructions
 
 ## About repository custom instructions
 
-Repository custom instructions consist of a single file, `.github/copilot-instructions.md`, that you create in a repository. The instructions you add to the file should be short, self-contained statements that add context or relevant information to supplement chat questions.
-
-Common use cases include:
-
-* **Test generation.** Create instructions for test generation, such as specifying the use of a certain test framework.
-* **Code review.** Specify instructions for reviewing code, such as telling a reviewer to look for a specific error in the code.
-* **Commit message generation.** Write instructions for generating commit messages, such as format or the type of information to include.
-
-### Example
-
-{% data reusables.copilot.repository-custom-instructions-example %}
+You can create two types of repository custom instructions for use in {% data variables.product.prodname_vscode_shortname %}:
 
-{% data reusables.copilot.repository-cust-instr-code-review %}
+{% data reusables.copilot.custom-instructions-about %}
 
 ## About prompt files
 

content/copilot/how-tos/configure-custom-instructions/add-organization-instructions.md

@@ -1,7 +1,7 @@
 ---
 title: Adding organization custom instructions for GitHub Copilot
 shortTitle: Add organization instructions
-intro: 'Customize {% data variables.copilot.copilot_chat %} responses for members of your organization.'
+intro: 'Customize {% data variables.product.prodname_copilot_short %} responses for members of your organization.'
 permissions: Organization owners
 product: 'Organizations with a {% data variables.copilot.copilot_for_business %} or {% data variables.copilot.copilot_enterprise %} plan'
 versions:
@@ -15,18 +15,28 @@ redirect_from:
 contentType: how-tos
 ---
 
-{% data reusables.copilot.organization-instructions-note %}
+> [!NOTE]
+> This feature is currently in {% data variables.release-phases.public_preview %} and is subject to change.
+>
+> Organization custom instructions are currently only supported for {% data variables.copilot.copilot_chat_short %} on {% data variables.product.prodname_dotcom_the_website %} and {% data variables.copilot.copilot_code-review_short %}.
 
 For an overview of the methods you can use to customize {% data variables.copilot.copilot_chat %} responses, see [AUTOTITLE](/copilot/concepts/about-customizing-github-copilot-chat-responses?tool=webui).
 
-## About organization custom instructions for {% data variables.copilot.copilot_chat %}
+## About organization custom instructions for {% data variables.product.prodname_copilot_short %}
 
-Organization owners can add instructions for {% data variables.copilot.copilot_chat %} in order to tailor chat responses to the needs and preferences of your organization. For example, you can choose to always have {% data variables.copilot.copilot_chat_short %} respond in your company's language of choice or with a particular style. Some examples of instructions you could add are:
+Organization owners can add instructions for {% data variables.product.prodname_copilot_short %}, to tailor responses to the needs and preferences of your organization. For example, you can choose to always have {% data variables.copilot.copilot_chat_short %} respond in your company's language of choice or with a particular style.
+
+Custom instructions defined in an organization's {% data variables.product.prodname_copilot_short %} settings are used for all members of the organization, irrespective of whether they receive their {% data variables.product.prodname_copilot_short %} subscription from that organization.
+
+Some examples of instructions you could add are:
 * `Always respond in Spanish.`
 * `Do not generate code blocks in responses.`
 * `For questions related to security, use the Security Docs Knowledge Base.`
 
-{% data reusables.copilot.custom-instructions-interactions-note %}
+> [!NOTE]
+> * {% data reusables.copilot.custom-instructions-chat-precedence %}
+> * For {% data variables.copilot.copilot_code-review_short %}, the order of precedence is: instructions in any applicable `.github/instructions/NAME.instructions.md` file, then the instructions in the `.github/copilot-instructions.md` file, then the organization-level custom instructions.
+> * {% data reusables.copilot.custom-instructions-conflict %}
 
 ## Adding organization custom instructions
 

content/copilot/how-tos/configure-custom-instructions/add-personal-instructions.md

@@ -24,7 +24,9 @@ You can add custom instructions for {% data variables.copilot.copilot_chat %} in
 * `Your style is a helpful colleague, minimize explanations but provide enough context to understand the code.`
 * `Always provide examples in TypeScript.`
 
-{% data reusables.copilot.custom-instructions-interactions-note %}
+> [!NOTE]
+> * {% data reusables.copilot.custom-instructions-chat-precedence %}
+> * {% data reusables.copilot.custom-instructions-conflict %}
 
 ## Adding personal custom instructions
 

content/copilot/how-tos/configure-custom-instructions/add-repository-instructions.md

@@ -56,7 +56,11 @@ This version of this article is for using repository custom instructions in Ecli
 
 Repository custom instructions let you provide {% data variables.product.prodname_copilot_short %} with repository-specific guidance and preferences.
 
-{% data reusables.copilot.repository-custom-instructions-support %}
+Repository custom instructions are currently supported for:
+* **{% data variables.copilot.copilot_chat_short %}** in {% data variables.product.prodname_vscode_shortname %}
+* **{% data variables.copilot.copilot_chat_short %}** in {% data variables.product.prodname_vs %}, JetBrains IDEs, Xcode, Eclipse, and on the {% data variables.product.github %} website (`copilot-instructions.md` file only)
+* **{% data variables.copilot.copilot_coding_agent %}**
+* **{% data variables.copilot.copilot_code-review_short %}**
 
 ## Prerequisites for repository custom instructions
 
@@ -98,13 +102,13 @@ Repository custom instructions let you provide {% data variables.product.prodnam
 
 {% endeclipse %}
 
-## Creating a repository custom instructions file
+## Creating custom instructions
 
 {% jetbrains %}
 
-JetBrains IDEs support a single `.github/copilot-instructions.md` custom instructions file stored in the repository.
+JetBrains IDEs support a single `.github/copilot-instructions.md` custom instructions file stored in the repository, and a locally stored `global-copilot-instructions.md` file.
 
-You can create a custom instructions file in your repository using the {% data variables.product.prodname_copilot_short %} settings page, or you can create the file manually.
+You can create the `.github/copilot-instructions.md` file in your repository using the {% data variables.product.prodname_copilot_short %} settings page, or you can create the file manually.
 
 Whitespace between instructions is ignored, so the instructions can be written as a single paragraph, each on a new line, or separated by blank lines for legibility.
 
@@ -184,40 +188,31 @@ Once saved, these instructions will apply to the current project in Eclipse that
 
 {% vscode %}
 
-{% data variables.product.prodname_vscode_shortname %} supports either:
+{% data variables.product.prodname_vscode_shortname %} supports two types of repository custom instructions:
 
-* A single `.github/copilot-instructions.md` custom instructions file stored in the repository
-* One or more `.instructions.md` files stored within `.github/instructions` in the repository. Each file can specify `applyTo` frontmatter to define what files or directories its instructions apply to.
+* **Repository-wide custom instructions**, which apply to all requests made in the context of a repository.
 
-### Using a single `.github/copilot-instructions.md` file
+  These are specified in a `copilot-instructions.md` file in the `.github` directory of the repository. See [Creating repository-wide custom instructions](#creating-repository-wide-custom-instructions).
 
-1. In the root of your repository, create a file named `.github/copilot-instructions.md`.
+* **Path-specific custom instructions**, which apply to requests made in the context of files that match a specified path.
 
-   Create the `.github` directory if it does not already exist.
+  These are specified in one or more `NAME.instructions.md` files within the `.github/instructions` directory in the repository. See [Creating path-specific custom instructions](#creating-path-specific-custom-instructions).
 
-1. Add natural language instructions to the file, in Markdown format.
+  If the path you specify matches a file that {% data variables.product.prodname_copilot_short %} is working on, and a repository-wide custom instructions file also exists, then the instructions from both files are used.
 
-   Whitespace between instructions is ignored, so the instructions can be written as a single paragraph, each on a new line, or separated by blank lines for legibility.
+## Creating repository-wide custom instructions
 
-### Using one or more `.instructions.md` files
+1. In the root of your repository, create a file named `.github/copilot-instructions.md`.
 
-1. Create the `.github/instructions` directory if it does not already exist.
+   Create the `.github` directory if it does not already exist.
 
-1. Create one or more `.instructions.md` files, adding natural language instructions to the file(s).
+1. Add natural language instructions to the file, in Markdown format.
 
    Whitespace between instructions is ignored, so the instructions can be written as a single paragraph, each on a new line, or separated by blank lines for legibility.
 
-1. Specify what files or directories the instructions apply to by adding `applyTo` frontmatter to the Markdown files, using glob syntax.
+## Creating path-specific custom instructions
 
-   ```markdown
-   ---
-   applyTo: "app/models/**/*.rb"
-   ---
-
-   Add custom instructions here
-   ```
-
-   To apply the instructions to all files, use the `**` pattern.
+{% data reusables.copilot.custom-instructions-path %}
 
 {% endvscode %}
 
@@ -237,19 +232,35 @@ Once saved, these instructions will apply to the current project in Eclipse that
 
 {% webui %}
 
-**{% data variables.copilot.copilot_chat_short %}** on the {% data variables.product.github %} website, **{% data variables.copilot.copilot_coding_agent %}** and **{% data variables.copilot.copilot_code-review_short %}** support a single `.github/copilot-instructions.md` custom instructions file stored in the repository.
+You can create several types of repository custom instructions for use on {% data variables.product.prodname_dotcom_the_website %}:
+
+* **Repository-wide custom instructions** apply to all requests made in the context of a repository.
+
+  Supported by: **{% data variables.copilot.copilot_chat_short %}**, **{% data variables.copilot.copilot_coding_agent %}**, and **{% data variables.copilot.copilot_code-review_short %}**.
+
+  These are specified in a `copilot-instructions.md` file in the `.github` directory of the repository. See [Creating repository-wide custom instructions](#creating-repository-wide-custom-instructions-1).
+
+* **Path-specific custom instructions** apply to requests made in the context of files that match a specified path.
 
-In addition, **{% data variables.copilot.copilot_coding_agent %}** supports:
+  Supported by: **{% data variables.copilot.copilot_coding_agent %}** and **{% data variables.copilot.copilot_code-review_short %}**.
 
-* One or more `.instructions.md` files stored within `.github/instructions` in the repository. Each file can specify `applyTo` frontmatter to define what files or directories its instructions apply to.
-* One or more `AGENTS.md` files stored anywhere within the repository. When {% data variables.product.prodname_copilot_short %} is working, the nearest `AGENTS.md` file in the directory tree will take precedence.
-* A single `CLAUDE.md` or `GEMINI.md` file stored in the root of the repository.
+  These are specified in one or more `NAME.instructions.md` files within the `.github/instructions` directory in the repository. See [Creating path-specific custom instructions](#creating-path-specific-custom-instructions-1).
 
-### Using a single `.github/copilot-instructions.md` file
+  If the path you specify matches a file that {% data variables.product.prodname_copilot_short %} is working on, and a repository-wide custom instructions file also exists, then the instructions from both files are used.
 
-You can ask {% data variables.copilot.copilot_coding_agent %} to generate a `.github/copilot-instructions.md` file, or you can write your own instructions file.
+* **Agent instructions** are used by AI agents.
 
-#### Asking {% data variables.copilot.copilot_coding_agent %} to generate a `.github/copilot-instructions.md` file
+  Supported by: **{% data variables.copilot.copilot_coding_agent %}**.
+
+  You can create one or more `AGENTS.md` files, stored anywhere within the repository. When {% data variables.product.prodname_copilot_short %} is working, the nearest `AGENTS.md` file in the directory tree will take precedence.
+
+  Alternatively, you can use a single `CLAUDE.md` or `GEMINI.md` file stored in the root of the repository.
+
+## Creating repository-wide custom instructions
+
+You can create your own custom instructions file from scratch. See [Writing your own copilot-instructions.md file](#writing-your-own-copilot-instructionsmd-file). Alternatively, you can ask {% data variables.copilot.copilot_coding_agent %} to generate one for you.
+
+### Asking {% data variables.copilot.copilot_coding_agent %} to generate a `copilot-instructions.md` file
 
 > [!NOTE]
 > {% data reusables.copilot.coding-agent.preview-note-text %}
@@ -341,7 +352,7 @@ You can ask {% data variables.copilot.copilot_coding_agent %} to generate a `.gi
 
 {% data variables.product.prodname_copilot_short %} will start a new session, which will appear in the list below the prompt box. {% data variables.product.prodname_copilot_short %} will create a draft pull request, write your custom instructions, push them to the branch, then add you as a reviewer when it has finished, triggering a notification.
 
-#### Writing your own `.github/copilot-instructions.md` file
+### Writing your own `copilot-instructions.md` file
 
 1. In the root of your repository, create a file named `.github/copilot-instructions.md`.
 
@@ -354,25 +365,12 @@ You can ask {% data variables.copilot.copilot_coding_agent %} to generate a `.gi
 > [!TIP]
 > The first time you create a pull request in a given repository with {% data variables.copilot.copilot_coding_agent %}, {% data variables.product.prodname_copilot_short %} will leave a comment with a link to automatically generate custom instructions for the repository.
 
-### Using one or more `.instructions.md` files
-
-1. Create the `.github/instructions` directory if it does not already exist.
-
-1. Create one or more `.instructions.md` files, adding natural language instructions to the file(s).
+## Creating path-specific custom instructions
 
-   Whitespace between instructions is ignored, so the instructions can be written as a single paragraph, each on a new line, or separated by blank lines for legibility.
-
-1. Specify what files or directories the instructions apply to by adding `applyTo` frontmatter to the Markdown files, using glob syntax.
-
-   ```markdown
-   ---
-   applyTo: "app/models/**/*.rb"
-   ---
-
-   Add custom instructions here
-   ```
+> [!NOTE]
+> Currently, on {% data variables.product.prodname_dotcom_the_website %}, path-specific custom instructions are only supported for {% data variables.copilot.copilot_coding_agent %} and {% data variables.copilot.copilot_code-review_short %}.
 
-   To apply the instructions to all files, use the `**` pattern.
+{% data reusables.copilot.custom-instructions-path %}
 
 {% endwebui %}
 
@@ -459,7 +457,9 @@ Whenever repository custom instructions are used by {% data variables.copilot.co
 
 You can click the reference to open the file.
 
-{% data reusables.copilot.custom-instructions-interactions-note %}
+> [!NOTE]
+> * {% data reusables.copilot.custom-instructions-chat-precedence %}
+> * {% data reusables.copilot.custom-instructions-conflict %}
 
 {% endwebui %}