diff --git a/docs/source/developers/guide/index.rst b/docs/source/developers/guide/index.rst index 0ed27a0ddc5..c8d3103ca78 100644 --- a/docs/source/developers/guide/index.rst +++ b/docs/source/developers/guide/index.rst @@ -141,7 +141,9 @@ of adding a basic feature. #. **Push the branch on your fork and create a Pull Request** - See detailed instructions on :ref:`create_pr` + See detailed instructions on :ref:`create_pr`. If you have used AI tools + to help generate your contribution, please also read our guidance on + :ref:`ai-generated-code`. If you are ready you can start with building Arrow or choose to follow diff --git a/docs/source/developers/overview.rst b/docs/source/developers/overview.rst index 7e38dcb8ebc..a6445aaccde 100644 --- a/docs/source/developers/overview.rst +++ b/docs/source/developers/overview.rst @@ -146,6 +146,45 @@ will merge the pull request. This is done with a description, a link back to the pull request, and attribution to the contributor and any co-authors. +.. _ai-generated-code: + +AI-generated code ++++++++++++++++++ + +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. 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 recommend +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 +* Match the style and conventions used in the rest of the codebase, including + PR titles and descriptions +* 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 comments, unnecessary + test cases, and incorrect fixes +* Break down large PRs into smaller ones to make review easier + +PR authors are also responsible for disclosing any copyrighted materials in +submitted contributions. See the `ASF's guidance on AI-generated code +`_ for further +information on licensing considerations. + .. Section on Experimental repositories: .. include:: experimental_repos.rst