diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 29aae926450..25070cfc846 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -1,4 +1,4 @@ -blank_issues_enabled: true +blank_issues_enabled: false contact_links: - name: Documentation url: https://aka.ms/agent-framework @@ -6,3 +6,6 @@ contact_links: - name: Discussions url: https://github.com/microsoft/agent-framework/discussions about: Ask questions about Agent Framework. + - name: Security Vulnerability + url: https://github.com/microsoft/agent-framework/security/policy + about: Report security vulnerabilities privately. diff --git a/.github/ISSUE_TEMPLATE/dotnet-issue.yml b/.github/ISSUE_TEMPLATE/dotnet-issue.yml index 71c461ac466..9842d4494fd 100644 --- a/.github/ISSUE_TEMPLATE/dotnet-issue.yml +++ b/.github/ISSUE_TEMPLATE/dotnet-issue.yml @@ -1,44 +1,63 @@ name: .NET Bug Report -description: Report a bug in the Agent Framework .NET SDK +description: Report a reproducible bug in the Agent Framework .NET SDK title: ".NET: [Bug]: " labels: [".NET"] type: bug body: + - type: markdown + attributes: + value: | + Use this form for reproducible defects. Ask usage questions in + [Discussions](https://github.com/microsoft/agent-framework/discussions). + + - type: textarea + id: observed-behavior + attributes: + label: Observed Behavior + description: What happened? + placeholder: Describe the incorrect behavior and its impact. + validations: + required: true + - type: textarea - id: description + id: expected-behavior attributes: - label: Description - description: Please provide a clear and detailed description of the bug. + label: Expected Behavior + description: What did you expect to happen? + placeholder: Describe the expected result. + validations: + required: true + + - type: textarea + id: reproduction-steps + attributes: + label: Steps to Reproduce + description: Provide the smallest reliable sequence that reproduces the problem. placeholder: | - - What happened? - - What did you expect to happen? - - Steps to reproduce the issue + 1. Configure ... + 2. Run ... + 3. Observe ... validations: required: true - type: textarea - id: code-sample + id: minimal-reproduction attributes: - label: Code Sample - description: If applicable, provide a minimal code sample that demonstrates the issue. + label: Minimal Reproduction + description: Provide minimal code or a repository link. If unavailable, explain why. placeholder: | ```csharp - // Your code here + // Minimal code that reproduces the problem ``` - render: markdown validations: - required: false + required: true - type: textarea id: error-messages attributes: - label: Error Messages / Stack Traces - description: Include any error messages or stack traces you received. - placeholder: | - ``` - Paste error messages or stack traces here - ``` - render: markdown + label: Error Messages and Stack Traces + description: Include the complete relevant error output after removing credentials, authorization headers, signed URLs, personal data, internal endpoints, and other sensitive values. + render: text validations: required: false @@ -46,8 +65,8 @@ body: id: dotnet-packages attributes: label: Package Versions - description: List the Microsoft.Agents.* packages and versions you are using - placeholder: "e.g., Microsoft.Agents.AI.Abstractions: 1.0.0, Microsoft.Agents.AI.OpenAI: 1.0.0" + description: List the Microsoft.Agents.* packages and exact versions you are using. + placeholder: "Microsoft.Agents.AI: 1.0.0" validations: required: true @@ -56,15 +75,50 @@ body: attributes: label: .NET Version description: What version of .NET are you using? - placeholder: "e.g., .NET 8.0" + placeholder: ".NET 10.0" validations: - required: false + required: true + + - type: dropdown + id: operating-system + attributes: + label: Operating System + options: + - Windows + - macOS + - Linux + - Other + validations: + required: true + + - type: dropdown + id: regression + attributes: + label: Regression + description: Did this work in an earlier Agent Framework version? + options: + - "Yes" + - "No" + - Unknown + validations: + required: true - type: textarea id: additional-context attributes: label: Additional Context - description: Add any other context or screenshots that might be helpful. - placeholder: "Any additional information..." + description: Add any other relevant context, logs, or screenshots. validations: required: false + + - type: checkboxes + id: acknowledgements + attributes: + label: Acknowledgements + options: + - label: I searched existing issues and did not find a duplicate. + required: true + - label: I personally verified this behavior and the reproduction details are authentic. + required: true + - label: I will wait for explicit maintainer agreement before starting implementation of a non-trivial change. + required: true diff --git a/.github/ISSUE_TEMPLATE/feature-request.yml b/.github/ISSUE_TEMPLATE/feature-request.yml index 1dc13189e73..3125eefc07a 100644 --- a/.github/ISSUE_TEMPLATE/feature-request.yml +++ b/.github/ISSUE_TEMPLATE/feature-request.yml @@ -1,46 +1,73 @@ name: Feature Request -description: Request a new feature for Microsoft Agent Framework +description: Propose a new capability for Microsoft Agent Framework title: "[Feature]: " type: feature body: + - type: markdown + attributes: + value: | + Describe the problem before proposing implementation. Filing an issue does + not reserve the work or approve a pull request. + + - type: textarea + id: problem + attributes: + label: Problem + description: What concrete problem or limitation are you experiencing? + placeholder: Describe the current limitation and who it affects. + validations: + required: true - type: textarea - id: description + id: use-case attributes: - label: Description - description: Please describe the feature you'd like and why it would be useful. - placeholder: | - Describe the feature you're requesting: - - What problem does it solve? - - What would the expected behavior be? - - Are there any alternatives you've considered? + label: Use Case and Evidence + description: Provide a real scenario, example, or other evidence that demonstrates the need. + placeholder: Explain what you are trying to accomplish and why the current APIs or guidance are insufficient. validations: required: true - type: textarea - id: code-sample + id: desired-outcome attributes: - label: Code Sample - description: If applicable, provide a code sample showing how you'd like to use this feature. - placeholder: | - ```python - # Your code here - ``` + label: Desired Outcome + description: Describe the behavior or capability you need without prescribing implementation details. + placeholder: What should a successful outcome allow users to do? + validations: + required: true - or + - type: textarea + id: alternatives + attributes: + label: Alternatives Considered + description: What existing features, workarounds, or alternative approaches have you considered? + placeholder: Describe what you tried and why it did not meet the need. + validations: + required: true + + - type: textarea + id: proposed-direction + attributes: + label: Proposed Direction + description: If you have a proposed API or design direction, describe it here. + placeholder: Optional implementation or API ideas. + validations: + required: false - ```csharp - // Your code here - ``` - render: markdown + - type: textarea + id: scope + attributes: + label: Scope and Non-Goals + description: Identify important boundaries or related work that should not be included. + placeholder: Optional scope constraints and non-goals. validations: required: false - type: dropdown id: language attributes: - label: Language/SDK - description: Which language/SDK does this feature apply to? + label: Language + description: Which implementation does this request apply to? options: - Both - .NET @@ -48,4 +75,26 @@ body: - Other / Not Applicable default: 0 validations: - required: false + required: true + + - type: dropdown + id: contribution-intent + attributes: + label: Contribution Intent + description: Would you be interested in implementing this after maintainer agreement? + options: + - I am willing to implement this + - I can help with implementation or testing + - I am only requesting the feature + validations: + required: true + + - type: checkboxes + id: acknowledgements + attributes: + label: Acknowledgements + options: + - label: I searched existing issues and did not find a duplicate. + required: true + - label: I will wait for explicit maintainer agreement before starting implementation of a non-trivial change. + required: true diff --git a/.github/ISSUE_TEMPLATE/general-issue.yml b/.github/ISSUE_TEMPLATE/general-issue.yml new file mode 100644 index 00000000000..621d7ab95c9 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/general-issue.yml @@ -0,0 +1,77 @@ +name: Other Issue +description: Report a documentation, process, or repository problem +title: "[Issue]: " +type: task +body: + - type: markdown + attributes: + value: | + Use this form for problems that are not SDK bugs or feature requests. + Ask usage questions in + [Discussions](https://github.com/microsoft/agent-framework/discussions). + Report security vulnerabilities according to + [SECURITY.md](https://github.com/microsoft/agent-framework/security/policy). + + - type: dropdown + id: category + attributes: + label: Category + options: + - Documentation + - Build or CI + - Repository maintenance + - Contribution process + - Other + validations: + required: true + + - type: textarea + id: problem + attributes: + label: Problem + description: What is incorrect, missing, or difficult? + placeholder: Describe the problem and its impact. + validations: + required: true + + - type: textarea + id: evidence + attributes: + label: Evidence + description: Provide links, examples, screenshots, or reproduction steps that demonstrate the problem. + placeholder: Include enough information for a maintainer to verify the issue. + validations: + required: true + + - type: textarea + id: desired-outcome + attributes: + label: Desired Outcome + description: What should change? + placeholder: Describe the expected result without assuming a particular implementation. + validations: + required: true + + - type: dropdown + id: language + attributes: + label: Language + description: Which implementation does this issue affect? + options: + - Both + - .NET + - Python + - Not Applicable + default: 3 + validations: + required: true + + - type: checkboxes + id: acknowledgements + attributes: + label: Acknowledgements + options: + - label: I searched existing issues and did not find a duplicate. + required: true + - label: I will wait for explicit maintainer agreement before starting implementation of a non-trivial change. + required: true diff --git a/.github/ISSUE_TEMPLATE/python-issue.yml b/.github/ISSUE_TEMPLATE/python-issue.yml index 84c421fefa5..83dfc3f8617 100644 --- a/.github/ISSUE_TEMPLATE/python-issue.yml +++ b/.github/ISSUE_TEMPLATE/python-issue.yml @@ -1,44 +1,63 @@ name: Python Bug Report -description: Report a bug in the Agent Framework Python SDK +description: Report a reproducible bug in the Agent Framework Python SDK title: "Python: [Bug]: " labels: ["Python"] type: bug body: + - type: markdown + attributes: + value: | + Use this form for reproducible defects. Ask usage questions in + [Discussions](https://github.com/microsoft/agent-framework/discussions). + + - type: textarea + id: observed-behavior + attributes: + label: Observed Behavior + description: What happened? + placeholder: Describe the incorrect behavior and its impact. + validations: + required: true + - type: textarea - id: description + id: expected-behavior attributes: - label: Description - description: Please provide a clear and detailed description of the bug. + label: Expected Behavior + description: What did you expect to happen? + placeholder: Describe the expected result. + validations: + required: true + + - type: textarea + id: reproduction-steps + attributes: + label: Steps to Reproduce + description: Provide the smallest reliable sequence that reproduces the problem. placeholder: | - - What happened? - - What did you expect to happen? - - Steps to reproduce the issue + 1. Configure ... + 2. Run ... + 3. Observe ... validations: required: true - type: textarea - id: code-sample + id: minimal-reproduction attributes: - label: Code Sample - description: If applicable, provide a minimal code sample that demonstrates the issue. + label: Minimal Reproduction + description: Provide minimal code or a repository link. If unavailable, explain why. placeholder: | ```python - # Your code here + # Minimal code that reproduces the problem ``` - render: markdown validations: - required: false + required: true - type: textarea id: error-messages attributes: - label: Error Messages / Stack Traces - description: Include any error messages or stack traces you received. - placeholder: | - ``` - Paste error messages or stack traces here - ``` - render: markdown + label: Error Messages and Stack Traces + description: Include the complete relevant error output after removing credentials, authorization headers, signed URLs, personal data, internal endpoints, and other sensitive values. + render: text validations: required: false @@ -46,8 +65,8 @@ body: id: python-packages attributes: label: Package Versions - description: List the agent-framework-* packages and versions you are using - placeholder: "e.g., agent-framework-core: 1.0.0, agent-framework-foundry: 1.0.0" + description: List the agent-framework-* packages and exact versions you are using. + placeholder: "agent-framework-core: 1.0.0" validations: required: true @@ -56,15 +75,50 @@ body: attributes: label: Python Version description: What version of Python are you using? - placeholder: "e.g., Python 3.11" + placeholder: "Python 3.13" validations: - required: false + required: true + + - type: dropdown + id: operating-system + attributes: + label: Operating System + options: + - Windows + - macOS + - Linux + - Other + validations: + required: true + + - type: dropdown + id: regression + attributes: + label: Regression + description: Did this work in an earlier Agent Framework version? + options: + - "Yes" + - "No" + - Unknown + validations: + required: true - type: textarea id: additional-context attributes: label: Additional Context - description: Add any other context or screenshots that might be helpful. - placeholder: "Any additional information..." + description: Add any other relevant context, logs, or screenshots. validations: required: false + + - type: checkboxes + id: acknowledgements + attributes: + label: Acknowledgements + options: + - label: I searched existing issues and did not find a duplicate. + required: true + - label: I personally verified this behavior and the reproduction details are authentic. + required: true + - label: I will wait for explicit maintainer agreement before starting implementation of a non-trivial change. + required: true diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index a790437b7e0..00a20f98e29 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -26,12 +26,32 @@ Please help reviewers and future users, providing the following information: + explain how this PR is different. + For a trivial change that does not need an issue, replace "Fixes #" below with + "N/A - trivial change" and briefly explain why. + For repository-maintained scheduled automation, replace it with + "N/A - repository automation" and identify the generating workflow. --> Fixes # +### AI Assistance + + + +- [ ] No material AI assistance was used. +- [ ] This is an AI-assisted contribution. I reviewed, understood, and verified all submitted content and accept responsibility for it. + + + +AI assistance details: + ### Contribution Checklist @@ -39,5 +59,5 @@ Fixes # - [ ] The code builds clean without any errors or warnings - [ ] All unit tests pass, and I have added new tests where possible - [ ] The PR follows the [Contribution Guidelines](https://github.com/microsoft/agent-framework/blob/main/CONTRIBUTING.md) -- [ ] This PR is linked to an issue and there is no other open PR for this issue (see Related Issue above). +- [ ] This PR links to an agreed issue with no competing open PR, or the Related Issue section documents a trivial-change or repository-automation exception. - [x] **This is not a breaking change.** If it _is_ a breaking change, add the `breaking change` label (or add "[BREAKING]" to the title prefix, before or after any language prefix) — a workflow keeps the label and title prefix in sync automatically. diff --git a/.github/skills/pull-requests/SKILL.md b/.github/skills/pull-requests/SKILL.md index cd724366bff..1dbfa1951a8 100644 --- a/.github/skills/pull-requests/SKILL.md +++ b/.github/skills/pull-requests/SKILL.md @@ -34,12 +34,34 @@ prompts: ### `### Related Issue` Link the issue the PR fixes using a GitHub closing keyword (`Fixes #123` / -`Closes #123`) so it closes automatically on merge. A PR with no linked issue may -be closed regardless of how valid the change is. Before opening, confirm there is -no other open PR for the same issue; if there is, explain how this PR differs. +`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. + +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. For the breaking-change item: +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 diff --git a/.github/workflows/python-dependency-maintenance.yml b/.github/workflows/python-dependency-maintenance.yml index 54517579643..fdc4f5b5892 100644 --- a/.github/workflows/python-dependency-maintenance.yml +++ b/.github/workflows/python-dependency-maintenance.yml @@ -357,14 +357,21 @@ jobs: "", "### Related Issue", "", - "No linked issue; this PR is generated by scheduled Python dependency maintenance.", + "N/A - repository automation generated by `.github/workflows/python-dependency-maintenance.yml`.", + "", + "### AI Assistance", + "", + "- [x] No material AI assistance was used.", + "- [ ] This is an AI-assisted contribution. I reviewed, understood, and verified all submitted content and accept responsibility for it.", + "", + "AI assistance details: N/A", "", "### Contribution Checklist", "", "- [x] The code builds clean without any errors or warnings", "- [x] All unit tests pass, and I have added new tests where possible", "- [x] The PR follows the [Contribution Guidelines](https://github.com/microsoft/agent-framework/blob/main/CONTRIBUTING.md)", - "- [ ] This PR is linked to an issue and there is no other open PR for this issue (see Related Issue above).", + "- [x] This PR links to an agreed issue with no competing open PR, or the Related Issue section documents a trivial-change or repository-automation exception.", '- [x] **This is not a breaking change.** If it _is_ a breaking change, add the `breaking change` label (or add "[BREAKING]" to the title prefix, before or after any language prefix) — a workflow keeps the label and title prefix in sync automatically.', ].join("\n") diff --git a/AI_CONTRIBUTIONS.md b/AI_CONTRIBUTIONS.md new file mode 100644 index 00000000000..e94e69b1c9d --- /dev/null +++ b/AI_CONTRIBUTIONS.md @@ -0,0 +1,120 @@ +# AI-Assisted Contributions Policy + +AI tools may be used to prepare contributions to Microsoft Agent Framework. Their +use does not lower the project's quality bar, transfer responsibility to the +tool, or create an entitlement to review or acceptance. + +This policy applies to issues, pull requests, code, tests, documentation, +samples, and other content submitted to this repository. It supplements the +[Contribution Guidelines](./CONTRIBUTING.md), [Code of Conduct](./CODE_OF_CONDUCT.md), +and [Security Policy](./SECURITY.md). + +## What Counts as AI-Assisted + +A contribution is materially AI-assisted when a generative AI tool creates or +substantially transforms content that is submitted to the repository. This can +include code, tests, documentation, designs, issue reports, and pull request +descriptions. + +Routine spelling or grammar correction, formatting, search, and short editor +completions do not need to be disclosed unless the generated output materially +shaped the contribution. + +## Contributor Responsibilities + +### Disclose Material AI Assistance + +Disclose material AI assistance in the issue or pull request description. For a +pull request, complete the **AI Assistance** section of the pull request +template and check exactly one option. Briefly identify the parts of the +contribution that were assisted, such as the issue analysis, implementation, +tests, documentation, or proposed design. Do not include prompts, credentials, +private data, or other sensitive information in the disclosure. + +Disclosure is not a mark against a contribution. It gives reviewers useful +context and confirms that the contributor accepts responsibility for the +submitted work. + +### Understand and Own the Contribution + +The human contributor remains the accountable submitter. Contributors must: + +- Review all submitted content rather than forwarding generated output. +- Understand the behavior, design, and consequences of the change. +- Be able to explain the change and respond to review feedback themselves. +- Make requested revisions and maintain the contribution through review. + +"The AI generated it" is not an explanation for a design choice, defect, or +unnecessary change. + +### Verify Correctness and Quality + +AI-assisted contributions must meet the same standards as any other +contribution. Before submission, contributors must: + +- Confirm that the change addresses a real, documented problem. +- Personally verify reported behavior and provide authentic reproduction details. +- Validate APIs, facts, versions, links, examples, and technical claims. +- Run the relevant builds, tests, formatting, and static analysis. +- Add meaningful tests when behavior changes. +- Remove unrelated changes, speculative abstractions, and generated churn. +- Check that comments and documentation describe the implemented behavior. + +Generated tests are not sufficient merely because they pass. They must exercise +the intended behavior and be capable of detecting a broken implementation. + +### Protect Confidential and Security-Sensitive Information + +Do not provide an AI service with secrets, credentials, personal data, private +source code, non-public telemetry, embargoed vulnerabilities, or other +confidential information unless you are explicitly authorized to do so. + +Security vulnerabilities must be reported through the process in +[SECURITY.md](./SECURITY.md), not through public issues, pull requests, or AI +service transcripts. + +Contributors are responsible for complying with applicable organizational +policies and the terms of the AI tools they use. + +### Respect Licensing and Provenance + +Contributors must have the right to submit all content under the repository's +[license](./LICENSE). Review generated content for copied or closely reproduced +third-party code, text, notices, or other material whose license is incompatible +with this repository. + +AI tool output does not remove attribution or licensing obligations. If the +origin or licensing of generated material is unclear, do not submit it. + +### Follow the Contribution Workflow + +AI tools make it inexpensive to produce changes. They do not make those changes +necessary. + +For non-trivial changes, start with an issue and wait for a maintainer to add +the `ready-for-implementation` label or explicitly agree with the direction +before starting implementation, as described in the +[Contribution Guidelines](./CONTRIBUTING.md). Keep each contribution focused on +one agreed problem. + +Do not use AI tools to produce: + +- Bulk or speculative pull requests. +- Duplicate or low-information issues. +- Broad refactors without prior agreement. +- Fabricated reproductions, benchmarks, citations, or test results. +- Changes that the contributor cannot explain or support through review. + +## Maintainer Response + +Maintainers evaluate the contribution, not the tool used to produce it. They may +ask for a reproduction, supporting evidence, a smaller scope, additional tests, +or a clearer explanation before reviewing implementation details. + +Contributions may be closed without detailed review when they do not follow this +policy or the Contribution Guidelines. This includes undisclosed material AI +assistance, unverified generated content, speculative changes without an +agreed issue, and repeated low-quality or high-volume submissions. + +This policy relies on honest disclosure rather than speculation about whether a +particular writing or coding style came from an AI tool. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f64cdbf4607..51bb09eac40 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -53,9 +53,42 @@ We welcome contributions, but maintainers must prioritize their limited review t across issues and pull requests, so we may not be able to get to reviewing every contribution immediately. -AI tooling has also made it easier for more people to -submit contributions, which has increased the overall volume we receive; as a -result, contributors should expect longer wait times for reviews. +AI tooling has also made it easier for more people to submit contributions, +which has increased the overall volume we receive. AI-assisted contributions +are permitted, but contributors remain responsible for understanding, verifying, +and supporting everything they submit. Review the +[AI-Assisted Contributions Policy](./AI_CONTRIBUTIONS.md) before submitting +materially AI-assisted work. Contributors should expect longer wait times for +reviews. + +### Before Opening a Pull Request + +Except for trivial changes, create or reuse an issue before starting +implementation. A trivial change is an obvious correction whose desired result +is not reasonably in dispute, such as fixing a typo or broken documentation +link. A small code diff is not automatically trivial. + +Repository-maintained scheduled automation may open recurring maintenance pull +requests without an issue when the pull request identifies the generating +workflow. + +For non-trivial changes: + +1. Search for an existing issue before creating a new one. +2. Describe the problem, supporting evidence or reproduction, desired outcome, + and relevant scope or alternatives. +3. Wait for a maintainer to add the `ready-for-implementation` label or + explicitly comment that the proposed direction is ready for implementation. + +Automated triage, issue assignment, reactions, and silence do not indicate +approval. Maintainer agreement means that a contribution is welcome for review; +it does not promise that a future pull request will be merged. + +Pull requests for non-trivial changes may be closed without detailed review when +they are neither linked to an agreed issue nor generated by +repository-maintained scheduled automation, or when they duplicate existing +work. For a trivial change without an issue, explain why it qualifies as trivial +in the pull request's **Related Issue** section. Note that your pull request may receive automated review comments from a bot; addressing or at least replying to those comments will help fast track the eventual human review. @@ -77,14 +110,17 @@ DO's: - **DO** keep the discussions focused. When a new or related topic comes up it's often better to create new issue than to side track the discussion. - **DO** clearly state on an issue that you are going to take on implementing it. +- **DO** wait for explicit maintainer agreement before implementing a non-trivial + change. - **DO** blog and tweet (or whatever) about your contributions, frequently! DON'Ts: -- **DON'T** surprise us with big pull requests. Instead, file an issue and start - a discussion so we can agree on a direction before you invest a large amount of time. -- **DON'T** commit code that you didn't write. If you find code that you think is a good - fit to add to Agent Framework, file an issue and start a discussion before proceeding. +- **DON'T** surprise us with non-trivial pull requests. File an issue and agree + on the problem and direction before investing in implementation. +- **DON'T** submit code or content whose origin, behavior, or licensing you cannot + verify. If you find third-party code that may fit Agent Framework, file an + issue and start a discussion before proceeding. - **DON'T** submit PRs that alter licensing related files or headers. If you believe there's a problem with them, file an issue and we'll be happy to discuss it. - **DON'T** make new APIs without filing an issue and discussing with us first. @@ -181,11 +217,9 @@ After a release, the `Promote Shipped APIs` workflow moves entries from `PublicA We use and recommend the following workflow: -1. Create an issue for your work. - - You can skip this step for trivial changes. - - Reuse an existing issue on the topic, if there is one. - - Get agreement from the team and the community that your proposed change is - a good one. +1. Complete the [issue-first process](#before-opening-a-pull-request). + - Skip the issue only for a trivial change as defined above. + - Reuse an existing issue on the topic when possible. - Clearly state that you are going to take on implementing it, if that's the case. You can request that the issue be assigned to you. Note: The issue filer and the implementer don't have to be the same person. @@ -197,7 +231,9 @@ We use and recommend the following workflow: 5. Add new tests corresponding to your change, if applicable. 6. Run the relevant scripts in [the section below](#development-setup) to ensure that your build is clean and all tests are passing. 7. Create a PR against the repository's **main** branch. - - State in the description what issue or improvement your change is addressing. + - Link the agreed issue with a closing keyword, or explain why the change is a + trivial exception. + - Complete the AI assistance disclosure in the pull request template. - Verify that all the Continuous Integration checks are passing. 8. Address feedback from the code maintainers. Reply to every review comment with the outcome and resolve each completed review conversation yourself before diff --git a/README.md b/README.md index d8ea282064f..c5b3b07d9b5 100644 --- a/README.md +++ b/README.md @@ -203,6 +203,7 @@ For environment variable configuration specific to each sample, refer to the REA ## Contributor Resources - [Contributing Guide](./CONTRIBUTING.md) +- [AI-Assisted Contributions Policy](./AI_CONTRIBUTIONS.md) - [Code of Conduct](./CODE_OF_CONDUCT.md) - [Python Development Guide](./python/DEV_SETUP.md) - [Design Documents](./docs/design) diff --git a/dotnet/.github/skills/pull-requests/SKILL.md b/dotnet/.github/skills/pull-requests/SKILL.md index 625001cd41e..9d8395cdabe 100644 --- a/dotnet/.github/skills/pull-requests/SKILL.md +++ b/dotnet/.github/skills/pull-requests/SKILL.md @@ -34,12 +34,34 @@ prompts: ### `### Related Issue` Link the issue the PR fixes using a GitHub closing keyword (`Fixes #123` / -`Closes #123`) so it closes automatically on merge. A PR with no linked issue may -be closed regardless of how valid the change is. Before opening, confirm there is -no other open PR for the same issue; if there is, explain how this PR differs. +`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. + +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. For the breaking-change item: +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 diff --git a/python/.github/skills/pull-requests/SKILL.md b/python/.github/skills/pull-requests/SKILL.md index 625001cd41e..9d8395cdabe 100644 --- a/python/.github/skills/pull-requests/SKILL.md +++ b/python/.github/skills/pull-requests/SKILL.md @@ -34,12 +34,34 @@ prompts: ### `### Related Issue` Link the issue the PR fixes using a GitHub closing keyword (`Fixes #123` / -`Closes #123`) so it closes automatically on merge. A PR with no linked issue may -be closed regardless of how valid the change is. Before opening, confirm there is -no other open PR for the same issue; if there is, explain how this PR differs. +`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. + +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. For the breaking-change item: +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