Skip to content

Add release backport helpers and maintainer guidance - #42275

Open
Ben Hillis (benhillis) wants to merge 7 commits into
masterfrom
benhill/release-backport-helpers
Open

Ben Hillis (benhillis) wants to merge 7 commits into
masterfrom
benhill/release-backport-helpers

Conversation

@benhillis

@benhillis Ben Hillis (benhillis) commented Nov 13, 2026 •

Copy link
Copy Markdown
Member

Summary of the Pull Request

Add preview-first maintainer tools for creating release backport PRs and updating the original PRs' backport labels, along with a release-backport guide and repository skill.

PR Checklist

  • Closes: No linked issue.
  • Communication: I've discussed this with core contributors already. If work hasn't been agreed, this work might be rejected
  • Tests: Added/updated if needed and all pass
  • Localization: All end user facing strings can be localized
  • Dev docs: Added/updated if needed
  • Documentation updated: If checked, please file a pull request on our docs repo and link it here: Not applicable (repository maintainer guidance only).

Detailed Description of the Pull Request / Additional comments

  • gen_cherrypick_prs.py selects merged default-branch PRs by release label or explicit number, orders them by merge time, and previews independent backport PRs. --apply creates branches, cherry-picks with provenance, pushes only the branch without force or tag following, and creates PRs. Backport metadata precedes the unchanged repository template without depending on exact headings.
  • relabel_backported.py previews which original PRs have reached the release branch. --apply replaces their pending label with the completed label, preserving existing label metadata.
  • Shared helpers validate the repository and every push destination, fetch explicit release refs without applying configured ref mappings, and recognize exact cherry-pick provenance and standard Git revert/reapply messages rather than quoted historical bodies. Revert subjects support the generated release prefix and repeated PR-number suffixes. Reverting a cherry-pick allows a retry even when its enclosing backport merge remains in history. Active merge reverts, repeated reversals through cherry-pick aliases, active reversal targets outside reachable history, reverted constituents of selected original merge commits, and merged backports without recognizable source provenance stop automation for manual review rather than guessing patch state.
  • Existing local attempts are skipped rather than reset. Failed cherry-picks preserve the resolution state and stop before pushing that attempt. Neither helper posts comments, changes repository protections, approves, or merges PRs.
  • Document selection, labels, previews, validation, conflicts, retries, and conservative completion detection. Add a reusable repository skill with explicit authorization boundaries.

The helpers use Click and GitPython from the existing tools/devops/requirements.txt, plus authenticated GitHub CLI. GitPython repositories are injected into the command logic for testing. There are no WSL runtime changes or new package dependencies. The localization checklist is not checked: output is maintainer-tool text, not localized WSL application UI.

Validation Steps Performed

  • python -m unittest discover -s tools\devops -p test_backports.py -v — Passed: 37 tests. Injected mock GitPython repositories cover Click command orchestration and conflicting preview/apply flags. Temporary Git repositories and mocked GitHub calls cover preview/apply behavior, independent branches, conflict preservation, retries, remote/ref safety, provenance, labels, standard reverts (including generated release prefixes and repeated GitHub PR-number suffixes), quoted revert bodies, and manual-review limitations. Template heading changes no longer break generation. An actual push to a local bare remote verifies that push.followTags=true does not publish an unrelated annotated tag. The latest regressions reproduce alias-target reversals, reversals carried from another release, reverted constituents of inherited source merges, and prefixed squash subjects; all failed before the fixes and pass afterward. Existing retry and revert-of-revert cases still pass.
  • python tools\devops\gen_cherrypick_prs.py 3.0 — Passed. Live read-only preview identified the pending backport; no branch, PR, or label writes.
  • python tools\devops\relabel_backported.py 3.0 — Passed. Live read-only preview found no completed candidates.
  • .\FormatSource.ps1 -Verify $true — Passed: no modified files requiring clang-format.
  • git --no-pager diff --cached --check — Passed.
  • python -m mkdocs build -f doc\mkdocs.yml — Failed rendering the unchanged api-reference/c/end-to-end-example.md: Pygments/pymdown highlighting reaches html.escape(None) and raises AttributeError. The new guide was separately rendered successfully, and the skill frontmatter parsed successfully.
  • python tools\devops\validate-copyright-headers.py — Failed while reporting missing headers in the existing checkout/build-dependency tree: output encoding raised UnicodeEncodeError (cp1252). The new Python files include copyright headers; no C/C++ files changed.
  • Full WSL build and Windows component tests — Not run: this change is limited to Python maintainer tools and documentation.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 98cc0b78-dd28-46e2-bc0a-5ae7950ae5ce
