From d6d6e39d41317c56fe4d67d90f69e7c98dbc5775 Mon Sep 17 00:00:00 2001 From: Guillaume Hetier Date: Thu, 11 Jun 2026 12:44:49 -0700 Subject: [PATCH 1/3] Add cherry-pick-to-release skill Encodes the patterns the project uses when back-porting PRs from main to release branches (release/2.4, release/2.5, ...), derived from ~30 recent cherry-pick PRs and commits on those branches: - PR title format: [CP] (#) - Branch naming: /cp__ - One PR per release branch - Standard MsQuic PR template body referencing the original PR - CLOG / dotnet regeneration when traces or src/inc/ are touched - No git cherry-pick -x trailers (not used by the project) - Open PRs as draft; never push without explicit user permission Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../skills/cherry-pick-to-release/SKILL.md | 260 ++++++++++++++++++ 1 file changed, 260 insertions(+) create mode 100644 .github/skills/cherry-pick-to-release/SKILL.md diff --git a/.github/skills/cherry-pick-to-release/SKILL.md b/.github/skills/cherry-pick-to-release/SKILL.md new file mode 100644 index 0000000000..1aef417b56 --- /dev/null +++ b/.github/skills/cherry-pick-to-release/SKILL.md @@ -0,0 +1,260 @@ +--- +name: cherry-pick-to-release +description: 'Cherry-pick a merged main-branch PR onto a MsQuic release branch (e.g. release/2.4, release/2.5) following the project''s established conventions.' +--- + +# Cherry-Pick to MsQuic Release Branch + +You are helping a maintainer back-port a fix from `main` to one or more +MsQuic release branches (`release/2.4`, `release/2.5`, etc.). + +This skill encodes the patterns the project actually uses — derived from +recent cherry-pick PRs and commits on `release/2.4` and `release/2.5`. + +## When This Skill Activates + +The user asks to cherry-pick / back-port / "CP" a PR or commit from `main` +onto a release branch. Typical requests: + +- "Cherry-pick #5942 to release/2.4 and release/2.5" +- "Back-port the ACK underflow fix to 2.5" +- "CP this commit to the 2.4 release branch" + +## Inputs You Need + +Before doing anything, make sure you know: + +1. **Source**: a PR number on `main` (preferred) or a commit SHA on `origin/main`. +2. **Target release branch(es)**: e.g. `release/2.4`, `release/2.5`. If the + user is ambiguous (e.g. "to the release branches"), ask whether they want + one branch or both, and which. +3. **Whether to push / open a PR**. Per the user's standing rule, you must + never push a branch or open a PR without explicit permission. Stop and + ask before any `git push` or `gh pr create`. + +If anything is missing, ask before proceeding. + +## Project Conventions (must follow) + +These were inferred from ~30 recent cherry-pick PRs to `release/2.4` and +`release/2.5`. Match them exactly unless the user tells you otherwise. + +### PR Title + +Dominant pattern: + +``` +[CP] (#) +``` + +Examples actually used on the release branches: + +- `[CP] Fix underflow in ACK frame parsing #5942` (→ PR #5943 on 2.5, #5944 on 2.4) +- `[CP] Fix SAL annotation placement on function templates (#5895)` +- `[CP] Free AES 256 GCM algorithm handle on cleanup (#5526)` +- `[CP] Fix double deref in connection pool error path (#5597)` + +When the same fix targets multiple release branches, the title is identical +across PRs; only the target branch differs. After squash-merge, GitHub +appends the new PR number, producing commits like +`[CP] Fix underflow in ACK frame parsing #5942 (#5943)` on the release +branch — this is expected and required (it makes traceability trivial). + +Acceptable variants (use only if the user prefers them or the situation +calls for it): + +- `[CP v2.5] (#<orig_pr>)` — when the target branch needs to be + explicit in the title. +- `[CP] <title A> (#<prA>) + <title B> (#<prB>)` — multi-PR cherry-pick in + one branch. +- `CP: <title> (#<orig_pr>)` / `Cherry-pick: <title> (#<orig_pr>)` — + older style, still accepted. + +Do **not** invent new prefixes; stick to `[CP]` unless asked. + +### PR Body + +Reuse the standard MsQuic PR template +(`.github/pull_request_template.md`) with three sections: `## Description`, +`## Testing`, `## Documentation`. + +Typical content: + +- **Description** — either: + - A short statement: `Cherry-pick of #<orig_pr>` / `Cherry-pick of #<orig_pr> to release 2.5`, or + - The original PR's description (verbatim or lightly condensed), so reviewers don't have to click through. Preferred when the fix is non-trivial. +- **Testing** — usually `CI`, `Existing testing.`, or + `Test not backported as they rely on changes present only in main` if + tests couldn't be cleanly back-ported. +- **Documentation** — usually `N/A` or `No` unless the cherry-pick + changes docs. + +If the original PR description references an upstream issue, keep the +`Fixes #<issue>` line so the issue closes when the cherry-pick merges. + +### Branch Naming + +Project convention (observed on most recent cherry-pick PRs): + +``` +<user>/cp_<short_description>_<target_version> +``` + +For the current user (`@guhetier_microsoft`), the additional standing +rule is that branches created by Copilot must end in `_copilot`. Combine +both → use: + +``` +guhetier/cp_<short_description>_2_5_copilot +guhetier/cp_<short_description>_2_4_copilot +``` + +The `<short_description>` is a snake_case summary of the fix, mirroring +prior branches like `cp_conn_pool_deref`, `cp_free_aes_256_gcm_handle`, +`underflow_fix_cp`. + +Use one branch per target release branch (do not try to land both +release branches from a single branch / PR). + +### Commits Inside the PR + +- Almost always **one commit** — the cherry-picked commit, with its + original message preserved. +- Occasionally a **second commit** is acceptable if needed to make the + release branch build/pass tests (e.g. `Add missing variable definition`, + `Upgrade perl action`). Keep these tightly scoped to enabling the + cherry-pick; do **not** sneak in unrelated changes. +- Squash-merge erases the multi-commit structure on the release branch. +- Do **not** add `(cherry picked from commit X)` trailers — the project + doesn't use `git cherry-pick -x`; traceability comes from the PR title + containing the original PR number. + +## Workflow + +Follow these steps in order. Do not skip a phase. + +### Phase 1 — Identify the source commit on main + +1. If given a PR number, find its squash-merge commit on `origin/main`: + ```powershell + gh pr view <orig_pr> --repo microsoft/msquic --json mergeCommit,state,title,body,baseRefName + ``` + Verify `state == MERGED` and `baseRefName == main`. If not merged, stop and tell the user — never cherry-pick an unmerged change. +2. If given a SHA, confirm it is reachable from `origin/main`: + ```powershell + git --no-pager log -1 --format="%H %s" <sha> + git --no-pager branch -r --contains <sha> | Select-String "origin/main" + ``` +3. Capture the original PR title and body — you'll reuse them. + +### Phase 2 — Prepare the local branch + +Repeat for each target release branch. + +1. Make sure the working tree is clean (`git status`). If not, stop and ask. +2. Fetch latest refs: `git fetch origin --prune`. +3. Create the branch from the tip of the release branch: + ```powershell + git checkout -b guhetier/cp_<short_desc>_2_5_copilot origin/release/2.5 + ``` + +### Phase 3 — Apply the cherry-pick + +1. Run `git cherry-pick <commit_sha>` (no `-x`). +2. **On conflicts**: + - Resolve them, keeping the spirit of the original fix. + - If the conflict is non-trivial, briefly summarize the resolution in the PR body under `## Description` so reviewers know what differs from `main`. + - If the fix depends on code that doesn't exist on the release branch, **stop and ask the user** how to proceed (skip, adapt, or pull in additional commits) — do not silently rewrite the fix. +3. If the original change touched tests that depend on main-only APIs and they don't apply cleanly, you may drop those test changes and note `Test not backported as they rely on changes present only in main` in the PR body. Try to keep at least one regression test when feasible. + +### Phase 4 — Regenerate derived files (only if applicable) + +Check whether the cherry-pick touches things that require regeneration. CI +will fail otherwise (`check-clog.yml`, `check-dotnet.yml`). + +- **Trace / log macro changes** (`QuicTraceLogInfo`, `QuicTraceEvent`, + etc., or anything under `src/manifest/`): + ```powershell + ./scripts/update-sidecar.ps1 + ``` + Commit any changes under `src/generated/` and `src/manifest/clog.sidecar` as part of the same commit (or amend). + +- **Public C API surface changes** (anything under `src/inc/`, especially `msquic.h`): + ```powershell + ./scripts/generate-dotnet.ps1 + ``` + Commit any changes under `src/cs/`. + +If neither applies, skip this phase. + +### Phase 5 — Build / verify locally + +If the cherry-pick had conflicts or required adaptation, build locally +before pushing: + +```powershell +./scripts/build.ps1 -Tls schannel +``` + +If tests are easily runnable and relevant, run them. For pure +configuration / CI / build-system cherry-picks, relying on CI is +acceptable (this is what most existing CP PRs do — see `## Testing: CI`). + +### Phase 6 — Push and open the PR (gated on explicit user permission) + +Stop here and confirm with the user before pushing. Then: + +1. Push the branch: + ```powershell + git push -u origin guhetier/cp_<short_desc>_2_5_copilot + ``` +2. Open the PR as a **draft** (per the user's standing rule, unless they say otherwise): + ```powershell + gh pr create --repo microsoft/msquic ` + --base release/2.5 ` + --head guhetier/cp_<short_desc>_2_5_copilot ` + --draft ` + --title "[CP] <Original title> (#<orig_pr>)" ` + --body-file <path_to_body.md> + ``` + - `--base` must be the release branch (`release/2.4`, `release/2.5`, …), **not** `main`. +3. If cherry-picking to multiple release branches, repeat phases 2–6 for each branch. Open one PR per branch; mention the sibling PR number in each body so reviewers can correlate them (e.g. `Companion PR for release/2.4: #5944`). + +## Self-Verification Checklist + +Before telling the user the cherry-pick is ready: + +- [ ] PR `--base` is the correct `release/X.Y` branch (never `main`). +- [ ] PR title is `[CP] <orig title> (#<orig_pr>)` (or an explicitly approved variant). +- [ ] PR body uses the three template sections and references the original PR. +- [ ] Branch name follows `guhetier/cp_<short_desc>_<X_Y>_copilot`. +- [ ] PR is opened as a draft. +- [ ] Only the cherry-picked commit (+ optional minimal build-fix commits) is on the branch — no unrelated changes. +- [ ] If trace/log macros were touched → `scripts/update-sidecar.ps1` was run and generated files committed. +- [ ] If `src/inc/` public headers were touched → `scripts/generate-dotnet.ps1` was run and generated files committed. +- [ ] For multi-branch cherry-picks, one PR per release branch (not a single PR targeting multiple branches). +- [ ] You obtained explicit user permission before pushing and opening the PR. + +## Anti-Patterns to Avoid + +- **Don't** cherry-pick a PR that isn't merged on `main` yet. +- **Don't** target both `release/2.4` and `release/2.5` from a single PR. +- **Don't** use `git cherry-pick -x` — the project doesn't include + `(cherry picked from commit X)` trailers in the final commit message. +- **Don't** bundle unrelated fixes into the same cherry-pick PR. If you + see a related-but-distinct issue, open a separate cherry-pick. +- **Don't** invent a new title prefix (e.g. `[BACKPORT 2.5]`) — stick to + `[CP]` to stay consistent with the last ~2 years of cherry-pick PRs. +- **Don't** silently drop test changes. If you skip back-porting tests, + call it out explicitly in `## Testing`. +- **Don't** push or open a PR without explicit user permission. +- **Don't** bump the version number as part of a cherry-pick PR — + version bumps (`Bump version to v2.5.X`) are separate PRs done at + release time. + +## Non-Goals + +- Triaging whether a fix *should* be cherry-picked. The user decides + that; this skill just executes the cherry-pick cleanly. +- Releasing / tagging / publishing artifacts. Those are separate + processes handled outside this skill. From d77963eecc5265528ca9b28d6e16d52760872646 Mon Sep 17 00:00:00 2001 From: Guillaume Hetier <guhetier@microsoft.com> Date: Thu, 11 Jun 2026 13:19:46 -0700 Subject: [PATCH 2/3] Skill: require verbatim original PR body + mandatory local build/test Per maintainer guidance, the cherry-pick skill now requires: - The PR body must be the exact original PR description verbatim. Only a short 'Cherry-pick of #<orig_pr>' prefix line and an optional companion PR cross-reference are allowed outside the verbatim body. - Phase 5 (build + run relevant tests locally) is now required for every cherry-pick, not just ones with conflicts. Auto-merged hunks can still silently produce wrong code. Self-verification checklist and anti-patterns updated accordingly. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../skills/cherry-pick-to-release/SKILL.md | 83 ++++++++++++++----- 1 file changed, 61 insertions(+), 22 deletions(-) diff --git a/.github/skills/cherry-pick-to-release/SKILL.md b/.github/skills/cherry-pick-to-release/SKILL.md index 1aef417b56..dac6e44c9f 100644 --- a/.github/skills/cherry-pick-to-release/SKILL.md +++ b/.github/skills/cherry-pick-to-release/SKILL.md @@ -74,24 +74,29 @@ Do **not** invent new prefixes; stick to `[CP]` unless asked. ### PR Body -Reuse the standard MsQuic PR template -(`.github/pull_request_template.md`) with three sections: `## Description`, -`## Testing`, `## Documentation`. +**Use the exact body of the original PR, verbatim**, including the +`## Description`, `## Testing`, and `## Documentation` sections as the +original author wrote them. Do **not** rewrite, summarize, or augment them +with cherry-pick commentary. -Typical content: +Allowed additions, kept *outside* the verbatim original body: -- **Description** — either: - - A short statement: `Cherry-pick of #<orig_pr>` / `Cherry-pick of #<orig_pr> to release 2.5`, or - - The original PR's description (verbatim or lightly condensed), so reviewers don't have to click through. Preferred when the fix is non-trivial. -- **Testing** — usually `CI`, `Existing testing.`, or - `Test not backported as they rely on changes present only in main` if - tests couldn't be cleanly back-ported. -- **Documentation** — usually `N/A` or `No` unless the cherry-pick - changes docs. +- A single short prefix line (above the original `## Description`) + identifying this as a cherry-pick, e.g. `Cherry-pick of #<orig_pr>` or + `Cherry-pick of #<orig_pr> to release 2.5`. +- A companion-PR cross-reference when cherry-picking the same fix to + multiple branches (e.g. `Companion PR for release/2.4: #<sibling>`). + Add this as a separate trailing line, not inside the original sections. If the original PR description references an upstream issue, keep the `Fixes #<issue>` line so the issue closes when the cherry-pick merges. +If tests from the original PR could not be back-ported, do **not** alter +the original `## Testing` section. Instead, mention it in the cherry-pick +prefix line above the body (e.g. +`Cherry-pick of #<orig_pr>. Tests not back-ported — they rely on changes +present only in main.`). + ### Branch Naming Project convention (observed on most recent cherry-pick PRs): @@ -187,18 +192,42 @@ will fail otherwise (`check-clog.yml`, `check-dotnet.yml`). If neither applies, skip this phase. -### Phase 5 — Build / verify locally +### Phase 5 — Build and run tests locally (REQUIRED) -If the cherry-pick had conflicts or required adaptation, build locally -before pushing: +Build and run tests locally before pushing. This is **required for every +cherry-pick**, regardless of whether the `git cherry-pick` was clean or +required conflict resolution. Do not skip this phase. -```powershell -./scripts/build.ps1 -Tls schannel -``` +1. **Build** with the default TLS provider for the platform you're on: + ```powershell + ./scripts/build.ps1 -Tls schannel # Windows + pwsh ./scripts/build.ps1 -Tls openssl # Linux + ``` + If the cherry-pick touches OpenSSL- or QuicTLS-specific code on + Windows, also build with `-Tls openssl` / `-Tls quictls` (requires + Perl + NASM). -If tests are easily runnable and relevant, run them. For pure -configuration / CI / build-system cherry-picks, relying on CI is -acceptable (this is what most existing CP PRs do — see `## Testing: CI`). +2. **Run the tests that exercise the cherry-picked code.** Use a + GoogleTest `--Filter` to keep the runtime short: + ```powershell + ./scripts/test.ps1 -Tls schannel -Filter '<TestSuite>.<TestPattern>*' + ``` + At minimum, run: + - the tests that were added or modified by the cherry-pick, and + - the tests directly covering the changed code paths (e.g. + `TlsTest.*` for `src/platform/tls_*`, `ApiTest.*` for `src/inc/` + surface changes, `HandshakeTest.*` for `src/core/` handshake logic). + For pure CI / build-system cherry-picks where no functional tests + apply, run a representative smoke test (e.g. one BVT) and note that + in the PR body. + +3. If the build or the relevant tests fail on the release branch but + pass on `main`, **stop and ask the user** — do not push a broken + cherry-pick. Likely causes: missing prerequisite commits, API drift + between branches, or test infra changes that didn't get back-ported. + +Capture the build and test outcome (pass/fail, number of tests run) to +mention briefly when you ask for permission to push. ### Phase 6 — Push and open the PR (gated on explicit user permission) @@ -226,10 +255,12 @@ Before telling the user the cherry-pick is ready: - [ ] PR `--base` is the correct `release/X.Y` branch (never `main`). - [ ] PR title is `[CP] <orig title> (#<orig_pr>)` (or an explicitly approved variant). -- [ ] PR body uses the three template sections and references the original PR. +- [ ] PR body uses the **exact body of the original PR verbatim**, optionally with a single `Cherry-pick of #<orig_pr>` prefix line and a companion-PR cross-reference. No rewritten / summarized descriptions. - [ ] Branch name follows `guhetier/cp_<short_desc>_<X_Y>_copilot`. - [ ] PR is opened as a draft. - [ ] Only the cherry-picked commit (+ optional minimal build-fix commits) is on the branch — no unrelated changes. +- [ ] **Local build succeeded** on the release branch with the cherry-pick applied (Phase 5). +- [ ] **Relevant tests were run locally and pass** (Phase 5). The exact test filter and result are mentioned when asking the user for permission to push. - [ ] If trace/log macros were touched → `scripts/update-sidecar.ps1` was run and generated files committed. - [ ] If `src/inc/` public headers were touched → `scripts/generate-dotnet.ps1` was run and generated files committed. - [ ] For multi-branch cherry-picks, one PR per release branch (not a single PR targeting multiple branches). @@ -247,6 +278,14 @@ Before telling the user the cherry-pick is ready: `[CP]` to stay consistent with the last ~2 years of cherry-pick PRs. - **Don't** silently drop test changes. If you skip back-porting tests, call it out explicitly in `## Testing`. +- **Don't** rewrite, summarize, or paraphrase the original PR's + description. The body must contain the original PR's body verbatim + (you may prepend a short `Cherry-pick of #<orig_pr>` line and append a + companion-PR cross-reference, but the original sections themselves + stay intact). +- **Don't** skip the local build / test step (Phase 5), even when the + cherry-pick applied with no conflicts. Auto-merged hunks can still + produce subtly wrong code. - **Don't** push or open a PR without explicit user permission. - **Don't** bump the version number as part of a cherry-pick PR — version bumps (`Bump version to v2.5.X`) are separate PRs done at From 20ee853f916cf3bc20da866e718813abf4c0e8d9 Mon Sep 17 00:00:00 2001 From: Guillaume Hetier <guhetier@microsoft.com> Date: Thu, 11 Jun 2026 14:26:22 -0700 Subject: [PATCH 3/3] Skill: tighten conventions per maintainer review Maintainer-driven cleanup of the cherry-pick-to-release skill: - PR body must be the original PR body verbatim, with no additions (no cherry-pick prefix line, no companion-PR cross-reference). - Title variants (\[CP v2.5]\, \CP:\, \Cherry-pick:\, multi-PR titles) removed; \[CP] <orig title> (#<orig_pr>)\ is the only accepted form. - Branch naming generalized to \<user>/cp_<short_desc>_<X_Y>_copilot\ (no longer hard-coded to \guhetier/\). - Phase 6 now requires showing the user a structured summary (original PR, target branch, branch name, PR title, build/test status) before asking for permission to push. - Minor trimming of redundant guidance throughout (build-system smoke tests, OpenSSL/QuicTLS extra build hint, test back-port wording, etc.). - Fixed missing closing quote in YAML frontmatter \description\. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../skills/cherry-pick-to-release/SKILL.md | 90 ++++--------------- 1 file changed, 18 insertions(+), 72 deletions(-) diff --git a/.github/skills/cherry-pick-to-release/SKILL.md b/.github/skills/cherry-pick-to-release/SKILL.md index dac6e44c9f..b4062eb72a 100644 --- a/.github/skills/cherry-pick-to-release/SKILL.md +++ b/.github/skills/cherry-pick-to-release/SKILL.md @@ -1,6 +1,6 @@ --- name: cherry-pick-to-release -description: 'Cherry-pick a merged main-branch PR onto a MsQuic release branch (e.g. release/2.4, release/2.5) following the project''s established conventions.' +description: 'Cherry-pick a merged main-branch PR onto a MsQuic release branch (release/X.Y).' --- # Cherry-Pick to MsQuic Release Branch @@ -8,8 +8,7 @@ description: 'Cherry-pick a merged main-branch PR onto a MsQuic release branch ( You are helping a maintainer back-port a fix from `main` to one or more MsQuic release branches (`release/2.4`, `release/2.5`, etc.). -This skill encodes the patterns the project actually uses — derived from -recent cherry-pick PRs and commits on `release/2.4` and `release/2.5`. +This skill encodes the patterns the project uses. ## When This Skill Activates @@ -28,21 +27,15 @@ Before doing anything, make sure you know: 2. **Target release branch(es)**: e.g. `release/2.4`, `release/2.5`. If the user is ambiguous (e.g. "to the release branches"), ask whether they want one branch or both, and which. -3. **Whether to push / open a PR**. Per the user's standing rule, you must - never push a branch or open a PR without explicit permission. Stop and - ask before any `git push` or `gh pr create`. +3. **Whether to push / open a PR**. You must never push a branch or open a PR + without explicit permission. Stop and ask before any `git push` or `gh pr create`. If anything is missing, ask before proceeding. ## Project Conventions (must follow) -These were inferred from ~30 recent cherry-pick PRs to `release/2.4` and -`release/2.5`. Match them exactly unless the user tells you otherwise. - ### PR Title -Dominant pattern: - ``` [CP] <Original PR title> (#<original_pr_number>) ``` @@ -60,16 +53,6 @@ appends the new PR number, producing commits like `[CP] Fix underflow in ACK frame parsing #5942 (#5943)` on the release branch — this is expected and required (it makes traceability trivial). -Acceptable variants (use only if the user prefers them or the situation -calls for it): - -- `[CP v2.5] <title> (#<orig_pr>)` — when the target branch needs to be - explicit in the title. -- `[CP] <title A> (#<prA>) + <title B> (#<prB>)` — multi-PR cherry-pick in - one branch. -- `CP: <title> (#<orig_pr>)` / `Cherry-pick: <title> (#<orig_pr>)` — - older style, still accepted. - Do **not** invent new prefixes; stick to `[CP]` unless asked. ### PR Body @@ -79,39 +62,14 @@ Do **not** invent new prefixes; stick to `[CP]` unless asked. original author wrote them. Do **not** rewrite, summarize, or augment them with cherry-pick commentary. -Allowed additions, kept *outside* the verbatim original body: - -- A single short prefix line (above the original `## Description`) - identifying this as a cherry-pick, e.g. `Cherry-pick of #<orig_pr>` or - `Cherry-pick of #<orig_pr> to release 2.5`. -- A companion-PR cross-reference when cherry-picking the same fix to - multiple branches (e.g. `Companion PR for release/2.4: #<sibling>`). - Add this as a separate trailing line, not inside the original sections. - -If the original PR description references an upstream issue, keep the -`Fixes #<issue>` line so the issue closes when the cherry-pick merges. - -If tests from the original PR could not be back-ported, do **not** alter -the original `## Testing` section. Instead, mention it in the cherry-pick -prefix line above the body (e.g. -`Cherry-pick of #<orig_pr>. Tests not back-ported — they rely on changes -present only in main.`). +No additions or modification of the original description is acceptable. ### Branch Naming Project convention (observed on most recent cherry-pick PRs): ``` -<user>/cp_<short_description>_<target_version> -``` - -For the current user (`@guhetier_microsoft`), the additional standing -rule is that branches created by Copilot must end in `_copilot`. Combine -both → use: - -``` -guhetier/cp_<short_description>_2_5_copilot -guhetier/cp_<short_description>_2_4_copilot +<user>/cp_<short_description>_<target_version>_copilot ``` The `<short_description>` is a snake_case summary of the fix, mirroring @@ -126,9 +84,8 @@ release branches from a single branch / PR). - Almost always **one commit** — the cherry-picked commit, with its original message preserved. - Occasionally a **second commit** is acceptable if needed to make the - release branch build/pass tests (e.g. `Add missing variable definition`, - `Upgrade perl action`). Keep these tightly scoped to enabling the - cherry-pick; do **not** sneak in unrelated changes. + release branch build/pass tests (merge conflict resolutions and build fixes). + Keep these tightly scoped to enabling the cherry-pick; do **not** sneak in unrelated changes. - Squash-merge erases the multi-commit structure on the release branch. - Do **not** add `(cherry picked from commit X)` trailers — the project doesn't use `git cherry-pick -x`; traceability comes from the PR title @@ -160,7 +117,7 @@ Repeat for each target release branch. 2. Fetch latest refs: `git fetch origin --prune`. 3. Create the branch from the tip of the release branch: ```powershell - git checkout -b guhetier/cp_<short_desc>_2_5_copilot origin/release/2.5 + git checkout -b <user>/cp_<short_desc>_2_5_copilot origin/release/2.5 ``` ### Phase 3 — Apply the cherry-pick @@ -170,7 +127,6 @@ Repeat for each target release branch. - Resolve them, keeping the spirit of the original fix. - If the conflict is non-trivial, briefly summarize the resolution in the PR body under `## Description` so reviewers know what differs from `main`. - If the fix depends on code that doesn't exist on the release branch, **stop and ask the user** how to proceed (skip, adapt, or pull in additional commits) — do not silently rewrite the fix. -3. If the original change touched tests that depend on main-only APIs and they don't apply cleanly, you may drop those test changes and note `Test not backported as they rely on changes present only in main` in the PR body. Try to keep at least one regression test when feasible. ### Phase 4 — Regenerate derived files (only if applicable) @@ -203,9 +159,6 @@ required conflict resolution. Do not skip this phase. ./scripts/build.ps1 -Tls schannel # Windows pwsh ./scripts/build.ps1 -Tls openssl # Linux ``` - If the cherry-pick touches OpenSSL- or QuicTLS-specific code on - Windows, also build with `-Tls openssl` / `-Tls quictls` (requires - Perl + NASM). 2. **Run the tests that exercise the cherry-picked code.** Use a GoogleTest `--Filter` to keep the runtime short: @@ -217,9 +170,6 @@ required conflict resolution. Do not skip this phase. - the tests directly covering the changed code paths (e.g. `TlsTest.*` for `src/platform/tls_*`, `ApiTest.*` for `src/inc/` surface changes, `HandshakeTest.*` for `src/core/` handshake logic). - For pure CI / build-system cherry-picks where no functional tests - apply, run a representative smoke test (e.g. one BVT) and note that - in the PR body. 3. If the build or the relevant tests fail on the release branch but pass on `main`, **stop and ask the user** — do not push a broken @@ -231,17 +181,19 @@ mention briefly when you ask for permission to push. ### Phase 6 — Push and open the PR (gated on explicit user permission) -Stop here and confirm with the user before pushing. Then: +Stop here and show a summary of the cherry-pick to the user: +original PR, target branch, branch name, PR title, build and test status. +Confirm with the user before pushing. Then: 1. Push the branch: ```powershell - git push -u origin guhetier/cp_<short_desc>_2_5_copilot + git push -u origin <user>/cp_<short_desc>_2_5_copilot ``` 2. Open the PR as a **draft** (per the user's standing rule, unless they say otherwise): ```powershell gh pr create --repo microsoft/msquic ` --base release/2.5 ` - --head guhetier/cp_<short_desc>_2_5_copilot ` + --head <user>/cp_<short_desc>_2_5_copilot ` --draft ` --title "[CP] <Original title> (#<orig_pr>)" ` --body-file <path_to_body.md> @@ -255,34 +207,28 @@ Before telling the user the cherry-pick is ready: - [ ] PR `--base` is the correct `release/X.Y` branch (never `main`). - [ ] PR title is `[CP] <orig title> (#<orig_pr>)` (or an explicitly approved variant). -- [ ] PR body uses the **exact body of the original PR verbatim**, optionally with a single `Cherry-pick of #<orig_pr>` prefix line and a companion-PR cross-reference. No rewritten / summarized descriptions. -- [ ] Branch name follows `guhetier/cp_<short_desc>_<X_Y>_copilot`. +- [ ] PR body uses the **exact body of the original PR verbatim** with no additions. +- [ ] Branch name follows `<user>/cp_<short_desc>_<X_Y>_copilot`. - [ ] PR is opened as a draft. - [ ] Only the cherry-picked commit (+ optional minimal build-fix commits) is on the branch — no unrelated changes. - [ ] **Local build succeeded** on the release branch with the cherry-pick applied (Phase 5). - [ ] **Relevant tests were run locally and pass** (Phase 5). The exact test filter and result are mentioned when asking the user for permission to push. - [ ] If trace/log macros were touched → `scripts/update-sidecar.ps1` was run and generated files committed. - [ ] If `src/inc/` public headers were touched → `scripts/generate-dotnet.ps1` was run and generated files committed. -- [ ] For multi-branch cherry-picks, one PR per release branch (not a single PR targeting multiple branches). - [ ] You obtained explicit user permission before pushing and opening the PR. ## Anti-Patterns to Avoid - **Don't** cherry-pick a PR that isn't merged on `main` yet. -- **Don't** target both `release/2.4` and `release/2.5` from a single PR. - **Don't** use `git cherry-pick -x` — the project doesn't include `(cherry picked from commit X)` trailers in the final commit message. - **Don't** bundle unrelated fixes into the same cherry-pick PR. If you see a related-but-distinct issue, open a separate cherry-pick. - **Don't** invent a new title prefix (e.g. `[BACKPORT 2.5]`) — stick to `[CP]` to stay consistent with the last ~2 years of cherry-pick PRs. -- **Don't** silently drop test changes. If you skip back-porting tests, - call it out explicitly in `## Testing`. +- **Don't** silently drop test changes. - **Don't** rewrite, summarize, or paraphrase the original PR's - description. The body must contain the original PR's body verbatim - (you may prepend a short `Cherry-pick of #<orig_pr>` line and append a - companion-PR cross-reference, but the original sections themselves - stay intact). + description. The body must contain the original PR's body verbatim without additions. - **Don't** skip the local build / test step (Phase 5), even when the cherry-pick applied with no conflicts. Auto-merged hunks can still produce subtly wrong code.