Skip to content

Add backport email template#124085

Open
steveisok wants to merge 8 commits intodotnet:mainfrom
steveisok:add-backport-template
Open

Add backport email template#124085
steveisok wants to merge 8 commits intodotnet:mainfrom
steveisok:add-backport-template

Conversation

@steveisok
Copy link
Member

@steveisok steveisok commented Feb 6, 2026

This adds a template for emailing Tactics to request approval for backports to release branches.

The template includes standard sections:

  • Customer Impact - with checkboxes for "Customer reported" / "Found internally"
  • Regression - with checkboxes for Yes/No and space for details
  • Testing - how the fix was verified
  • Risk - High/Medium/Low with justification

This complements the existing PULL_REQUEST_TEMPLATE/servicing_pull_request_template.md which is used for the PR itself, while this template is for the email approval request step.

Copilot AI review requested due to automatic review settings February 6, 2026 12:58
@github-actions github-actions bot added the needs-area-label An area label is needed to ensure this gets routed to the appropriate area owners label Feb 6, 2026
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR adds a standardized template for requesting backports to release branches, providing a structured format that aligns with the existing servicing PR workflow and .NET Tactics approval process.

Changes:

  • Adds .github/BACKPORT_TEMPLATE.md with sections for Customer Impact, Regression, Testing, and Risk assessment to standardize backport requests


---