@benhillis
Ben Hillis (benhillis) requested a review from a team as a code owner November 13, 2026 22:00
Copilot AI balanced review requested due to automatic review settings November 13, 2026 22:00

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🟡 Changes recommended

The retry generator relies on the merge SHA and can incorrectly treat a reverted backport as active, suppressing all new backport attempts.

1 open issue
What changed in this PR

Adds preview-first release backport tooling and maintainer guidance for WSL, without changing runtime components or adding package dependencies.

Changes:

  • Adds helpers to create independent backport PRs and update original PR labels after completion.
  • Adds shared remote validation, provenance detection, and revert handling, with automated tests.
  • Documents preview, authorization, validation, and recovery workflows in a guide and repository skill.
File Description
tools/​devops/​test_backports.py Tests helper behavior, safety checks, retries, and revert detection.
tools/​devops/​relabel_backported.py Previews and applies completed-backport label updates.
tools/​devops/​gen_cherrypick_prs.py Previews and creates independent cherry-pick PRs.
tools/​devops/​backport_utils.py Shares selection, remote validation, provenance, and template helpers.
doc/​mkdocs.yml Adds the backport guide to documentation navigation.
doc/​docs/​release-backports.md Documents the maintainer backport workflow and recovery steps.
.github/​skills/​wsl-release-backports/​SKILL.md Defines assistant workflow guidance and authorization boundaries.

Review effort: Balanced

Comment thread tools/devops/backport_utils.py Resolved
Verify recognizable source provenance at the backport merge instead of treating the surviving merge SHA as proof that its change remains active.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 98cc0b78-dd28-46e2-bc0a-5ae7950ae5ce
Copilot AI balanced review requested due to automatic review settings November 13, 2026 22:54

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🔵 Needs a closer look

The revert-history walk mishandles repeated-target histories, causing needed backports to be skipped or restored fixes to remain pending.

No open issues 🎉

1 previously missed issue

In code that hasn't changed since last review

Medium severity Repeated-target revert histories misclassify fix status

tools/​devops/​backport_utils.py:124

Cherry-picking S as P1, reverting P1, reapplying S as P2, then reverting P1 again removes the fix, but this walk still counts S through P2; the relabeler marks it completed and the generator skips the needed retry. Repeated-target histories involving a revert-of-revert can also leave a restored fix incorrectly pending because the source is excluded at lines 112–113. Track applications and reverts together, or stop for manual review on ambiguous repeated-target histories, with regression cases for both outcomes.

1 resolved since last review

Review effort: Balanced

Avoid misclassifying reapplications and repeated reversals. Parse canonical Git Revert and Reapply metadata so quoted historical bodies in squash messages do not block release previews.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 98cc0b78-dd28-46e2-bc0a-5ae7950ae5ce
Copilot AI balanced review requested due to automatic review settings November 13, 2026 23:11

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🟡 Changes recommended

The revert matcher rejects squash-merged subjects with PR-number suffixes, causing needed backports to be skipped and reverted fixes to be incorrectly marked completed.

1 open issue

Review effort: Balanced

