Skip to content

Commit 316bb29

Browse files
committed
pull-requests.md: add guidance for large and/or automatic edits
This primarily came out of the discussion around allowing the use of LLMs (kubernetes/steering#291), but isn't limited to it because other tools (search/replace, linters) can have the same effect. The goal is to clarify expected behavior and to give reviewers something that they can link to when they decide that a PR shouldn't get merged.
1 parent eeaf3e9 commit 316bb29

File tree

1 file changed

+27
-1
lines changed

1 file changed

+27
-1
lines changed

contributors/guide/pull-requests.md

Lines changed: 27 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,8 @@ It should serve as a reference for all contributors, and be useful especially to
3535
- [It's OK to Push Back](#its-ok-to-push-back)
3636
- [Common Sense and Courtesy](#common-sense-and-courtesy)
3737
- [Trivial Edits](#trivial-edits)
38+
- [Large or Automatic Edits](#large-or-automatic-edits)
39+
- [Fixing Linter Issues](#fixing-linter-issues)
3840
- [The Testing and Merge Workflow](#the-testing-and-merge-workflow)
3941
- [More About `Ok-To-Test`](#more-about-ok-to-test)
4042

@@ -590,7 +592,31 @@ at once to that file.
590592
* Can the file be improved further?
591593
* Does the trivial edit greatly improve the quality of the content?
592594

593-
## Fixing linter issues
595+
## Large or Automatic Edits
596+
597+
Some tools make it very easy to create large Pull Requests, for example:
598+
- global search/replace
599+
- linters which automatically correct issues (see also next section)
600+
- large language models (LLMs) which generate code or documentation
601+
602+
To make it easier for reviewers to handle such Pull Requests, please explain
603+
how it was generated in the "Special notes for your reviewer" section of the
604+
Pull Request description. Reviewers may then be able to reproduce those steps
605+
(search/replace, linters) or can start the review with the right expectations
606+
(LLMs).
607+
608+
Even with such tools it is still your responsibility as submitter of a Pull
609+
Request to ensure that the change is correct (to the best of your knowledge),
610+
and that making the change improves the project enough to justify the cost that
611+
is needed to review and merge the Pull Request (see previous section). If
612+
unsure, add a "RFC: " (request for comments) or "WIP: " (work in progress) prefix
613+
to the subject of the Pull Request and ask for guidance.
614+
615+
Please understand that reviewers may decide to close a Pull Request with a
616+
reference to this documentation if they come to the conclusion that the Pull
617+
Request is not worth the effort.
618+
619+
## Fixing Linter Issues
594620

595621
Kubernetes has a set of linter checks. Some of those must pass in the entire
596622
code base, some must pass in new or modified code, and some are merely hints

0 commit comments

Comments
 (0)