From 77cab5fd206a230fddaea26f7fa0f214a287d805 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 7 Oct 2025 21:04:22 +0000 Subject: [PATCH 1/8] Initial plan From 7a5b220ef165afda57585fd345687ba012507a88 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 7 Oct 2025 21:15:39 +0000 Subject: [PATCH 2/8] Add GitHub Copilot agents for updatexlf and fixcompletions Co-authored-by: nagilson <23152278+nagilson@users.noreply.github.com> --- .github/agents/fixcompletions.instructions.md | 150 ++++++++++++++++++ .github/agents/updatexlf.instructions.md | 68 ++++++++ 2 files changed, 218 insertions(+) create mode 100644 .github/agents/fixcompletions.instructions.md create mode 100644 .github/agents/updatexlf.instructions.md diff --git a/.github/agents/fixcompletions.instructions.md b/.github/agents/fixcompletions.instructions.md new file mode 100644 index 000000000000..b4e83537fb74 --- /dev/null +++ b/.github/agents/fixcompletions.instructions.md @@ -0,0 +1,150 @@ +# Fix Completions Tests Agent + +This agent automates the process of updating CLI completions snapshot test files when completion outputs change. + +## Trigger + +This agent is triggered when a user comments `/fixcompletions` on a pull request. + +## Description + +The dotnet CLI has snapshot-based tests for command completions across different shells (bash, zsh, powershell, etc.). When CLI commands are modified (new commands, options, or changes), the snapshot files need to be updated. This agent automates that process by: + +1. Building the repository +2. Running the completion tests to generate new `.received.` files +3. Comparing and updating the `.verified.` snapshot files +4. Committing the changes back to the PR + +## Instructions + +You are an expert at managing snapshot-based tests in .NET projects. When invoked: + +### Step 1: Build the Repository + +First, ensure the repository is built with the latest changes: + +```bash +./build.sh +``` + +This may take 5-10 minutes. Use a timeout of at least 600 seconds (10 minutes) for the build command. + +### Step 2: Run the Completion Tests + +Run the specific completion snapshot tests to generate the new `.received.` files: + +```bash +# Use the repo-local dotnet +./.dotnet/dotnet test test/dotnet.Tests/dotnet.Tests.csproj --filter "FullyQualifiedName~VerifyCompletions" +``` + +This will run the `VerifyCompletions` test which generates completion snapshots for all supported shells. + +**Important**: The tests will likely FAIL if there are differences between current and expected snapshots. This is expected and correct behavior - don't be alarmed by test failures. + +### Step 3: Compare the Snapshots + +Run the `CompareCliSnapshots` MSBuild target to copy the `.received.` files from the artifacts directory to the test project: + +```bash +cd test/dotnet.Tests +dotnet restore /t:CompareCliSnapshots +``` + +Or from the repository root: + +```bash +dotnet restore test/dotnet.Tests/ /t:CompareCliSnapshots +``` + +### Step 4: Review the Changes + +Before accepting the changes, review them to ensure they make sense: + +```bash +git status +git diff test/dotnet.Tests/CompletionTests/snapshots/ +``` + +Look for: +- New command options that were added +- Removed options (if commands were deprecated) +- Changed command descriptions +- New subcommands + +**Critical**: Only proceed if the changes match the expected modifications from the PR. + +### Step 5: Update the Verified Snapshots + +If the changes look correct, run the `UpdateCliSnapshots` target to rename `.received.` files to `.verified.`: + +```bash +cd test/dotnet.Tests +dotnet restore /t:UpdateCliSnapshots +``` + +Or from the repository root: + +```bash +dotnet restore test/dotnet.Tests/ /t:UpdateCliSnapshots +``` + +This will move/rename all `.received.*` files to `.verified.*` in the `test/dotnet.Tests/CompletionTests/snapshots/` directory. + +### Step 6: Commit the Changes + +Use the `report_progress` tool to commit and push the snapshot updates: + +- Commit message: "Update CLI completions snapshots" +- PR description: Update the checklist to show completion snapshots have been updated + +### Step 7: Verify Final State + +After committing, verify that: +1. All `.received.` files have been renamed to `.verified.` +2. No `.received.` files remain in the repository +3. Only `.verified.*` files are committed + +## Important Notes + +- **Always build before running tests** - the tests need the latest built CLI tools +- **Test failures are expected** when snapshots don't match - this is not an error +- **Review changes carefully** - snapshot updates should match the PR's intended changes +- The snapshots are in: `test/dotnet.Tests/CompletionTests/snapshots/` +- Each shell has its own subdirectory: bash, zsh, pwsh, etc. +- Only commit `.verified.*` files, never commit `.received.*` files + +## Troubleshooting + +If the build fails: +- Check the error messages carefully +- Some CI-only failures are expected and can be ignored if they're unrelated to your changes +- Report any blocking build errors to the user + +If tests timeout: +- The completion tests can be slow - allow at least 5 minutes +- If tests hang, try running them again + +If no `.received.` files are generated: +- Make sure the tests actually ran and detected differences +- Check that the build completed successfully +- The tests might have passed (no changes needed) + +## Example Workflow + +When a user comments `/fixcompletions`: + +1. Build: `./build.sh` (with 600s timeout) +2. Test: `./.dotnet/dotnet test test/dotnet.Tests/dotnet.Tests.csproj --filter "FullyQualifiedName~VerifyCompletions"` +3. Compare: `dotnet restore test/dotnet.Tests/ /t:CompareCliSnapshots` +4. Review: `git diff test/dotnet.Tests/CompletionTests/snapshots/` - verify changes are correct +5. Update: `dotnet restore test/dotnet.Tests/ /t:UpdateCliSnapshots` +6. Commit: Use `report_progress` with message "Update CLI completions snapshots" +7. Inform: Let the user know the snapshots have been updated successfully + +## References + +- See `documentation/project-docs/snapshot-based-testing.md` for more details +- Example snapshot update: https://github.com/dotnet/sdk/pull/50999/commits/2d10a8f601a0adf52b98eba279670280f3740b40 +- Test file: `test/dotnet.Tests/CompletionTests/DotnetCliSnapshotTests.cs` +- MSBuild targets: `test/dotnet.Tests/dotnet.Tests.csproj` (lines 101-113) diff --git a/.github/agents/updatexlf.instructions.md b/.github/agents/updatexlf.instructions.md new file mode 100644 index 000000000000..962c36507bc3 --- /dev/null +++ b/.github/agents/updatexlf.instructions.md @@ -0,0 +1,68 @@ +# Update XLF Files Agent + +This agent automates the process of updating XLF (XLIFF) translation files when .resx resource files are changed. + +## Trigger + +This agent is triggered when a user comments `/updatexlf` on a pull request. + +## Description + +When .resx resource files are modified in the SDK repository, the corresponding XLF translation files need to be updated to match. This agent automates that process by: + +1. Building the repository (or running the UpdateXlf MSBuild target) +2. Collecting the updated XLF files +3. Committing the changes back to the PR + +## Instructions + +You are an expert at managing localization files in .NET projects. When invoked: + +1. **Check the current state**: First, identify if there are any .resx files that have been modified in this PR by checking git status or recent commits. + +2. **Run the UpdateXlf target**: Execute the MSBuild UpdateXlf target to update all XLF files: + ```bash + msbuild /t:UpdateXlf + ``` + + If that doesn't work or if the target is not found, perform a full build which will also update XLF files: + ```bash + ./build.sh + ``` + +3. **Verify the changes**: Check which XLF files were modified: + ```bash + git status + git diff --name-only + ``` + +4. **Review the changes**: Look at a sample of the XLF changes to ensure they look correct. Properly updated XLF files should have: + - Elements with `state="needs-review-translation"` for modified strings + - Elements with `state="new"` for newly added strings + - No manual edits to translations + +5. **Commit the changes**: Use the `report_progress` tool to commit and push the XLF updates: + - Commit message: "Update XLF translation files" + - PR description: Update the checklist to show XLF files have been updated + +## Important Notes + +- **Never manually edit XLF files**. Always use the MSBuild target or build process. +- Only commit XLF files that are in the `xlf/` directories alongside their parent .resx files. +- If there are any errors during the build, report them clearly to the user. +- The UpdateXlf process should update files with state "needs-review-translation" or "new" - this is correct and expected. + +## Example Workflow + +When a user comments `/updatexlf`: + +1. Run: `msbuild /t:UpdateXlf` (or `./build.sh` if needed) +2. Check: `git status` and `git diff` to see what changed +3. Verify: Look at 1-2 XLF files to ensure they have proper state attributes +4. Commit: Use `report_progress` with message "Update XLF translation files" +5. Inform: Let the user know the XLF files have been updated successfully + +## References + +- See `documentation/project-docs/Localization.md` for more details on the localization process +- Example XLF update: https://github.com/dotnet/sdk/pull/2389/commits/edbb8ddd72e1943a73928560bd0b58a5a1d00bb7 From 61d700ff4a4569c33c69ce1f12e7b80581962e54 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 7 Oct 2025 21:18:25 +0000 Subject: [PATCH 3/8] Document GitHub Copilot automation commands Co-authored-by: nagilson <23152278+nagilson@users.noreply.github.com> --- documentation/project-docs/Localization.md | 11 +++++++ documentation/project-docs/developer-guide.md | 33 +++++++++++++++++++ .../project-docs/snapshot-based-testing.md | 12 +++++++ 3 files changed, 56 insertions(+) diff --git a/documentation/project-docs/Localization.md b/documentation/project-docs/Localization.md index 884c9fa075a3..1555d199d8f3 100644 --- a/documentation/project-docs/Localization.md +++ b/documentation/project-docs/Localization.md @@ -7,6 +7,17 @@ The local dev build automatically generates updates to the xlf files that contai When making string changes, update the resx, build, and check in all xlf file changes. Developers should never need to update the xlf files directly and should always rely on the local build for updates to those files. This will leave the files in english initially and they will get translated eventually. +#### Automated XLF Updates via GitHub Copilot + +If you've modified `.resx` files in a pull request and need to update the corresponding `.xlf` files but don't want to clone the branch locally, you can use the GitHub Copilot automation: + +**Comment `/updatexlf` on your pull request** and the Copilot agent will: +1. Run the `msbuild /t:UpdateXlf` target (or build if needed) +2. Collect all updated `.xlf` files +3. Commit the changes directly to your PR branch + +This is particularly useful when CI is failing due to outdated XLF files. + For internal folks, see https://aka.ms/allaboutloc ### Loc issues diff --git a/documentation/project-docs/developer-guide.md b/documentation/project-docs/developer-guide.md index 61fb41ea8a37..af1c0473722d 100644 --- a/documentation/project-docs/developer-guide.md +++ b/documentation/project-docs/developer-guide.md @@ -176,6 +176,39 @@ taskkill /F /IM VSTest.Console.exe /T || taskkill /F /IM msbuild.exe /T ``` +## GitHub Copilot Automation Commands + +The SDK repository includes GitHub Copilot agents that can automate common maintenance tasks directly from pull requests. These agents can be triggered by commenting specific commands on a PR. + +### `/updatexlf` - Update Translation Files + +When you modify `.resx` resource files, the corresponding `.xlf` translation files need to be updated. Instead of manually running the build locally, you can comment `/updatexlf` on the PR and the Copilot agent will: + +1. Run the `msbuild /t:UpdateXlf` target (or perform a full build if needed) +2. Collect all updated `.xlf` files +3. Commit the changes to the PR branch + +This is useful when you've changed localized strings and the CI build is failing due to outdated XLF files. + +**Example usage:** Comment `/updatexlf` on a PR where you've modified `CliStrings.resx` or other resource files. + +See also: [Localization documentation](Localization.md) + +### `/fixcompletions` - Update CLI Completion Snapshots + +The CLI includes snapshot-based tests for shell completions (bash, zsh, pwsh, etc.). When you add or modify CLI commands, these snapshots need to be updated. Comment `/fixcompletions` on the PR and the agent will: + +1. Build the repository +2. Run the completion tests to generate new snapshots +3. Compare and update the verified snapshot files +4. Commit the changes to the PR branch + +This is useful when you've added new commands or options and the `VerifyCompletions` tests are failing. + +**Example usage:** Comment `/fixcompletions` on a PR where you've modified CLI command structure. + +See also: [Snapshot-based testing documentation](snapshot-based-testing.md) + ## Adding a Command The dotnet CLI supports several models for adding new commands: diff --git a/documentation/project-docs/snapshot-based-testing.md b/documentation/project-docs/snapshot-based-testing.md index eb282a9cb174..19fee0de3b8b 100644 --- a/documentation/project-docs/snapshot-based-testing.md +++ b/documentation/project-docs/snapshot-based-testing.md @@ -13,6 +13,18 @@ To fix these tests, you need to diff the two files and visually inspect the chan * [CompareCliSnapshots][compare] - this Target copies the .received. files from the artifacts directory, where they are created due to the way we run tests, to the [snapshots][snapshots] directory in the dotnet.Tests project. This makes it much easier to diff the two. * [UpdateCliSnapshots][update] - this Target renames the .received. files to .verified. in the local [snapshots][snapshots] directory, and so acts as a giant 'I accept these changes' button. Only use this if you've diffed the snapshots and are sure they match your expectations. +### Automated Snapshot Updates via GitHub Copilot + +If you've modified CLI commands in a pull request and the completion snapshot tests are failing, but you don't want to clone the branch locally to update the snapshots, you can use the GitHub Copilot automation: + +**Comment `/fixcompletions` on your pull request** and the Copilot agent will: +1. Build the repository +2. Run the completion tests to generate new snapshots +3. Run the `CompareCliSnapshots` and `UpdateCliSnapshots` targets +4. Commit the updated verified snapshot files directly to your PR branch + +This is particularly useful when you've added new commands, options, or modified existing CLI functionality. + [dotnet.Tests]: ../../test/dotnet.Tests/ [snapshot-tests]: ../../test/dotnet.Tests/CompletionTests/DotnetCliSnapshotTests.cs [snapshots]: ../../test/dotnet.Tests/CompletionTests/snapshots/ From 7e654f818fd33eeae339f3252dd53befc0c8fe74 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 7 Oct 2025 21:19:15 +0000 Subject: [PATCH 4/8] Add README for agents directory Co-authored-by: nagilson <23152278+nagilson@users.noreply.github.com> --- .github/agents/README.md | 62 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 .github/agents/README.md diff --git a/.github/agents/README.md b/.github/agents/README.md new file mode 100644 index 000000000000..a46679e8198b --- /dev/null +++ b/.github/agents/README.md @@ -0,0 +1,62 @@ +# GitHub Copilot Agents + +This directory contains custom agent instructions for GitHub Copilot to automate common maintenance tasks in the .NET SDK repository. + +## Available Agents + +### `/updatexlf` - Update Translation Files + +Automatically updates XLF (XLIFF) translation files when .resx resource files are changed. + +**When to use:** Comment `/updatexlf` on a PR when: +- You've modified `.resx` files +- CI is failing due to outdated `.xlf` files +- You want to avoid cloning the branch locally just to update translations + +**What it does:** +1. Runs `msbuild /t:UpdateXlf` (or builds the repository if needed) +2. Collects all updated `.xlf` files +3. Commits the changes to your PR branch + +See [updatexlf.instructions.md](updatexlf.instructions.md) for detailed agent instructions. + +### `/fixcompletions` - Update CLI Completion Snapshots + +Automatically updates CLI completion snapshot test files when CLI commands are modified. + +**When to use:** Comment `/fixcompletions` on a PR when: +- You've added or modified CLI commands, options, or subcommands +- The `VerifyCompletions` tests are failing +- You want to update completion snapshots without building locally + +**What it does:** +1. Builds the repository +2. Runs the completion tests to generate new `.received.` files +3. Runs the `CompareCliSnapshots` and `UpdateCliSnapshots` MSBuild targets +4. Commits the updated `.verified.*` snapshot files to your PR branch + +See [fixcompletions.instructions.md](fixcompletions.instructions.md) for detailed agent instructions. + +## How It Works + +These agents are triggered when you comment the specific slash command on a pull request. GitHub Copilot will: + +1. Clone the PR branch into a sandbox environment +2. Execute the instructions defined in the corresponding `.instructions.md` file +3. Use the `report_progress` tool to commit and push changes back to your PR +4. Comment on the PR to confirm completion or report any errors + +## For Agent Developers + +Each agent instruction file should: +- Clearly describe the trigger command and purpose +- Provide step-by-step instructions for the automation +- Include error handling and troubleshooting guidance +- Use the `report_progress` tool to commit changes +- Reference relevant documentation and example PRs + +## Additional Resources + +- [Developer Guide](../../documentation/project-docs/developer-guide.md#github-copilot-automation-commands) +- [Localization Guide](../../documentation/project-docs/Localization.md) +- [Snapshot Testing Guide](../../documentation/project-docs/snapshot-based-testing.md) From 388e7e7371c079f37aedbc679af038d5a15e98e4 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 7 Oct 2025 21:20:57 +0000 Subject: [PATCH 5/8] Improve agent instructions with specific timeouts and commands Co-authored-by: nagilson <23152278+nagilson@users.noreply.github.com> --- .github/agents/fixcompletions.instructions.md | 4 ++-- .github/agents/updatexlf.instructions.md | 10 +++++++--- 2 files changed, 9 insertions(+), 5 deletions(-) diff --git a/.github/agents/fixcompletions.instructions.md b/.github/agents/fixcompletions.instructions.md index b4e83537fb74..8e499233da68 100644 --- a/.github/agents/fixcompletions.instructions.md +++ b/.github/agents/fixcompletions.instructions.md @@ -27,7 +27,7 @@ First, ensure the repository is built with the latest changes: ./build.sh ``` -This may take 5-10 minutes. Use a timeout of at least 600 seconds (10 minutes) for the build command. +This may take 5-10 minutes. Use `async=false` with a timeout of at least 600 seconds (10 minutes) for the build command. ### Step 2: Run the Completion Tests @@ -38,7 +38,7 @@ Run the specific completion snapshot tests to generate the new `.received.` file ./.dotnet/dotnet test test/dotnet.Tests/dotnet.Tests.csproj --filter "FullyQualifiedName~VerifyCompletions" ``` -This will run the `VerifyCompletions` test which generates completion snapshots for all supported shells. +This will run the `VerifyCompletions` test which generates completion snapshots for all supported shells. Allow at least 300 seconds (5 minutes) for this command. **Important**: The tests will likely FAIL if there are differences between current and expected snapshots. This is expected and correct behavior - don't be alarmed by test failures. diff --git a/.github/agents/updatexlf.instructions.md b/.github/agents/updatexlf.instructions.md index 962c36507bc3..7cd7032aacb6 100644 --- a/.github/agents/updatexlf.instructions.md +++ b/.github/agents/updatexlf.instructions.md @@ -20,15 +20,19 @@ You are an expert at managing localization files in .NET projects. When invoked: 1. **Check the current state**: First, identify if there are any .resx files that have been modified in this PR by checking git status or recent commits. -2. **Run the UpdateXlf target**: Execute the MSBuild UpdateXlf target to update all XLF files: +2. **Run the UpdateXlf target**: The repository is built on a Linux environment, so use the appropriate build script: + + First, try running just the UpdateXlf target (faster): ```bash - msbuild /t:UpdateXlf + ./build.sh /t:UpdateXlf ``` If that doesn't work or if the target is not found, perform a full build which will also update XLF files: ```bash ./build.sh ``` + + The build may take 5-10 minutes. Use `async=false` with a timeout of at least 600 seconds (10 minutes). 3. **Verify the changes**: Check which XLF files were modified: ```bash @@ -56,7 +60,7 @@ You are an expert at managing localization files in .NET projects. When invoked: When a user comments `/updatexlf`: -1. Run: `msbuild /t:UpdateXlf` (or `./build.sh` if needed) +1. Run: `./build.sh /t:UpdateXlf` (with 600s timeout) or `./build.sh` if needed 2. Check: `git status` and `git diff` to see what changed 3. Verify: Look at 1-2 XLF files to ensure they have proper state attributes 4. Commit: Use `report_progress` with message "Update XLF translation files" From 58f4ed246b6406c1a682600321254d4c3ef14971 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 7 Oct 2025 22:16:30 +0000 Subject: [PATCH 6/8] Relax critical review requirement in fixcompletions agent Co-authored-by: nagilson <23152278+nagilson@users.noreply.github.com> --- .github/agents/fixcompletions.instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/agents/fixcompletions.instructions.md b/.github/agents/fixcompletions.instructions.md index 8e499233da68..87d4a1c6c4bb 100644 --- a/.github/agents/fixcompletions.instructions.md +++ b/.github/agents/fixcompletions.instructions.md @@ -72,7 +72,7 @@ Look for: - Changed command descriptions - New subcommands -**Critical**: Only proceed if the changes match the expected modifications from the PR. +If the changes are obviously incorrect or the diff shows unexpected modifications, report them to the user. Otherwise, proceed with updating the snapshots - the human reviewer of the PR will verify the changes are appropriate. ### Step 5: Update the Verified Snapshots From ba600e29148d68ce633714fc83ec5e4e4df668c3 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 7 Oct 2025 22:24:22 +0000 Subject: [PATCH 7/8] Clarify agent pushes commits and simplify test filter Co-authored-by: nagilson <23152278+nagilson@users.noreply.github.com> --- .github/agents/fixcompletions.instructions.md | 21 ++++++++++--------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/.github/agents/fixcompletions.instructions.md b/.github/agents/fixcompletions.instructions.md index 87d4a1c6c4bb..865c17c9d1c2 100644 --- a/.github/agents/fixcompletions.instructions.md +++ b/.github/agents/fixcompletions.instructions.md @@ -21,7 +21,7 @@ You are an expert at managing snapshot-based tests in .NET projects. When invoke ### Step 1: Build the Repository -First, ensure the repository is built with the latest changes: +First, ensure the repository is built with the latest changes. This build will create the repo-local dotnet installation at `./.dotnet/dotnet`: ```bash ./build.sh @@ -31,14 +31,13 @@ This may take 5-10 minutes. Use `async=false` with a timeout of at least 600 sec ### Step 2: Run the Completion Tests -Run the specific completion snapshot tests to generate the new `.received.` files: +Run the completion snapshot tests to generate the new `.received.` files. After the build completes, use the repo-local dotnet that was built: ```bash -# Use the repo-local dotnet -./.dotnet/dotnet test test/dotnet.Tests/dotnet.Tests.csproj --filter "FullyQualifiedName~VerifyCompletions" +./.dotnet/dotnet test test/dotnet.Tests/dotnet.Tests.csproj --filter "Name~VerifyCompletions" ``` -This will run the `VerifyCompletions` test which generates completion snapshots for all supported shells. Allow at least 300 seconds (5 minutes) for this command. +This will run all the `VerifyCompletions` tests which generate completion snapshots for all supported shells (bash, zsh, pwsh, fish, nushell). Allow at least 300 seconds (5 minutes) for this command. **Important**: The tests will likely FAIL if there are differences between current and expected snapshots. This is expected and correct behavior - don't be alarmed by test failures. @@ -93,11 +92,13 @@ This will move/rename all `.received.*` files to `.verified.*` in the `test/dotn ### Step 6: Commit the Changes -Use the `report_progress` tool to commit and push the snapshot updates: +Use the `report_progress` tool to commit and push the snapshot updates directly to the PR branch: - Commit message: "Update CLI completions snapshots" - PR description: Update the checklist to show completion snapshots have been updated +The `report_progress` tool will automatically stage all changes, create a commit, and push to the origin branch that this PR is based on. + ### Step 7: Verify Final State After committing, verify that: @@ -134,12 +135,12 @@ If no `.received.` files are generated: When a user comments `/fixcompletions`: -1. Build: `./build.sh` (with 600s timeout) -2. Test: `./.dotnet/dotnet test test/dotnet.Tests/dotnet.Tests.csproj --filter "FullyQualifiedName~VerifyCompletions"` +1. Build: `./build.sh` (with 600s timeout) - creates `./.dotnet/dotnet` +2. Test: `./.dotnet/dotnet test test/dotnet.Tests/dotnet.Tests.csproj --filter "Name~VerifyCompletions"` (with 300s timeout) 3. Compare: `dotnet restore test/dotnet.Tests/ /t:CompareCliSnapshots` -4. Review: `git diff test/dotnet.Tests/CompletionTests/snapshots/` - verify changes are correct +4. Review: `git diff test/dotnet.Tests/CompletionTests/snapshots/` - check for unexpected issues 5. Update: `dotnet restore test/dotnet.Tests/ /t:UpdateCliSnapshots` -6. Commit: Use `report_progress` with message "Update CLI completions snapshots" +6. Commit: Use `report_progress` with message "Update CLI completions snapshots" - this commits and pushes to the PR branch 7. Inform: Let the user know the snapshots have been updated successfully ## References From d223f7c3660a1e9ba8f9c11c7ec2e5f5f783a2f4 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 10 Oct 2025 18:32:33 +0000 Subject: [PATCH 8/8] Replace Copilot agent instructions with GitHub Actions workflows Co-authored-by: nagilson <23152278+nagilson@users.noreply.github.com> --- .github/agents/README.md | 62 ------- .github/agents/fixcompletions.instructions.md | 151 ---------------- .github/agents/updatexlf.instructions.md | 72 -------- .../workflows/fix-completions-on-comment.yml | 167 ++++++++++++++++++ .github/workflows/update-xlf-on-comment.yml | 152 ++++++++++++++++ documentation/project-docs/Localization.md | 12 +- documentation/project-docs/developer-guide.md | 26 ++- .../project-docs/snapshot-based-testing.md | 6 +- 8 files changed, 339 insertions(+), 309 deletions(-) delete mode 100644 .github/agents/README.md delete mode 100644 .github/agents/fixcompletions.instructions.md delete mode 100644 .github/agents/updatexlf.instructions.md create mode 100644 .github/workflows/fix-completions-on-comment.yml create mode 100644 .github/workflows/update-xlf-on-comment.yml diff --git a/.github/agents/README.md b/.github/agents/README.md deleted file mode 100644 index a46679e8198b..000000000000 --- a/.github/agents/README.md +++ /dev/null @@ -1,62 +0,0 @@ -# GitHub Copilot Agents - -This directory contains custom agent instructions for GitHub Copilot to automate common maintenance tasks in the .NET SDK repository. - -## Available Agents - -### `/updatexlf` - Update Translation Files - -Automatically updates XLF (XLIFF) translation files when .resx resource files are changed. - -**When to use:** Comment `/updatexlf` on a PR when: -- You've modified `.resx` files -- CI is failing due to outdated `.xlf` files -- You want to avoid cloning the branch locally just to update translations - -**What it does:** -1. Runs `msbuild /t:UpdateXlf` (or builds the repository if needed) -2. Collects all updated `.xlf` files -3. Commits the changes to your PR branch - -See [updatexlf.instructions.md](updatexlf.instructions.md) for detailed agent instructions. - -### `/fixcompletions` - Update CLI Completion Snapshots - -Automatically updates CLI completion snapshot test files when CLI commands are modified. - -**When to use:** Comment `/fixcompletions` on a PR when: -- You've added or modified CLI commands, options, or subcommands -- The `VerifyCompletions` tests are failing -- You want to update completion snapshots without building locally - -**What it does:** -1. Builds the repository -2. Runs the completion tests to generate new `.received.` files -3. Runs the `CompareCliSnapshots` and `UpdateCliSnapshots` MSBuild targets -4. Commits the updated `.verified.*` snapshot files to your PR branch - -See [fixcompletions.instructions.md](fixcompletions.instructions.md) for detailed agent instructions. - -## How It Works - -These agents are triggered when you comment the specific slash command on a pull request. GitHub Copilot will: - -1. Clone the PR branch into a sandbox environment -2. Execute the instructions defined in the corresponding `.instructions.md` file -3. Use the `report_progress` tool to commit and push changes back to your PR -4. Comment on the PR to confirm completion or report any errors - -## For Agent Developers - -Each agent instruction file should: -- Clearly describe the trigger command and purpose -- Provide step-by-step instructions for the automation -- Include error handling and troubleshooting guidance -- Use the `report_progress` tool to commit changes -- Reference relevant documentation and example PRs - -## Additional Resources - -- [Developer Guide](../../documentation/project-docs/developer-guide.md#github-copilot-automation-commands) -- [Localization Guide](../../documentation/project-docs/Localization.md) -- [Snapshot Testing Guide](../../documentation/project-docs/snapshot-based-testing.md) diff --git a/.github/agents/fixcompletions.instructions.md b/.github/agents/fixcompletions.instructions.md deleted file mode 100644 index 865c17c9d1c2..000000000000 --- a/.github/agents/fixcompletions.instructions.md +++ /dev/null @@ -1,151 +0,0 @@ -# Fix Completions Tests Agent - -This agent automates the process of updating CLI completions snapshot test files when completion outputs change. - -## Trigger - -This agent is triggered when a user comments `/fixcompletions` on a pull request. - -## Description - -The dotnet CLI has snapshot-based tests for command completions across different shells (bash, zsh, powershell, etc.). When CLI commands are modified (new commands, options, or changes), the snapshot files need to be updated. This agent automates that process by: - -1. Building the repository -2. Running the completion tests to generate new `.received.` files -3. Comparing and updating the `.verified.` snapshot files -4. Committing the changes back to the PR - -## Instructions - -You are an expert at managing snapshot-based tests in .NET projects. When invoked: - -### Step 1: Build the Repository - -First, ensure the repository is built with the latest changes. This build will create the repo-local dotnet installation at `./.dotnet/dotnet`: - -```bash -./build.sh -``` - -This may take 5-10 minutes. Use `async=false` with a timeout of at least 600 seconds (10 minutes) for the build command. - -### Step 2: Run the Completion Tests - -Run the completion snapshot tests to generate the new `.received.` files. After the build completes, use the repo-local dotnet that was built: - -```bash -./.dotnet/dotnet test test/dotnet.Tests/dotnet.Tests.csproj --filter "Name~VerifyCompletions" -``` - -This will run all the `VerifyCompletions` tests which generate completion snapshots for all supported shells (bash, zsh, pwsh, fish, nushell). Allow at least 300 seconds (5 minutes) for this command. - -**Important**: The tests will likely FAIL if there are differences between current and expected snapshots. This is expected and correct behavior - don't be alarmed by test failures. - -### Step 3: Compare the Snapshots - -Run the `CompareCliSnapshots` MSBuild target to copy the `.received.` files from the artifacts directory to the test project: - -```bash -cd test/dotnet.Tests -dotnet restore /t:CompareCliSnapshots -``` - -Or from the repository root: - -```bash -dotnet restore test/dotnet.Tests/ /t:CompareCliSnapshots -``` - -### Step 4: Review the Changes - -Before accepting the changes, review them to ensure they make sense: - -```bash -git status -git diff test/dotnet.Tests/CompletionTests/snapshots/ -``` - -Look for: -- New command options that were added -- Removed options (if commands were deprecated) -- Changed command descriptions -- New subcommands - -If the changes are obviously incorrect or the diff shows unexpected modifications, report them to the user. Otherwise, proceed with updating the snapshots - the human reviewer of the PR will verify the changes are appropriate. - -### Step 5: Update the Verified Snapshots - -If the changes look correct, run the `UpdateCliSnapshots` target to rename `.received.` files to `.verified.`: - -```bash -cd test/dotnet.Tests -dotnet restore /t:UpdateCliSnapshots -``` - -Or from the repository root: - -```bash -dotnet restore test/dotnet.Tests/ /t:UpdateCliSnapshots -``` - -This will move/rename all `.received.*` files to `.verified.*` in the `test/dotnet.Tests/CompletionTests/snapshots/` directory. - -### Step 6: Commit the Changes - -Use the `report_progress` tool to commit and push the snapshot updates directly to the PR branch: - -- Commit message: "Update CLI completions snapshots" -- PR description: Update the checklist to show completion snapshots have been updated - -The `report_progress` tool will automatically stage all changes, create a commit, and push to the origin branch that this PR is based on. - -### Step 7: Verify Final State - -After committing, verify that: -1. All `.received.` files have been renamed to `.verified.` -2. No `.received.` files remain in the repository -3. Only `.verified.*` files are committed - -## Important Notes - -- **Always build before running tests** - the tests need the latest built CLI tools -- **Test failures are expected** when snapshots don't match - this is not an error -- **Review changes carefully** - snapshot updates should match the PR's intended changes -- The snapshots are in: `test/dotnet.Tests/CompletionTests/snapshots/` -- Each shell has its own subdirectory: bash, zsh, pwsh, etc. -- Only commit `.verified.*` files, never commit `.received.*` files - -## Troubleshooting - -If the build fails: -- Check the error messages carefully -- Some CI-only failures are expected and can be ignored if they're unrelated to your changes -- Report any blocking build errors to the user - -If tests timeout: -- The completion tests can be slow - allow at least 5 minutes -- If tests hang, try running them again - -If no `.received.` files are generated: -- Make sure the tests actually ran and detected differences -- Check that the build completed successfully -- The tests might have passed (no changes needed) - -## Example Workflow - -When a user comments `/fixcompletions`: - -1. Build: `./build.sh` (with 600s timeout) - creates `./.dotnet/dotnet` -2. Test: `./.dotnet/dotnet test test/dotnet.Tests/dotnet.Tests.csproj --filter "Name~VerifyCompletions"` (with 300s timeout) -3. Compare: `dotnet restore test/dotnet.Tests/ /t:CompareCliSnapshots` -4. Review: `git diff test/dotnet.Tests/CompletionTests/snapshots/` - check for unexpected issues -5. Update: `dotnet restore test/dotnet.Tests/ /t:UpdateCliSnapshots` -6. Commit: Use `report_progress` with message "Update CLI completions snapshots" - this commits and pushes to the PR branch -7. Inform: Let the user know the snapshots have been updated successfully - -## References - -- See `documentation/project-docs/snapshot-based-testing.md` for more details -- Example snapshot update: https://github.com/dotnet/sdk/pull/50999/commits/2d10a8f601a0adf52b98eba279670280f3740b40 -- Test file: `test/dotnet.Tests/CompletionTests/DotnetCliSnapshotTests.cs` -- MSBuild targets: `test/dotnet.Tests/dotnet.Tests.csproj` (lines 101-113) diff --git a/.github/agents/updatexlf.instructions.md b/.github/agents/updatexlf.instructions.md deleted file mode 100644 index 7cd7032aacb6..000000000000 --- a/.github/agents/updatexlf.instructions.md +++ /dev/null @@ -1,72 +0,0 @@ -# Update XLF Files Agent - -This agent automates the process of updating XLF (XLIFF) translation files when .resx resource files are changed. - -## Trigger - -This agent is triggered when a user comments `/updatexlf` on a pull request. - -## Description - -When .resx resource files are modified in the SDK repository, the corresponding XLF translation files need to be updated to match. This agent automates that process by: - -1. Building the repository (or running the UpdateXlf MSBuild target) -2. Collecting the updated XLF files -3. Committing the changes back to the PR - -## Instructions - -You are an expert at managing localization files in .NET projects. When invoked: - -1. **Check the current state**: First, identify if there are any .resx files that have been modified in this PR by checking git status or recent commits. - -2. **Run the UpdateXlf target**: The repository is built on a Linux environment, so use the appropriate build script: - - First, try running just the UpdateXlf target (faster): - ```bash - ./build.sh /t:UpdateXlf - ``` - - If that doesn't work or if the target is not found, perform a full build which will also update XLF files: - ```bash - ./build.sh - ``` - - The build may take 5-10 minutes. Use `async=false` with a timeout of at least 600 seconds (10 minutes). - -3. **Verify the changes**: Check which XLF files were modified: - ```bash - git status - git diff --name-only - ``` - -4. **Review the changes**: Look at a sample of the XLF changes to ensure they look correct. Properly updated XLF files should have: - - Elements with `state="needs-review-translation"` for modified strings - - Elements with `state="new"` for newly added strings - - No manual edits to translations - -5. **Commit the changes**: Use the `report_progress` tool to commit and push the XLF updates: - - Commit message: "Update XLF translation files" - - PR description: Update the checklist to show XLF files have been updated - -## Important Notes - -- **Never manually edit XLF files**. Always use the MSBuild target or build process. -- Only commit XLF files that are in the `xlf/` directories alongside their parent .resx files. -- If there are any errors during the build, report them clearly to the user. -- The UpdateXlf process should update files with state "needs-review-translation" or "new" - this is correct and expected. - -## Example Workflow - -When a user comments `/updatexlf`: - -1. Run: `./build.sh /t:UpdateXlf` (with 600s timeout) or `./build.sh` if needed -2. Check: `git status` and `git diff` to see what changed -3. Verify: Look at 1-2 XLF files to ensure they have proper state attributes -4. Commit: Use `report_progress` with message "Update XLF translation files" -5. Inform: Let the user know the XLF files have been updated successfully - -## References - -- See `documentation/project-docs/Localization.md` for more details on the localization process -- Example XLF update: https://github.com/dotnet/sdk/pull/2389/commits/edbb8ddd72e1943a73928560bd0b58a5a1d00bb7 diff --git a/.github/workflows/fix-completions-on-comment.yml b/.github/workflows/fix-completions-on-comment.yml new file mode 100644 index 000000000000..c326d59a50bb --- /dev/null +++ b/.github/workflows/fix-completions-on-comment.yml @@ -0,0 +1,167 @@ +name: Fix completion snapshots on command + +on: + issue_comment: + types: [created] + +permissions: + contents: write + pull-requests: write + issues: write + +jobs: + fix-completions: + # Only run on PR comments that start with /fixcompletions + if: github.event.issue.pull_request && startsWith(github.event.comment.body, '/fixcompletions') + runs-on: ubuntu-latest + + steps: + - name: React to comment + uses: actions/github-script@v7 + with: + script: | + await github.rest.reactions.createForIssueComment({ + owner: context.repo.owner, + repo: context.repo.repo, + comment_id: context.payload.comment.id, + content: 'eyes' + }); + + - name: Checkout repository + uses: actions/checkout@v4 + with: + token: ${{ secrets.GITHUB_TOKEN }} + fetch-depth: 0 + + - name: Checkout PR branch + run: | + gh pr checkout ${{ github.event.issue.number }} + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + - name: Build repository + id: build + run: | + chmod +x ./build.sh + ./build.sh + continue-on-error: true + timeout-minutes: 15 + + - name: Run completion tests + id: test + if: steps.build.outcome == 'success' + run: | + # Use the repo-local dotnet that was built + ./.dotnet/dotnet test test/dotnet.Tests/dotnet.Tests.csproj --filter "Name~VerifyCompletions" + continue-on-error: true + timeout-minutes: 10 + + - name: Compare snapshots + id: compare + if: steps.test.outcome != 'skipped' + run: | + dotnet restore test/dotnet.Tests/ /t:CompareCliSnapshots + continue-on-error: true + + - name: Check for snapshot changes + id: check-changes + if: steps.compare.outcome == 'success' + run: | + # Check if there are changes to snapshot files + if git diff --name-only test/dotnet.Tests/CompletionTests/snapshots/ | grep -E '\.received\.'; then + echo "changes=true" >> $GITHUB_OUTPUT + echo "Changed snapshot files:" + git diff --name-only test/dotnet.Tests/CompletionTests/snapshots/ + else + echo "changes=false" >> $GITHUB_OUTPUT + fi + + - name: Update verified snapshots + id: update + if: steps.check-changes.outputs.changes == 'true' + run: | + # This renames .received.* files to .verified.* + dotnet restore test/dotnet.Tests/ /t:UpdateCliSnapshots + continue-on-error: true + + - name: Commit and push snapshot changes + id: commit + if: steps.update.outcome == 'success' + run: | + git config --global user.name 'github-actions[bot]' + git config --global user.email 'github-actions[bot]@users.noreply.github.com' + + # Add snapshot files + git add test/dotnet.Tests/CompletionTests/snapshots/ + + # Create commit + COMMIT_DATE=$(date -u +"%Y-%m-%d") + git commit -m "Update CLI completion snapshots - $COMMIT_DATE" + + # Push to the PR branch + git push + continue-on-error: true + + - name: Comment on PR - Success + if: steps.commit.outcome == 'success' + uses: actions/github-script@v7 + with: + script: | + await github.rest.issues.createComment({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.payload.issue.number, + body: '✅ CLI completion snapshots have been updated and committed to this PR.' + }); + await github.rest.reactions.createForIssueComment({ + owner: context.repo.owner, + repo: context.repo.repo, + comment_id: context.payload.comment.id, + content: '+1' + }); + + - name: Comment on PR - No changes + if: steps.compare.outcome == 'success' && steps.check-changes.outputs.changes == 'false' + uses: actions/github-script@v7 + with: + script: | + await github.rest.issues.createComment({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.payload.issue.number, + body: 'ℹ️ No completion snapshot files needed to be updated.' + }); + await github.rest.reactions.createForIssueComment({ + owner: context.repo.owner, + repo: context.repo.repo, + comment_id: context.payload.comment.id, + content: '+1' + }); + + - name: Comment on PR - Failure + if: steps.build.outcome == 'failure' || (steps.test.outcome == 'failure' && steps.compare.outcome != 'success') || (steps.check-changes.outputs.changes == 'true' && (steps.update.outcome == 'failure' || steps.commit.outcome == 'failure')) + uses: actions/github-script@v7 + with: + script: | + let errorMsg = '❌ Failed to update completion snapshots.'; + + if ('${{ steps.build.outcome }}' === 'failure') { + errorMsg += ' The build failed.'; + } else if ('${{ steps.update.outcome }}' === 'failure') { + errorMsg += ' Could not update snapshot files.'; + } else if ('${{ steps.commit.outcome }}' === 'failure') { + errorMsg += ' Could not commit changes.'; + } + + await github.rest.issues.createComment({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.payload.issue.number, + body: errorMsg + ' Please check the workflow logs for details.' + }); + await github.rest.reactions.createForIssueComment({ + owner: context.repo.owner, + repo: context.repo.repo, + comment_id: context.payload.comment.id, + content: 'confused' + }); diff --git a/.github/workflows/update-xlf-on-comment.yml b/.github/workflows/update-xlf-on-comment.yml new file mode 100644 index 000000000000..5d5035bedd5c --- /dev/null +++ b/.github/workflows/update-xlf-on-comment.yml @@ -0,0 +1,152 @@ +name: Update XLF files on command + +on: + issue_comment: + types: [created] + +permissions: + contents: write + pull-requests: write + issues: write + +jobs: + update-xlf: + # Only run on PR comments that start with /updatexlf + if: github.event.issue.pull_request && startsWith(github.event.comment.body, '/updatexlf') + runs-on: ubuntu-latest + + steps: + - name: React to comment + uses: actions/github-script@v7 + with: + script: | + await github.rest.reactions.createForIssueComment({ + owner: context.repo.owner, + repo: context.repo.repo, + comment_id: context.payload.comment.id, + content: 'eyes' + }); + + - name: Checkout repository + uses: actions/checkout@v4 + with: + token: ${{ secrets.GITHUB_TOKEN }} + fetch-depth: 0 + + - name: Checkout PR branch + run: | + gh pr checkout ${{ github.event.issue.number }} + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + - name: Run UpdateXlf target + id: update + run: | + chmod +x ./build.sh + # Try the fast UpdateXlf target first + if ./build.sh /t:UpdateXlf; then + echo "result=success" >> $GITHUB_OUTPUT + else + # If that fails, try a full build + if ./build.sh; then + echo "result=success" >> $GITHUB_OUTPUT + else + echo "result=failure" >> $GITHUB_OUTPUT + exit 1 + fi + fi + continue-on-error: true + timeout-minutes: 15 + + - name: Check for XLF changes + id: check-changes + if: steps.update.outcome == 'success' + run: | + # Check if there are changes to .xlf files + if git diff --name-only | grep -E '\.xlf$'; then + echo "changes=true" >> $GITHUB_OUTPUT + echo "Changed XLF files:" + git diff --name-only | grep -E '\.xlf$' + else + echo "changes=false" >> $GITHUB_OUTPUT + fi + + - name: Commit and push XLF changes + id: commit + if: steps.update.outcome == 'success' && steps.check-changes.outputs.changes == 'true' + run: | + git config --global user.name 'github-actions[bot]' + git config --global user.email 'github-actions[bot]@users.noreply.github.com' + + # Add all .xlf files + git add **/*.xlf + + # Create commit + COMMIT_DATE=$(date -u +"%Y-%m-%d") + git commit -m "Update XLF translation files - $COMMIT_DATE" + + # Push to the PR branch + git push + continue-on-error: true + + - name: Comment on PR - Success + if: steps.commit.outcome == 'success' + uses: actions/github-script@v7 + with: + script: | + await github.rest.issues.createComment({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.payload.issue.number, + body: '✅ XLF translation files have been updated and committed to this PR.' + }); + await github.rest.reactions.createForIssueComment({ + owner: context.repo.owner, + repo: context.repo.repo, + comment_id: context.payload.comment.id, + content: '+1' + }); + + - name: Comment on PR - No changes + if: steps.update.outcome == 'success' && steps.check-changes.outputs.changes == 'false' + uses: actions/github-script@v7 + with: + script: | + await github.rest.issues.createComment({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.payload.issue.number, + body: 'ℹ️ No XLF files needed to be updated.' + }); + await github.rest.reactions.createForIssueComment({ + owner: context.repo.owner, + repo: context.repo.repo, + comment_id: context.payload.comment.id, + content: '+1' + }); + + - name: Comment on PR - Failure + if: steps.update.outcome == 'failure' || (steps.check-changes.outputs.changes == 'true' && steps.commit.outcome == 'failure') + uses: actions/github-script@v7 + with: + script: | + let errorMsg = '❌ Failed to update XLF files.'; + + if ('${{ steps.update.outcome }}' === 'failure') { + errorMsg += ' The build failed.'; + } else if ('${{ steps.commit.outcome }}' === 'failure') { + errorMsg += ' Could not commit changes.'; + } + + await github.rest.issues.createComment({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.payload.issue.number, + body: errorMsg + ' Please check the workflow logs for details.' + }); + await github.rest.reactions.createForIssueComment({ + owner: context.repo.owner, + repo: context.repo.repo, + comment_id: context.payload.comment.id, + content: 'confused' + }); diff --git a/documentation/project-docs/Localization.md b/documentation/project-docs/Localization.md index 1555d199d8f3..51fde9703637 100644 --- a/documentation/project-docs/Localization.md +++ b/documentation/project-docs/Localization.md @@ -7,14 +7,14 @@ The local dev build automatically generates updates to the xlf files that contai When making string changes, update the resx, build, and check in all xlf file changes. Developers should never need to update the xlf files directly and should always rely on the local build for updates to those files. This will leave the files in english initially and they will get translated eventually. -#### Automated XLF Updates via GitHub Copilot +#### Automated XLF Updates via GitHub Actions -If you've modified `.resx` files in a pull request and need to update the corresponding `.xlf` files but don't want to clone the branch locally, you can use the GitHub Copilot automation: +If you've modified `.resx` files in a pull request and need to update the corresponding `.xlf` files but don't want to clone the branch locally, you can use the automated GitHub Action: -**Comment `/updatexlf` on your pull request** and the Copilot agent will: -1. Run the `msbuild /t:UpdateXlf` target (or build if needed) -2. Collect all updated `.xlf` files -3. Commit the changes directly to your PR branch +**Comment `/updatexlf` on your pull request** and the workflow will: +1. Check out your PR branch +2. Run the UpdateXlf build target +3. Commit any updated `.xlf` files directly to your PR branch This is particularly useful when CI is failing due to outdated XLF files. diff --git a/documentation/project-docs/developer-guide.md b/documentation/project-docs/developer-guide.md index af1c0473722d..4cfd06528085 100644 --- a/documentation/project-docs/developer-guide.md +++ b/documentation/project-docs/developer-guide.md @@ -176,36 +176,32 @@ taskkill /F /IM VSTest.Console.exe /T || taskkill /F /IM msbuild.exe /T ``` -## GitHub Copilot Automation Commands +## Automated PR Maintenance Commands -The SDK repository includes GitHub Copilot agents that can automate common maintenance tasks directly from pull requests. These agents can be triggered by commenting specific commands on a PR. +The SDK repository includes GitHub Actions workflows that automate common maintenance tasks directly from pull requests. ### `/updatexlf` - Update Translation Files -When you modify `.resx` resource files, the corresponding `.xlf` translation files need to be updated. Instead of manually running the build locally, you can comment `/updatexlf` on the PR and the Copilot agent will: +When you modify `.resx` resource files, the corresponding `.xlf` translation files need to be updated. Instead of manually running the build locally, comment `/updatexlf` on the PR and the GitHub Action will: -1. Run the `msbuild /t:UpdateXlf` target (or perform a full build if needed) -2. Collect all updated `.xlf` files -3. Commit the changes to the PR branch +1. Check out the PR branch +2. Run `./build.sh /t:UpdateXlf` (or full build if needed) +3. Commit any updated `.xlf` files directly to the PR branch This is useful when you've changed localized strings and the CI build is failing due to outdated XLF files. -**Example usage:** Comment `/updatexlf` on a PR where you've modified `CliStrings.resx` or other resource files. - See also: [Localization documentation](Localization.md) ### `/fixcompletions` - Update CLI Completion Snapshots -The CLI includes snapshot-based tests for shell completions (bash, zsh, pwsh, etc.). When you add or modify CLI commands, these snapshots need to be updated. Comment `/fixcompletions` on the PR and the agent will: +The CLI includes snapshot-based tests for shell completions (bash, zsh, pwsh, etc.). When you add or modify CLI commands, these snapshots need to be updated. Comment `/fixcompletions` on the PR and the GitHub Action will: 1. Build the repository -2. Run the completion tests to generate new snapshots -3. Compare and update the verified snapshot files -4. Commit the changes to the PR branch - -This is useful when you've added new commands or options and the `VerifyCompletions` tests are failing. +2. Run the completion tests +3. Update the verified snapshot files +4. Commit the changes directly to the PR branch -**Example usage:** Comment `/fixcompletions` on a PR where you've modified CLI command structure. +This is useful when you've added new commands or options and the completion snapshot tests are failing. See also: [Snapshot-based testing documentation](snapshot-based-testing.md) diff --git a/documentation/project-docs/snapshot-based-testing.md b/documentation/project-docs/snapshot-based-testing.md index 19fee0de3b8b..c423941cca30 100644 --- a/documentation/project-docs/snapshot-based-testing.md +++ b/documentation/project-docs/snapshot-based-testing.md @@ -13,11 +13,11 @@ To fix these tests, you need to diff the two files and visually inspect the chan * [CompareCliSnapshots][compare] - this Target copies the .received. files from the artifacts directory, where they are created due to the way we run tests, to the [snapshots][snapshots] directory in the dotnet.Tests project. This makes it much easier to diff the two. * [UpdateCliSnapshots][update] - this Target renames the .received. files to .verified. in the local [snapshots][snapshots] directory, and so acts as a giant 'I accept these changes' button. Only use this if you've diffed the snapshots and are sure they match your expectations. -### Automated Snapshot Updates via GitHub Copilot +### Automated Snapshot Updates via GitHub Actions -If you've modified CLI commands in a pull request and the completion snapshot tests are failing, but you don't want to clone the branch locally to update the snapshots, you can use the GitHub Copilot automation: +If you've modified CLI commands in a pull request and the completion snapshot tests are failing, but you don't want to clone the branch locally to update the snapshots, you can use the automated GitHub Action: -**Comment `/fixcompletions` on your pull request** and the Copilot agent will: +**Comment `/fixcompletions` on your pull request** and the workflow will: 1. Build the repository 2. Run the completion tests to generate new snapshots 3. Run the `CompareCliSnapshots` and `UpdateCliSnapshots` targets