**Subject:** [release/X.0] Backport request: <Brief description> (#<PR number>)
Copy link

Copilot AI Feb 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Inconsistent placeholder format: Line 7 uses <PR number> (lowercase with space) while line 13 uses <PR_NUMBER> (uppercase with underscore). Consider standardizing to use the same format throughout, preferably uppercase with underscores for consistency with <PR_NUMBER> and <ISSUE_NUMBER>.

Suggested change
**Subject:** [release/X.0] Backport request: <Brief description> (#<PR number>)
**Subject:** [release/X.0] Backport request: <BRIEF_DESCRIPTION> (#<PR_NUMBER>)

Copilot uses AI. Check for mistakes.
Adds a template for emailing Tactics to request approval for backports
to release branches, with standard sections for Customer Impact,
Regression, Testing, and Risk.
@steveisok steveisok force-pushed the add-backport-template branch from c3a25ac to 1a4401e Compare February 6, 2026 13:04
@steveisok steveisok changed the title Add backport request template Add backport email template Feb 6, 2026
Copilot AI review requested due to automatic review settings February 6, 2026 13:12
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 3 comments.


---

**Subject:** [release/X.0] Backport request: <Brief description> (#<PR number>)
Copy link

Copilot AI Feb 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Inconsistent placeholder formatting in the subject line. The template uses both lowercase <Brief description> and <PR number> here, while using uppercase <PR_NUMBER> and <ISSUE_NUMBER> elsewhere in the template (lines 15, 24). Consider using consistent formatting throughout - either all uppercase (e.g., <BRIEF_DESCRIPTION> and <PR_NUMBER>) or all lowercase with underscores for multi-word placeholders.

Suggested change
**Subject:** [release/X.0] Backport request: <Brief description> (#<PR number>)
**Subject:** [release/X.0] Backport request: <BRIEF_DESCRIPTION> (#<PR_NUMBER>)

Copilot uses AI. Check for mistakes.

Use this template when emailing Tactics to request approval for a backport to a release branch.

> **Note:** Most email clients (Outlook, Gmail, etc.) don't render Markdown. Copy the template below and the section headers will display as bold text. If your email client supports rich text, you can manually increase the header font size.
Copy link

Copilot AI Feb 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The note states "the section headers will display as bold text" but this is misleading. When copying markdown text with **TEXT** into a plain text email, the asterisks will be visible as literal characters (e.g., **CUSTOMER IMPACT**), not rendered as bold. Consider clarifying this note to say something like "the section headers use **bold** markdown syntax which, while not rendered in plain text emails, provides visual emphasis through the asterisks" or remove the claim about bold text display.

Suggested change
> **Note:** Most email clients (Outlook, Gmail, etc.) don't render Markdown. Copy the template below and the section headers will display as bold text. If your email client supports rich text, you can manually increase the header font size.
> **Note:** Most email clients (Outlook, Gmail, etc.) don't render Markdown. Copy the template below: the section headers use `**bold**` Markdown syntax which, in plain-text emails, appears with asterisks for visual emphasis. If your email client supports rich text, you can manually format the headers (for example, by increasing the font size or applying bold).

Copilot uses AI. Check for mistakes.
Comment on lines 19 to 20
- [ ] Customer reported
- [ ] Found internally
Copy link

Copilot AI Feb 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The checkbox syntax - [ ] is GitHub Flavored Markdown that won't render as checkboxes in email clients. When copied to email, these will appear as plain text like - [ ] Customer reported. Consider whether this is the intended format for an email template, or if a simpler format like ☐ Customer reported or just removing the brackets entirely would be more appropriate for email use.

Copilot uses AI. Check for mistakes.
@steveisok steveisok closed this Feb 6, 2026
@steveisok steveisok deleted the add-backport-template branch February 6, 2026 13:15
@steveisok steveisok restored the add-backport-template branch February 6, 2026 15:52
@steveisok steveisok reopened this Feb 6, 2026
Per feedback, the email content should come directly from the backport
PR description to ensure consistency. Updated template to:
- Explicitly instruct users to copy sections from their PR
- Add DESCRIPTION and main PR sections to match servicing template
- Standardize placeholder format to UPPERCASE_WITH_UNDERSCORES
@steveisok
Copy link
Member Author

steveisok commented Feb 6, 2026

@jkotas it should now work like this:

Generate a backport email from https://github.com/dotnet/runtime/pull/124058

If it ends up inconsistent, we can add a skill to better direct it. I doubt that will be necessary since our usage is straightforward.

@jkotas
Copy link
Member

jkotas commented Feb 6, 2026

Generate a backport email from #124058

This did not work for me. It generated an email that was ~95% right.

I had to point it to the template explicitly like Generate a backport email from https://github.com/dotnet/runtime/pull/124058 using template at .github\BACKPORT_EMAIL_TEMPLATE.md to actually use this template. It generated the text, but it did not open it in outlook.

Generate a backport email from #124058 using template at .github\BACKPORT_EMAIL_TEMPLATE.md and open it outlook` made it to open it in outlook as ASCII text (without nice formatting). The Powershell script that it executed to open the email in outlook caused my outlook to hang and I had to restart.

@@ -0,0 +1,52 @@
# Backport Email Template
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How much does the file name matter for copilot? Can the file be in a subdirectory and have a name that does not look like a special name recognized by github? (For example, the existing PULL_REQUEST_TEMPLATE is a special directory name that github knowns about.)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We could likely put this anywhere and tell the skill where to pick it up. It seemed 'better' to have this under .github since it's intended to work with the skill.

Copy link
Member

@jkotas jkotas Feb 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

intended to work with the skill.

Can this be a sub-directory in the skill directory? Like https://github.com/dotnet/runtime/tree/main/.github/skills/azdo-helix-failures

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, I created a template folder and moved it into there.

Copilot AI review requested due to automatic review settings February 7, 2026 03:27
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

Comment on lines 50 to 52
**RISK**

<Copy from PR: Risk section>
Copy link

Copilot AI Feb 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PR description says the email template includes a Risk High/Medium/Low selection with justification, but the template only has a free-form <Copy from PR: Risk section> placeholder and no standard options. Consider adding the Risk level options (e.g., checkboxes or an explicit Risk: High|Medium|Low line) so the template matches the intended standardized format.

Copilot uses AI. Check for mistakes.
Output the email as **plain text** (not markdown) since email clients don't render markdown.

```
Subject: [release/X.0] Backport request: <TITLE> (#<PR_NUMBER>)
Copy link

Copilot AI Feb 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The sample subject line here uses Subject: ... <TITLE> while .github/BACKPORT_EMAIL_TEMPLATE.md uses **Subject:** ... <BRIEF_DESCRIPTION>. Align the placeholder naming/format between the skill output example and the template to reduce ambiguity about what should be inserted (full PR title vs brief description).

Suggested change
Subject: [release/X.0] Backport request: <TITLE> (#<PR_NUMBER>)
Subject: [release/X.0] Backport request: <BRIEF_DESCRIPTION> (#<PR_NUMBER>)

Copilot uses AI. Check for mistakes.
Comment on lines 22 to 29
2. **Extract from the PR description:**
- Link to the original main PR
- Link to the issue being fixed
- DESCRIPTION section
- CUSTOMER IMPACT section (including checkboxes)
- REGRESSION section (including checkboxes)
- TESTING section
- RISK section
Copy link

Copilot AI Feb 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This skill says the PR description contains checkbox blocks for Customer Impact/Regression and instructs to preserve - [ ] / - [x], but the existing servicing PR template (.github/PULL_REQUEST_TEMPLATE/servicing_pull_request_template.md) only has section headings and HTML comments (no checkboxes). Either adjust this skill/template to not assume checkboxes exist, or update the servicing PR template in the same PR so the flow is consistent.

Copilot uses AI. Check for mistakes.
Copy link
Member

@jkotas jkotas Feb 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The problem is that there are two diverging copies of the servicing template committed in the repo. For example, one copy has check-boxes, the other one does not have check-boxes.

  • this template is used most of the time
    Backport of #%source_pr_number% to %target_branch%
    /cc %cc_users%
    ## Customer Impact
    - [ ] Customer reported
    - [ ] Found internally
    [Select one or both of the boxes. Describe how this issue impacts customers, citing the expected and actual behaviors and scope of the issue. If customer-reported, provide the issue number.]
    ## Regression
    - [ ] Yes
    - [ ] No
    [If yes, specify when the regression was introduced. Provide the PR or commit if known.]
    ## Testing
    [How was the fix verified? How was the issue missed previously? What tests were added?]
    ## Risk
    [High/Medium/Low. Justify the indication by mentioning how risks were measured and addressed.]
    **IMPORTANT**: If this backport is for a servicing release, please verify that:
    - For .NET 8 and .NET 9: The PR target branch is `release/X.0-staging`, not `release/X.0`.
    - For .NET 10+: The PR target branch is `release/X.0` (no `-staging` suffix).
    ## Package authoring no longer needed in .NET 9
    **IMPORTANT**: Starting with .NET 9, you no longer need to edit a NuGet package's csproj to enable building and bump the version.
    Keep in mind that we still need package authoring in .NET 8 and older versions.
    -
  • Second one https://github.com/dotnet/runtime/blob/18a3069ebfd2f1c1c07c5cb567e4714999e81e61/.github/PULL_REQUEST_TEMPLATE/servicing_pull_request_template.md?plain=1

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It can reference the yml the same way. I thought the backport bot used the servicing PR markdown. Guess not.

Steve Pfister added 2 commits February 7, 2026 15:50
Instead of duplicating the servicing PR template sections in the email
template, just instruct to copy the PR description verbatim. The
servicing_pull_request_template.md remains the single source of truth
for section structure.
Copilot AI review requested due to automatic review settings February 7, 2026 21:12
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.

- **Do NOT attempt to open the email in Outlook or any email client.** Just output the formatted text for the user to copy.
- Copy the PR description verbatim — do not rewrite or restructure it.
- Extract the release branch version (e.g., `9.0`) from the PR's base branch.
- If any section is missing from the PR description, note it and leave a placeholder.
Copy link

Copilot AI Feb 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There’s a contradiction between “Copy the PR description verbatim — do not rewrite or restructure it” and “If any section is missing from the PR description, note it and leave a placeholder.” If the PR description must be verbatim, missing-section placeholders should be added outside the verbatim block (or change the instruction to allow modifying the description).

Suggested change
- If any section is missing from the PR description, note it and leave a placeholder.
- If any section is missing from the PR description, note it in the email outside the copied PR description and leave a placeholder there.

Copilot uses AI. Check for mistakes.
# Backport Email Template

Use this template when emailing Tactics to request approval for a backport to a release branch.
The body of the email should be the PR description verbatim (from `servicing_pull_request_template.md`).
Copy link

Copilot AI Feb 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The template text says “The body of the email should be the PR description verbatim”, but the template itself includes additional body lines (greeting + links) before the PR description. Consider rewording to something like “After the header lines below, paste the PR description verbatim” to avoid confusion about what must be copied unchanged.

Suggested change
The body of the email should be the PR description verbatim (from `servicing_pull_request_template.md`).
After the header lines below, paste the PR description verbatim as the body of the email (from `servicing_pull_request_template.md`).

Copilot uses AI. Check for mistakes.
Output the email as **plain text** (not markdown) since email clients don't render markdown.

```
Subject: [release/X.0] Backport request: <TITLE> (#<PR_NUMBER>)
Copy link

Copilot AI Feb 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The placeholder naming in the sample output uses <TITLE>, but the template file uses <BRIEF_DESCRIPTION>. Using consistent placeholder names across both files will reduce confusion when following the instructions.

Suggested change
Subject: [release/X.0] Backport request: <TITLE> (#<PR_NUMBER>)
Subject: [release/X.0] Backport request: <BRIEF_DESCRIPTION> (#<PR_NUMBER>)

Copilot uses AI. Check for mistakes.

---

**Subject:** [release/X.0] Backport request: <BRIEF_DESCRIPTION> (#<PR_NUMBER>)
Copy link

Copilot AI Feb 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Although this file is Markdown, the template text is meant to be copied into an email as plain text. The **Subject:** markup will copy literally into the email; consider changing it to Subject: (and similarly avoid other Markdown-only formatting) so the template can be pasted directly without cleanup.

Suggested change
**Subject:** [release/X.0] Backport request: <BRIEF_DESCRIPTION> (#<PR_NUMBER>)
Subject: [release/X.0] Backport request: <BRIEF_DESCRIPTION> (#<PR_NUMBER>)

Copilot uses AI. Check for mistakes.
Comment on lines 3 to 4
Use this template when emailing Tactics to request approval for a backport to a release branch.
The body of the email should be the PR description verbatim (from `servicing_pull_request_template.md`).
Copy link

Copilot AI Feb 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The PR description says the email template includes standard sections with checkboxes (Customer Impact/Regression/Testing/Risk), but this template currently just points to pasting the PR description verbatim and doesn’t define any checkbox sections itself. Either update the template to include the promised checkbox sections, or adjust the PR description to match the actual behavior.

Copilot uses AI. Check for mistakes.
@jkotas
Copy link
Member

jkotas commented Feb 7, 2026

@copilot review this PR against Anthropic best practices for building skills

@steveisok
Copy link
Member Author

steveisok commented Feb 7, 2026

@copilot review this PR against Anthropic best practices for building skills

I did that earlier in the CLI, but didn't post it. Here's what I got before I created a templates folder:

The Anthropic skill format is essentially identical — no standard subdirectories either. The key points:

   - Required: Only SKILL.md with YAML frontmatter (name + description)
   - Optional: Any supporting files (scripts, templates, assets) alongside or in subdirectories — entirely up to the author
   - Location: .claude/skills/<skill-name>/ (Anthropic's path) or .github/skills/<skill-name>/ (GitHub's, which is what this repo uses — both are recognized)
   - Subdirectory structure is freeform — the spec doesn't prescribe any named subdirectories like templates/ or examples/

  Both the Anthropic and GitHub Copilot skill formats share the same open standard (agentskills.io (https://agentskills.io)). The backport-email skill's structure — SKILL.md + BACKPORT_EMAIL_TEMPLATE.md side by side in the
  skill folder — is consistent with both formats.

Copilot AI review requested due to automatic review settings February 7, 2026 23:33
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 6 comments.


---

**Subject:** [release/X.0] Backport request: <BRIEF_DESCRIPTION> (#<PR_NUMBER>)
Copy link

Copilot AI Feb 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Placeholder naming is inconsistent between the skill (<TITLE>) and the template (<BRIEF_DESCRIPTION>), which makes it harder to follow both. Align on a single placeholder name across both files.

Suggested change
**Subject:** [release/X.0] Backport request: <BRIEF_DESCRIPTION> (#<PR_NUMBER>)
**Subject:** [release/X.0] Backport request: <TITLE> (#<PR_NUMBER>)

Copilot uses AI. Check for mistakes.
Comment on lines +8 to +14
**Subject:** [release/X.0] Backport request: <BRIEF_DESCRIPTION> (#<PR_NUMBER>)

---

Hello Tactics,

Please consider https://github.com/dotnet/runtime/pull/<PR_NUMBER> for backporting into release/X.0.
Copy link

Copilot AI Feb 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This subject line hardcodes release/X.0, but backport PRs can target release/X.0-staging. Use a <TARGET_BRANCH> placeholder (filled from the PR base branch) so the email targets the correct branch.

Suggested change
**Subject:** [release/X.0] Backport request: <BRIEF_DESCRIPTION> (#<PR_NUMBER>)
---
Hello Tactics,
Please consider https://github.com/dotnet/runtime/pull/<PR_NUMBER> for backporting into release/X.0.
**Subject:** [<TARGET_BRANCH>] Backport request: <BRIEF_DESCRIPTION> (#<PR_NUMBER>)
---
Hello Tactics,
Please consider https://github.com/dotnet/runtime/pull/<PR_NUMBER> for backporting into <TARGET_BRANCH>.

Copilot uses AI. Check for mistakes.
Comment on lines +8 to +14
**Subject:** [release/X.0] Backport request: <BRIEF_DESCRIPTION> (#<PR_NUMBER>)

---

Hello Tactics,

Please consider https://github.com/dotnet/runtime/pull/<PR_NUMBER> for backporting into release/X.0.
Copy link

Copilot AI Feb 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This line hardcodes release/X.0, but the correct backport target can be release/X.0-staging. Use <TARGET_BRANCH> (from the PR base branch) here to avoid requesting approval for the wrong branch.

Suggested change
**Subject:** [release/X.0] Backport request: <BRIEF_DESCRIPTION> (#<PR_NUMBER>)
---
Hello Tactics,
Please consider https://github.com/dotnet/runtime/pull/<PR_NUMBER> for backporting into release/X.0.
**Subject:** [<TARGET_BRANCH>] Backport request: <BRIEF_DESCRIPTION> (#<PR_NUMBER>)
---
Hello Tactics,
Please consider https://github.com/dotnet/runtime/pull/<PR_NUMBER> for backporting into <TARGET_BRANCH>.

Copilot uses AI. Check for mistakes.
Comment on lines +18 to +20
- PR number and title
- Target release branch (e.g., `release/9.0`)
- PR description (filled in from the `pr_description_template` in `.github/workflows/backport.yml`)
Copy link

Copilot AI Feb 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This suggests the target branch is something like release/9.0, but servicing backports may target release/X.0-staging (see the notes in .github/workflows/backport.yml). Consider updating the example/wording to reflect that the base branch might include -staging.

Copilot uses AI. Check for mistakes.

- **Do NOT attempt to open the email in Outlook or any email client.** Just output the formatted text for the user to copy.
- Copy the PR description verbatim — do not rewrite or restructure it.
- Extract the release branch version (e.g., `9.0`) from the PR's base branch.
Copy link

Copilot AI Feb 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The instructions say to extract the release branch version (e.g., 9.0) from the PR base branch, but that would drop a -staging suffix and can produce the wrong target (e.g., release/9.0 vs release/9.0-staging). Use the full base branch name as the target branch in the generated subject/body.

Copilot uses AI. Check for mistakes.
Comment on lines +34 to +38
Subject: [release/X.0] Backport request: <TITLE> (#<PR_NUMBER>)

Hello Tactics,

Please consider https://github.com/dotnet/runtime/pull/<PR_NUMBER> for backporting into release/X.0.
Copy link

Copilot AI Feb 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The sample email hardcodes release/X.0 in the subject/body. Backport PRs may target release/X.0-staging, so this can generate an approval request for the wrong branch. Use a <TARGET_BRANCH> placeholder populated from the PR base branch instead of release/X.0.

Copilot uses AI. Check for mistakes.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

needs-area-label An area label is needed to ensure this gets routed to the appropriate area owners

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants