Add manual backport instructions to backport failure comments

[Copilot]

When the backport action fails (usually a merge conflict), the comment it posts contains only a failure notice and raw git am output — enough for experienced users, but not a starting point for anyone who hasn't done a manual backport before.

The failure comment now includes a step-by-step How to backport manually section, placed after the failure message and before the (less interesting) <details> block with the command output.

Changes

• manual_backport_instructions(temp_branch, patch_file, git_am_command) renders a bash snippet mirroring what the workflow itself does: branch off the target branch, download the PR patch, run the same git am command that failed, resolve conflicts, push, and open the PR.
• Applied to all three "please backport manually" comments: git am failure, conflict-resolution command failure, and unresolved conflicts after resolution.
• Hoisted the PR title/description/label template expansion to the top of the script so the instructions emit the exact title, body, and labels the workflow would have used. This removes the duplicated .replace(...) chains from the PR-creation path.
• Values interpolated into the shell snippet (PR title/body/labels) are escaped for a double-quoted shell context.

Sample output for a conflicted backport to release/9.0 with pr_labels: Servicing-consider:

@requester backporting to `release/9.0` failed, the patch most likely resulted in conflicts. Please backport manually!

### How to backport manually

```bash
# 1. Get the latest sources and create the backport branch from the target branch
git fetch origin
git checkout -b backport/pr-42-to-release/9.0 origin/release/9.0

# 2. Download the patch of the changes from pull request #42
gh pr diff --patch 42 > changes.patch

# 3. Apply the patch (this is the step that failed in the automated backport)
git am --3way --empty=keep --ignore-whitespace --keep-non-patch changes.patch
...
```

To double check:

• The right tests are in and the right validation has happened. Guidance: https://github.com/dotnet/arcade/blob/main/Documentation/Validation.md

The repo has no test harness for workflow scripts. Validation was done by extracting the Run backport script and executing it under Node with mocked github/context/core/exec, covering the git am failure path (instruction rendering and escaping of quotes/$/backticks in the PR title) and the success path (PR still created with correct title, body, and labels after the template hoist).

• Fixes The backport workflow should provide instructions to the use when the automated backport fails #17487

[Copilot]

Copilot wasn't able to review any files in this pull request.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟡 Changes recommended

The new manual backport instructions don’t fully mirror the workflow’s required steps (notably the PR-head fetch and force-push behavior), which can cause the suggested manual commands to fail.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

• Files reviewed: 1/1 changed files
• Comments generated: 3
• Review effort level: Lite

[baronfel]

@copilot resolve the feedbacks from the review

[Copilot]

@copilot resolve the feedbacks from the review

Resolved in 453c8d4: added the PR-head fetch to the manual commands, changed the manual push to --force --set-upstream, and updated the string comparison to strict inequality. Targeted validation passed (git diff --check, extracted Run backport script node --check), secret scanning found no secrets, and CodeQL reported no alerts.

[Copilot]

🟡 Changes recommended

The new manual backport snippet currently has a couple of sharp edges (notably --body "..." readability with multi-line templates and git push --force in user-facing instructions) that can mislead users and create unnecessary risk.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

.github/workflows/backport-base.yml:169

• backport_pr_description defaults to a multi-line template, so embedding it directly in --body "..." makes the snippet span multiple lines inside quotes, which is easy for users to misread/copy incorrectly. Consider switching the instructions to --body-file - with a quoted heredoc so the body is clearly multi-line and does not require shell escaping/expansion concerns.

• Files reviewed: 1/1 changed files
• Comments generated: 1
• Review effort level: Lite

[baronfel]

@copilot respond to the review feedback

[Copilot]

@copilot respond to the review feedback

Addressed in 1fc5fc9: changed the manual push instruction to git push --force-with-lease --set-upstream to avoid accidentally clobbering a remote branch that has additional commits.

[Copilot]

🟢 Approval recommended

The change is localized to workflow messaging/templating and is low risk, with only a minor doc-accuracy tweak suggested in review comments.

Review details

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

.github/workflows/backport-base.yml:152

• The manual backport snippet uses git fetch origin refs/pull/.../head as a normal step, but the workflow treats this fetch as best-effort (warns and continues). If this fetch fails for a user (e.g., ref not available or permissions), they may stop even though they can still proceed with git am. Consider making the snippet match the workflow by ignoring failures and/or adding a short note that it is optional.

• Files reviewed: 1/1 changed files
• Comments generated: 0 new
• Review effort level: Lite

[akoeplinger]

One comment, LGTM otherwise

[akoeplinger]

this will embed the quite large PR description (e.g. the full servicing template for dotnet/runtime) in the command shown to the user, I don't think that will be a nice UX :)