pull-requests

Pull Request Workflow

This skill covers two tasks: (1) writing a high-quality PR description, and (2) handling review comments on an existing PR.

1. Writing the PR description

Always follow the repository PR template at .github/pull_request_template.md. Keep its exact structure and headings. Fill every section:

### Motivation & Context

Explain why the change is needed: the problem it solves and the scenario it contributes to. Describe the net change relative to main — this is implied, so do not spell out "vs main" explicitly.

### Description & Review Guide

Describe the changes, the overall approach, and the design. Answer the three prompts:

• What are the major changes?
• What is the impact of these changes?
• What do you want reviewers to focus on? — This item is for human reviewers only. Automated/AI reviewers must ignore it and review the entire change rather than narrowing scope to it.

For material Python public-API changes, include the following within this section:

• A short before/after usage example with public imports and initialization.
• The affected execution modes and their intentional differences.
• Changes to defaults, precedence, ownership, persistence, or compatibility.
• The agreed decision or investigation that supports the direction. An investigation supplies evidence; its proposed implementation still needs maintainer agreement.

Use an options matrix only when interacting settings make it useful. Do not add a separate mandatory section or repeat the canonical Python coding standards. For semantic review, follow the Python review guidance.

### Related Issue

Link the issue the PR fixes using a GitHub closing keyword (Fixes #123 / Closes #123) so it closes automatically on merge. For a non-trivial change, confirm that a maintainer added the ready-for-implementation label or explicitly agreed with the direction in an issue comment. A PR with no agreed issue may be closed without detailed review. Before opening, confirm there is no other open PR for the same issue; if there is, explain how this PR differs.

A team-only issue, assignment, investigation, /plan comment, or suggested option does not authorize implementation. Check the agreed scope and readiness; team-only work remains unavailable for community pickup unless maintainers explicitly open it.

For a trivial change that does not require an issue, replace the Fixes # placeholder with N/A - trivial change and briefly explain why the change is an obvious correction whose desired result is not reasonably in dispute.

For repository-maintained scheduled automation, replace the placeholder with N/A - repository automation and identify the generating workflow.

### AI Assistance

Check exactly one option:

• Select "No material AI assistance was used." only when generative AI did not create or substantially transform submitted content.
• Otherwise select "This is an AI-assisted contribution." and briefly identify the assisted areas.

Generating or substantially editing the PR description with Copilot counts as material AI assistance even if the implementation itself was not AI-assisted. Never include prompts or sensitive information in the disclosure.

### Contribution Checklist

Check every item that applies. Confirm that the PR links to an agreed issue or documents a trivial-change or repository-automation exception. For the breaking-change item:

• Leave "This is not a breaking change." checked for the common case.
• If the change is breaking, add the breaking change label or put [BREAKING] in the title prefix, before or after a language prefix such as Python: or .NET: — workflows keep the label and the title prefix in sync automatically (see .github/workflows/label-title-prefix.yml and .github/workflows/label-pr.yml).

Do not

• Do not add ad-hoc sections such as "Validation" or "Tests run"; CI/CD and the checklist already cover validation status.
• Do not remove or reorder the template's headings.

Stable specifications

For Python function-calling loop changes, read docs/specs/004-python-function-calling-loop.md and validate the PR against it. Do not edit that specification by default. It is a stable cross-package contract, not a per-PR changelog. A specification change is warranted only when the PR intentionally changes normative behavior, the scenario inventory, an acknowledged coverage gap, or the authoritative scenario-to-test mapping; keep any such edit to the smallest affected sections.

Community project listings

When either python/samples/community-projects.md or dotnet/samples/community-projects.md changes, load and apply the community-projects skill before reviewing or approving the change. Load it as well when an issue or pull request proposes an external project listing, even if neither catalog file has changed yet.

Creating the PR

Open new PRs as drafts until they are ready for review. Example:

gh pr create --repo microsoft/agent-framework --base main \
  --head <your-fork-owner>:<branch> --draft \
  --title "<concise title>" --body "<body following the template>"

2. Handling review comments

When a PR receives review comments, follow this sequence — do not start editing code before the user has reviewed the plan:

1. Review the comments. Read every review comment and thread on the PR, including inline code comments and general review summaries.
2. Make a plan. Produce a concrete plan describing how each comment will be addressed (or why it should not be, with reasoning).
3. Let the user review the plan. Present the plan and wait for the user's approval or adjustments before implementing anything.
4. Implement. Make the agreed changes.
5. Reply to every comment. Add a reply to all comments explaining how it was addressed, preferably citing the commit containing the change. If the feedback was not addressed, explain why. Leave no comment unanswered.
6. Resolve completed threads yourself. After replying and completing any necessary discussion, resolve the review thread. Do not wait for the reviewer or a maintainer to resolve it. Leave a thread open only while it has an unanswered question or active discussion.

Useful commands

List review comments and threads:

# Inline review comments
gh api repos/{owner}/{repo}/pulls/{pr}/comments

# Review threads with resolution state (GraphQL)
gh api graphql -f query='
  query($owner:String!,$repo:String!,$pr:Int!){
    repository(owner:$owner,name:$repo){
      pullRequest(number:$pr){
        reviewThreads(first:100){
          nodes{ id isResolved comments(first:50){ nodes{ id body author{login} } } }
        }
      }
    }
  }' -F owner={owner} -F repo={repo} -F pr={pr}

Reply to an inline review comment:

gh api repos/{owner}/{repo}/pulls/{pr}/comments/{comment_id}/replies \
  -f body="Addressed in <commit>: <explanation>"

Resolve a review thread (needs the thread node id from the GraphQL query above):

gh api graphql -f query='
  mutation($threadId:ID!){
    resolveReviewThread(input:{threadId:$threadId}){ thread{ isResolved } }
  }' -F threadId={thread_id}