Comment thread tools/devops/backport_utils.py Resolved
Keep canonical revert matching anchored while accepting the PR-number suffix added by GitHub, with retry and label regression coverage for reverted and restored changes.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 98cc0b78-dd28-46e2-bc0a-5ae7950ae5ce
Copilot AI balanced review requested due to automatic review settings November 13, 2026 23:21

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🔵 Needs a closer look

Human assessment is needed because ambiguous provenance can cause unapplied changes to be skipped, while pushes may publish tags beyond the previewed branch.

No open issues 🎉

1 resolved since last review

Review effort: Balanced

Override push.followTags so applying a preview publishes only its explicit branch. Verify the behavior with a real push to a local bare remote.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 98cc0b78-dd28-46e2-bc0a-5ae7950ae5ce
Copilot AI balanced review requested due to automatic review settings November 13, 2026 23:32

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🔵 Needs a closer look

Human assessment is needed because quoted annotations and partial reverts can cause provenance to be misinterpreted, leading to skipped or repeated backports and incorrect completion labels.

No open issues 🎉

Review effort: Balanced

Comment thread tools/devops/gen_cherrypick_prs.py Resolved
Comment thread tools/devops/backport_utils.py Resolved
Comment thread tools/devops/backport_utils.py Outdated
sha = identity[0]
# Squash messages can quote old revert bodies without reverting anything.
reversal = re.match(
r'(?:(?:Revert|Reapply) "[^\n]*"(?: \(#[1-9][0-9]*\))?\n\n)?'

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

This feels a bit brittle and will require exact word match in the commit.

Instead of doing this, we could look at pull requests that targeted the backport branch and consider all of those a backport

Comment thread tools/devops/backport_utils.py Resolved
Comment thread tools/devops/backport_utils.py Resolved
Comment thread tools/devops/test_backports.py Resolved
Use Click and injected GitPython repositories, preserve the PR template without exact-heading matching, and cover orchestration with repo mocks while retaining real Git regressions.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 98cc0b78-dd28-46e2-bc0a-5ae7950ae5ce
Copilot AI balanced review requested due to automatic review settings November 16, 2026 21:45
Comment thread tools/devops/gen_cherrypick_prs.py Fixed
Comment thread tools/devops/relabel_backported.py Fixed

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🟡 Changes recommended

Critical gaps in revert detection can leave removed fixes marked present, causing backport generation to skip missing fixes and relabeling to mark them completed.

3 open issues

Review effort: Balanced

Comment thread tools/devops/backport_utils.py Resolved
Comment thread tools/devops/backport_utils.py Outdated
Comment on lines +115 to +116
targets = [reversal.group(1)] if reversal else []
if any(target in seen_targets for target in targets):
Comment thread tools/devops/backport_utils.py Resolved
Recognize generated squash revert subjects and guard alias reversals, out-of-history targets, and reverted constituents of inherited source merges. Preserve ordinary backport retries and make empty command results explicit.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 98cc0b78-dd28-46e2-bc0a-5ae7950ae5ce
Copilot AI balanced review requested due to automatic review settings November 17, 2026 18:23

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🔵 Needs a closer look

Human assessment is needed because quoted cherry-pick markers and complex revert/reapplication histories can falsely indicate that fixes are present, causing needed backports to be skipped and pending labels to be removed incorrectly.

1 open issue
2 resolved since last review

Review effort: Balanced

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🟡 Changes recommended

Critical merge and revert tracking errors can cause both helpers to mark absent or incomplete backports as complete.

4 open issues

Review effort: Max

Comment on lines +136 to +139
if sha in reverted or any(source in reverted for source in sources[sha]):
continue
present.add(sha)
present.update(sources[sha])
active_targets.update(aliases.get(target, {target}))
reverted.update(targets)
for source in source_commits:
if source not in present or len(parents.get(source, ())) < 2:
Comment on lines +101 to +103
if __name__ == "__main__":
try:
main()

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants