diff --git a/.github/workflows/backport.yml b/.github/workflows/backport.yml index fffd778b9d48..5efe762cf00f 100644 --- a/.github/workflows/backport.yml +++ b/.github/workflows/backport.yml @@ -1,3 +1,9 @@ +# This workflow creates a "backport" pull request by cherry-picking changes +# from the source pull request to the target branch when /backport to +# is commented on a pull request. +# Action: https://github.com/dotnet/sdk/actions/workflows/backport.yml +# Keep documentation/project-docs/developer-guide.md up to date with changes in +# this workflow. name: Backport PR to branch on: issue_comment: @@ -17,4 +23,4 @@ jobs: pr_description_template: | Backport of #%source_pr_number% to %target_branch% - /cc %cc_users% \ No newline at end of file + /cc %cc_users% diff --git a/.github/workflows/fix-completions-on-comment.yml b/.github/workflows/fix-completions-on-comment.yml index 29f4bff3f363..e1a8c5051085 100644 --- a/.github/workflows/fix-completions-on-comment.yml +++ b/.github/workflows/fix-completions-on-comment.yml @@ -1,3 +1,8 @@ +# This workflow updates snapshots for CLI completion tests when +# /fixcompletions or /completions is commented on a pull request. +# Action: https://github.com/dotnet/sdk/actions/workflows/fix-completions-on-comment.yml +# Keep documentation/project-docs/developer-guide.md up to date with changes in +# this workflow. name: Fix completion snapshots on command on: diff --git a/.github/workflows/update-xlf-on-comment.yml b/.github/workflows/update-xlf-on-comment.yml index 5f67a325130a..98196608b97d 100644 --- a/.github/workflows/update-xlf-on-comment.yml +++ b/.github/workflows/update-xlf-on-comment.yml @@ -1,3 +1,8 @@ +# This workflow updates XLF files when /updatexlf or /xlf is commented on a +# pull request. +# Action: https://github.com/dotnet/sdk/actions/workflows/update-xlf-on-comment.yml +# Keep documentation/project-docs/developer-guide.md up to date with changes in +# this workflow. name: Update XLF files on command on: diff --git a/documentation/project-docs/developer-guide.md b/documentation/project-docs/developer-guide.md index e1bd2e70a080..6ab85c6deca7 100644 --- a/documentation/project-docs/developer-guide.md +++ b/documentation/project-docs/developer-guide.md @@ -180,9 +180,12 @@ taskkill /F /IM msbuild.exe /T The SDK repository includes GitHub Actions workflows that automate common maintenance tasks directly from pull requests. -### `/xlf or /updatexlf` - Update Translation Files +### `/xlf` or `/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, comment `/updatexlf` on the PR and the GitHub Action will: +- Workflow: [Update XLF files on command](https://github.com/dotnet/sdk/actions/workflows/update-xlf-on-comment.yml) +- Source: [update-xlf-on-comment.yml](../../.github/workflows/update-xlf-on-comment.yml) + +When you modify `.resx` resource files, the corresponding `.xlf` translation files need to be updated. Instead of manually running the build locally, comment `/xlf` or `/updatexlf` on the PR and the GitHub Action will: 1. Check out the PR branch 2. Run `./build.sh /t:UpdateXlf` (or full build if needed) @@ -192,9 +195,12 @@ This is useful when you've changed localized strings and the CI build is failing See also: [Localization documentation](Localization.md) -### `/completions or /fixcompletions` - Update CLI Completion Snapshots +### `/completions` or `/fixcompletions` - Update CLI Completion Snapshots + +- Workflow: [Fix completion snapshots on command](https://github.com/dotnet/sdk/actions/workflows/fix-completions-on-comment.yml) +- Source: [fix-completions-on-comment.yml](../../.github/workflows/fix-completions-on-comment.yml) -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: +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 `/completions` or `/fixcompletions` on the PR and the GitHub Action will: 1. Build the repository 2. Run the completion tests @@ -205,12 +211,34 @@ This is useful when you've added new commands or options and the completion snap See also: [Snapshot-based testing documentation](snapshot-based-testing.md) +### `/backport to ` + +- Workflow: [Backport PR to branch](https://github.com/dotnet/sdk/actions/workflows/backport.yml) +- Source: [backport.yml](../../.github/workflows/backport.yml) + +Comment `/backport to ` on a merged PR to create a new pull request that cherry-picks the changes onto the target branch. The backport PR will be labeled with `backport` and will CC the original PR participants. + +### `/ba-g ` - Bypass Build Analysis + +Comment `/ba-g ` on a PR to unconditionally turn the Build Analysis check green. The reason +is captured by telemetry and should be descriptive - avoid non-specific justifications like +"unrelated issues". This is useful when CI failures are caused by known flaky tests or +infrastructure issues unrelated to the PR. -### `/backport to {branch}` +Example reasons: -The SDK team manages many branches. -You may use /backport to {branch_name} to mimic the process of cherry-picking a PR onto another branch. +- `/ba-g deadletter` - Helix work item crashed with "DeadLetter" status. +- `/ba-g docs-only change` - PR did not change any source code. +- `/ba-g insufficient info in logs` - No good unique pattern in the logs to open a known issue. +- `/ba-g recently fixed known issue #` - The known issue fix was already merged, but CI ran + before it. +- `/ba-g failures are from known issues #, #` - All failures have known issues + filed, but Build Analysis isn't turning green. +For details on triaging CI failures and filing known issues, see the [runtime failure analysis +documentation](https://github.com/dotnet/runtime/blob/main/docs/workflow/ci/failure-analysis.md). +The [Build Analysis Known Issue Helper](https://helix.dot.net/BuildAnalysis/CreateKnownIssues) can +assist in creating known issue reports with the correct labels and JSON format. ## Adding a Command