Conversation
There was a problem hiding this comment.
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.mdwith sections for Customer Impact, Regression, Testing, and Risk assessment to standardize backport requests
.github/BACKPORT_EMAIL_TEMPLATE.md
Outdated
|
|
||
| --- | ||
|
|
||
| **Subject:** [release/X.0] Backport request: <Brief description> (#<PR number>) |
There was a problem hiding this comment.
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>.
| **Subject:** [release/X.0] Backport request: <Brief description> (#<PR number>) | |
| **Subject:** [release/X.0] Backport request: <BRIEF_DESCRIPTION> (#<PR_NUMBER>) |
Adds a template for emailing Tactics to request approval for backports to release branches, with standard sections for Customer Impact, Regression, Testing, and Risk.
c3a25ac to
1a4401e
Compare
.github/BACKPORT_EMAIL_TEMPLATE.md
Outdated
|
|
||
| --- | ||
|
|
||
| **Subject:** [release/X.0] Backport request: <Brief description> (#<PR number>) |
There was a problem hiding this comment.
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.
| **Subject:** [release/X.0] Backport request: <Brief description> (#<PR number>) | |
| **Subject:** [release/X.0] Backport request: <BRIEF_DESCRIPTION> (#<PR_NUMBER>) |
.github/BACKPORT_EMAIL_TEMPLATE.md
Outdated
|
|
||
| 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. |
There was a problem hiding this comment.
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.
| > **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). |
.github/BACKPORT_EMAIL_TEMPLATE.md
Outdated
| - [ ] Customer reported | ||
| - [ ] Found internally |
There was a problem hiding this comment.
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.
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
|
@jkotas it should now work like this:
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. |
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 #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 | |||
There was a problem hiding this comment.
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.)
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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
There was a problem hiding this comment.
Yes, I created a template folder and moved it into there.
.github/BACKPORT_EMAIL_TEMPLATE.md
Outdated
| **RISK** | ||
|
|
||
| <Copy from PR: Risk section> |
There was a problem hiding this comment.
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.
| Output the email as **plain text** (not markdown) since email clients don't render markdown. | ||
|
|
||
| ``` | ||
| Subject: [release/X.0] Backport request: <TITLE> (#<PR_NUMBER>) |
There was a problem hiding this comment.
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).
| Subject: [release/X.0] Backport request: <TITLE> (#<PR_NUMBER>) | |
| Subject: [release/X.0] Backport request: <BRIEF_DESCRIPTION> (#<PR_NUMBER>) |
| 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 |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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 -
runtime/.github/workflows/backport.yml
Lines 21 to 55 in 18a3069
- Second one https://github.com/dotnet/runtime/blob/18a3069ebfd2f1c1c07c5cb567e4714999e81e61/.github/PULL_REQUEST_TEMPLATE/servicing_pull_request_template.md?plain=1
There was a problem hiding this comment.
It can reference the yml the same way. I thought the backport bot used the servicing PR markdown. Guess not.
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.
| - **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. |
There was a problem hiding this comment.
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).
| - 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. |
| # 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`). |
There was a problem hiding this comment.
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.
| 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`). |
| Output the email as **plain text** (not markdown) since email clients don't render markdown. | ||
|
|
||
| ``` | ||
| Subject: [release/X.0] Backport request: <TITLE> (#<PR_NUMBER>) |
There was a problem hiding this comment.
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.
| Subject: [release/X.0] Backport request: <TITLE> (#<PR_NUMBER>) | |
| Subject: [release/X.0] Backport request: <BRIEF_DESCRIPTION> (#<PR_NUMBER>) |
|
|
||
| --- | ||
|
|
||
| **Subject:** [release/X.0] Backport request: <BRIEF_DESCRIPTION> (#<PR_NUMBER>) |
There was a problem hiding this comment.
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.
| **Subject:** [release/X.0] Backport request: <BRIEF_DESCRIPTION> (#<PR_NUMBER>) | |
| Subject: [release/X.0] Backport request: <BRIEF_DESCRIPTION> (#<PR_NUMBER>) |
| 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`). |
There was a problem hiding this comment.
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 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: |
|
|
||
| --- | ||
|
|
||
| **Subject:** [release/X.0] Backport request: <BRIEF_DESCRIPTION> (#<PR_NUMBER>) |
There was a problem hiding this comment.
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.
| **Subject:** [release/X.0] Backport request: <BRIEF_DESCRIPTION> (#<PR_NUMBER>) | |
| **Subject:** [release/X.0] Backport request: <TITLE> (#<PR_NUMBER>) |
| **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. |
There was a problem hiding this comment.
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.
| **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>. |
| **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. |
There was a problem hiding this comment.
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.
| **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>. |
| - 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`) |
There was a problem hiding this comment.
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.
|
|
||
| - **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. |
There was a problem hiding this comment.
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.
| 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. |
There was a problem hiding this comment.
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.
This adds a template for emailing Tactics to request approval for backports to release branches.
The template includes standard sections:
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.