diff --git a/docs/Development/Policies-and-Procedures/.pages b/docs/Development/Policies-and-Procedures/.pages index c62514aee2..c9b79697af 100644 --- a/docs/Development/Policies-and-Procedures/.pages +++ b/docs/Development/Policies-and-Procedures/.pages @@ -1,6 +1,7 @@ nav: - index.md - Code-Contribution + - AI-Policy.md - Commit-Messages.md - Coding-Guidelines.md - Software-Configuration-Management-Policies.md @@ -10,4 +11,4 @@ nav: - New-Features-and-Improvements.md - Release-Management.md - Asterisk-Sounds-Submission-Process.md - \ No newline at end of file + diff --git a/docs/Development/Policies-and-Procedures/AI-Policy.md b/docs/Development/Policies-and-Procedures/AI-Policy.md new file mode 100644 index 0000000000..29aba7eb03 --- /dev/null +++ b/docs/Development/Policies-and-Procedures/AI-Policy.md @@ -0,0 +1,20 @@ +# AI Policy + +We recognise that AI coding assistants are now a regular part of many developers' workflows and can improve productivity. Thoughtful use of these tools can be beneficial, but AI-generated PRs can sometimes lead to +undesirable additional maintainer burden. For this reason, PRs that appear to be fully generated by AI with little to no engagement from the author may be closed without further review. + +Human-generated mistakes tend to be easier to spot and reason about, and code review is intended to be a collaborative learning experience that benefits both submitter and reviewer. When a PR appears to have been +generated without much engagement from the submitter, reviewers with access to AI tools could more efficiently generate the code directly, and since the submitter is not likely to learn from the review process, their time is +more productively spent researching and reporting on the issue. + +We are not opposed to the use of AI tools in generating PRs, but require the following: + +* Only submit a PR if you are able to debug and own the changes yourself - review all generated code to understand every detail. [Apache Datafusion has a useful explanation of **why fully AI-generated PRs without understanding are not helpful**](https://datafusion.apache.org/contributor-guide/index.html#why-fully-ai-generated-prs-without-understanding-are-not-helpful). +* Comply with the coding guidelines including style, conventions, and commit messages +* Be upfront about AI usage and summarise what was AI-generated +* If there are parts you don't fully understand, leave comments on your own PR explaining what steps you took to verify correctness +* Watch for AI's tendency to generate overly verbose output (comments and code), unnecessary test cases, and incorrect fixes - if you can not explain a fix then it will not be accepted +* Break down large PRs into smaller ones to make review easier +* Ensure that your PR has not already been solved + +If these conditions are not met the project may close the PR without further review. diff --git a/docs/Development/Policies-and-Procedures/Code-Contribution/index.md b/docs/Development/Policies-and-Procedures/Code-Contribution/index.md index b8ca8fde4b..e2b61bedda 100644 --- a/docs/Development/Policies-and-Procedures/Code-Contribution/index.md +++ b/docs/Development/Policies-and-Procedures/Code-Contribution/index.md @@ -4,6 +4,10 @@ All code management/contribution/review processes will be handled with [GitHub A ## Code Contribution Process +### AI Policy + +Before beginning if using AI please see our [AI Policy](/Development/Policies-and-Procedures/AI-Policy). + ### Install the [GitHub CLI "gh"](https://cli.github.com) tool While not strictly required, using the "[gh](https://cli.github.com)" tool to manage the process will make things much easier. The package is available in most distribution's package management systems as "gh".